# Topdata Inheritance Contract

## Status Snapshot

Current state as of 2026-05-13:

- Implemented.
- `native.go` supports both row-sugar inheritance and generic object
  inheritance, including cycle detection and missing-target failures.
- Validation and build regression coverage live in `topdata_test.go`.

Native topdata now supports two inheritance forms:

## 1. Row Sugar Compatibility

This is the existing narrow row helper:

```json
{
  "PARENT": { "id": "custom:parent" },
  "inherit": {
    "from": "PARENT",
    "fields": ["VALUE", "ICON"]
  }
}
```

It remains supported for row-local field copying.

## 2. Generic Object Inheritance

This is the new reusable primitive:

```json
{
  "inherit": {
    "ref": "masterfeats:skillfocus"
  },
  "LABEL": "FEAT_SKILL_FOCUS_ATHLETICS"
}
```

Or for a nested object:

```json
{
  "DETAILS": {
    "inherit": {
      "ref": "custom:parent",
      "field": "DETAILS"
    },
    "meta": {
      "cost": "9"
    }
  }
}
```

## Rules

- `inherit.ref` must use stable `dataset:key` identity.
- `inherit.field` is optional and selects an object-valued field on the target row.
- Generic inheritance can appear on any authored object, not only top-level rows.
- Merge precedence is `local overrides inherited`.
- Scalars replace inherited values.
- Arrays replace inherited values.
- Objects merge recursively unless the local object is an atomic topdata value object such as:
  - TLK payloads
  - row refs
  - table refs
- Cycles fail the build.
- Missing targets fail the build.

## Current Intended Consumer

`feat` is the first dataset expected to use this primitive heavily, especially for
borrowing shared properties from `masterfeats` while keeping `feat`'s own dataset
contract and row model.
