Topdata Migration (#2)

Native topdata migration summary

- Replaced the legacy 2dabuilder runtime path with the native topdata builder.
- Native build, validate, compare, and convert flows now cover the canonical topdata pipeline.
- compare-topdata is now a native self-check; legacy reference-builder runtime usage was removed.
- Parts generation follows the native asset-scan contract and uses sow-assets via project asset resolution.
- Generated feat families, class-feat injects, masterfeat/successor expansion, and dataset-derived feat generation were brought to parity and regression-covered.
- Remaining mirrored datasets were migrated into native-owned canonical data while preserving lock IDs.
- normalize-topdata bridge behavior and migration-era ownership markers were removed.
- Documentation was rewritten around the native workflow and active contracts were cleaned up.
- Final hardening pass removed stale validator assumptions and cleaned ignored/generated artifacts for PR readiness.

Reviewed-on: https://gitea.westgate.pw/ShadowsOverWestgate/sow-tools/pulls/2
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
Co-committed-by: vickydotbat <vickydotbat@tutamail.com>

internal/topdata/FAMILY_EXPANSION_CONTRACT.md

@@ -0,0 +1,70 @@
+# 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.