# Generic Family Expansion Contract

Topdata now treats underscore expansion as a structural rule:

- `parent_child` means `child` is an expansion of `parent`
- underscores are for family structure, not simulated spaces
- existing canonical keys still win when lock or TLK state already established them

This is a global interpretation rule, not a wiki-only convention.

## Identity

- `weaponspecialization_club`
  - parent: `weaponspecialization`
  - child: `club`
- `gnome_rock`
  - parent: `gnome`
  - child: `rock`
- `toughness_10`
  - parent: `toughness`
  - child: `10`

Standalone keys without an underscore are treated as a parent identity with no child.

## Generated Family Files

Canonical generated families declare:

```json
{
  "family": "weapon_focus",
  "family_key": "weaponfocus",
  "template": "masterfeats:weaponfocus",
  "child_source": {
    "dataset": "baseitems",
    "column": "WeaponFocusFeat"
  }
}
```

Rules:

- `family` is the authored family type
- `family_key` is the structural parent identity used in generated child keys
- `template` is optional for the primitive in general, but required by current
  masterfeat-backed `feat` families
- `child_source.dataset` identifies the canonical dataset driving expansion
- `child_source.column` is used when expansion is gated by a non-null source field
- `child_source.predicate` is used when expansion depends on a named rule such as
  accessibility

## Row Metadata

Generated rows can carry:

```json
{
  "meta": {
    "family": {
      "parent": "weaponfocus",
      "child": "club",
      "source": "baseitems:club",
      "template": "masterfeats:weaponfocus"
    }
  }
}
```

This metadata is builder-owned and does not affect emitted 2DA columns. It preserves
family structure for later phases without enabling wiki generation yet.