# `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:

```json
{
  "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:

```json
{
  "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`.
