sow-tools/internal/topdata/MASTERFEATS_CONTRACT.md

masterfeats Canonical Contract

Status Snapshot

Current state as of 2026-05-13:

• Implemented as a first-class native dataset.
• The repository contains topdata/data/masterfeats/, migration/import support, validator checks, and native output coverage for masterfeats.2da.
• Remaining work is only downstream adoption and regression maintenance as other native datasets continue to consume masterfeats more heavily.

masterfeats is a stable native canonical family consumed directly by feat generation, class-feat expansion, and inheritance/ref resolution.

Current canonical scope:

• dataset root: topdata/data/masterfeats/
• required files:
  • base.json
  • lock.json
• generated output:
  • masterfeats.2da

base.json

Canonical shape:

{
  "output": "masterfeats.2da",
  "columns": ["LABEL", "STRREF", "DESCRIPTION", "..."],
  "rows": [
    {
      "id": 0,
      "key": "masterfeats:weaponfocus",
      "LABEL": "WeaponFocus",
      "STRREF": "6490",
      "DESCRIPTION": "436"
    }
  ]
}

Rules:

• output may be omitted; native dataset discovery deterministically derives masterfeats.2da from topdata/data/masterfeats/base.json
• if output is present, it must be exactly masterfeats.2da
• columns must include LABEL, STRREF, and DESCRIPTION
• every canonical row must have a non-empty key
• row keys must start with masterfeats:
• inline TLK payloads are allowed in STRREF and DESCRIPTION
• numeric/text references are both allowed where the native TLK compiler already supports them

lock.json

Canonical shape:

{
  "masterfeats:weaponfocus": 0
}

Rules:

• every key must start with masterfeats:
• every value must be numeric
• the lockfile remains the canonical stable id source for authored keys

Module contributions

This family continues to support the shared canonical module shapes already used by native datasets:

• columns
• entries
• overrides

Those shapes are validated generically in topdata.go; this contract only adds the family-specific guarantees for masterfeats.