Merge Phase V — docs cross-referenced to conformance fixtures

Each of the 8 feature docs gained a ## Verified by section listing the
conformance fixtures that gate the documented behavior. NEW docs/CONFORMANCE.md
is the inverse index: per-corpus totals, per-port pass status, fixture-to-doc
mapping. docs/README.md links to it.

138 fixtures cross-referenced across 5 active corpora:
- conformance/ (metamodel, 85)         — grouped under entities/field-types/
                                          source-kinds/relationships/templates/loaders
- yaml-conformance/ (6)                → yaml-authoring.md
- verify-conformance/ (31)             → migrations-and-drift.md
- render-conformance/ (4)              → templates-and-payloads.md
- persistence-conformance/ (12)        → migrations-and-drift.md + source-kinds.md

Zero orphans (no fixture without a feature doc, no feature without gating
fixtures). Codegen-conformance noted as deferred (FR-007).

The docs are now provably grounded in shipped tests, not aspirational —
LLMs reading a feature doc can verify the documented behavior by following
the fixture links and reading the expected.json + per-port runner outcomes.

Author: dmealing

docs/CONFORMANCE.md

@@ -0,0 +1,106 @@
+# Conformance coverage
+
+The MetaObjects standard has 5 cross-language conformance corpora plus a deferred
+6th (`codegen-conformance/`, tracked as FR-007). Every port runs every applicable
+corpus and asserts the same expected behavior against the same fixtures. **This
+page is the inverse index**: fixture → feature doc + per-port pass status.
+
+If you are coming from a feature doc's `## Verified by` section, you are in the
+right place. If you are wondering whether a particular fixture has a
+human-readable explanation somewhere, look it up in the
+"Fixture-to-doc mapping" table below.
+
+## Per-corpus totals
+
+| Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
+|---|---|---|---|---|---|---|
+| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 85 | 85 / 85 | 85 / 85 | inherits via `metadata-ktx` | source-v2 cluster + `doc-common-attrs-on-all-types` are open gaps | 91 / 91 (also gates loader extensions) |
+| [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 6 | 6 / 6 | 6 / 6 | inherits via Java | 6 / 6 | 6 / 6 |
+| [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 31 | 31 / 31 | 31 / 31 | inherits via Java | 31 / 31 | 31 / 31 |
+| [`fixtures/render-conformance/`](../fixtures/render-conformance/) | 4 | 4 / 4 | 4 / 4 | inherits via Java | 4 / 4 | 4 / 4 |
+| [`fixtures/persistence-conformance/`](../fixtures/persistence-conformance/) | 12 (9 query + 3 migration) | 12 / 12 | 12 / 12 | 12 / 12 (via Exposed) | 12 / 12 | 12 / 12 |
+| `fixtures/codegen-conformance/` (FR-007 — DROPPED in favor of `persistence-conformance` participation) | 0 | n/a | n/a | n/a | n/a | n/a |
+
+Per-port runners + commands:
+
+| Port | Metamodel + YAML + render + verify | Persistence |
+|---|---|---|
+| TypeScript | `cd server/typescript && bun test` (per-package, `~3s`) | `scripts/integration-test.sh ts` (needs Docker) |
+| Java | `mvn -pl metaobjects-conformance test` (and per-tier `-pl render`, etc.) | `scripts/integration-test.sh java` (needs Docker) |
+| Kotlin | `mvn -pl codegen-kotlin test` (snapshot suite) | `mvn -pl integration-tests-kotlin test` (needs Docker) |
+| C# | `dotnet test` (per project) | `scripts/integration-test.sh csharp` (needs Docker) |
+| Python | `pytest` (per package) | `scripts/integration-test.sh python` (needs Docker) |
+
+The `persistence-conformance` corpus is intentionally **on-demand** — none of the
+unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
+`scripts/integration-test.sh` is the entry point and is wired into
+[`docs/RELEASING.md`](RELEASING.md) §2b as the pre-`latest` gate.
+
+## Fixture-to-doc mapping
+
+### `fixtures/conformance/` — metamodel loader + canonical serializer (85)
+
+| Fixture prefix | Feature doc |
+|---|---|
+| `loader-basic-*`, `error-parse-*` | [features/loaders.md](features/loaders.md) |
+| `extends-*`, `error-extends-*` | [features/entities.md](features/entities.md) (inheritance) |
+| `identity-*`, `subtype-entity-*`, `subtype-value-*` | [features/entities.md](features/entities.md) (identity / entity vs value) |
+| `attr-*`, `error-attr-*`, `error-reserved-word-as-attr` | [features/entities.md](features/entities.md) (attributes) |
+| `doc-common-attrs-*` | [features/entities.md](features/entities.md) (documentation common attrs) |
+| `auto-set-on-*` | [features/entities.md](features/entities.md) (auto-set timestamps) |
+| `attr-filter-*`, `loader-filterable-*`, `warning-filterable-*`, `layout-data-grid-*`, `error-data-grid-*` | [features/entities.md](features/entities.md) (filter / sort / grid) |
+| `overlay-*` | [features/entities.md](features/entities.md) (overlay / merge) |
+| `field-string-*`, `field-decimal-*`, `field-object-storage-*`, `error-field-object-storage-*` | [features/field-types.md](features/field-types.md) |
+| `currency-*` | [features/field-types.md](features/field-types.md) (currency) |
+| `enum-*`, `error-enum-*` | [features/field-types.md](features/field-types.md) (enum) |
+| `source-rdb-*`, `source-db-table-*`, `source-db-view-*`, `source-multi-source-*`, `error-source-*` | [features/source-kinds.md](features/source-kinds.md) |
+| `relationship-*`, `error-unknown-relationship-*` | [features/relationships.md](features/relationships.md) |
+| `template-*`, `error-template-*` | [features/templates-and-payloads.md](features/templates-and-payloads.md) |
+| `origin-*`, `error-origin-*` | [features/templates-and-payloads.md](features/templates-and-payloads.md) (payload origins) |
+| `smoke-empty-metadata` | [features/entities.md](features/entities.md) |
+
+### `fixtures/yaml-conformance/` (6)
+
+All 6 fixtures → [features/yaml-authoring.md](features/yaml-authoring.md).
+
+### `fixtures/render-conformance/` (4)
+
+All 4 fixtures → [features/templates-and-payloads.md](features/templates-and-payloads.md)
+(render engine output section).
+
+### `fixtures/verify-conformance/` (31)
+
+All 31 fixtures → [features/migrations-and-drift.md](features/migrations-and-drift.md)
+(template drift section — `Renderer.verify`).
+
+### `fixtures/persistence-conformance/` (12)
+
+- `migrations/*` (3) → [features/migrations-and-drift.md](features/migrations-and-drift.md) (schema migration section)
+- `queries/*` (9) → [features/source-kinds.md](features/source-kinds.md) (query semantics against `source.rdb`)
+
+## Orphaned fixtures (tested but not yet documented)
+
+All 138 fixtures across the 5 active corpora map to a feature doc. None are
+orphaned today.
+
+If you add a new fixture and don't see a clear home for it, either:
+
+1. Add a section to the closest matching feature doc and reference it from its
+   `## Verified by` block, or
+2. Open an issue if the fixture exercises behavior the feature docs haven't yet
+   described.
+
+## Orphaned docs (documented but no fixture coverage)
+
+None of the 8 feature docs lack fixture coverage. The closest case is the
+high-level overview material in each doc (e.g., the "Anatomy of an entity"
+explainer in `entities.md`) — these are pedagogical, not behavioral, and don't
+require pinning.
+
+## See also
+
+- [features/](features/) — the per-feature reference, each with its own `## Verified by`
+- [`spec/conformance-tests.md`](../spec/conformance-tests.md) — fixture format + canonical serializer contract
+- [`spec/cross-language-porting-guide.md`](../spec/cross-language-porting-guide.md) — how a new port wires up against the corpora
+- [`fixtures/conformance/ERROR-CODES.json`](../fixtures/conformance/ERROR-CODES.json) — the enumerated error codes every `error-*` fixture pins
+- [`docs/RELEASING.md`](RELEASING.md) — `scripts/integration-test.sh` runs `persistence-conformance` per port pre-release

docs/README.md

@@ -15,6 +15,7 @@ copy-paste cross-port without context-switching.
 ```
 docs/
 ├── README.md                    # this file
+├── CONFORMANCE.md               # inverse index: fixture → feature doc + per-port pass status
 ├── features/                    # one file per metamodel feature
 │   ├── entities.md
 │   ├── source-kinds.md
@@ -42,6 +43,7 @@ docs/
 | Author metadata in YAML instead of JSON | [`features/yaml-authoring.md`](features/yaml-authoring.md) |
 | Wire prompt construction (FR-004) | [`features/templates-and-payloads.md`](features/templates-and-payloads.md) |
 | Know which feature is supported in which port today | the capability matrix in the root [`README.md`](../README.md) or the per-port "Capability snapshot" table |
+| See which conformance fixtures gate each feature (and which port passes which) | [`CONFORMANCE.md`](CONFORMANCE.md) |
 | Read the canonical spec (target-agnostic) | [`../spec/`](../spec/) |
 | Find a release recipe (Cloudflare D1, etc.) | [`recipes/`](recipes/) |
 | See the deeper design rationale for a feature | [`superpowers/specs/`](superpowers/specs/) |

docs/features/entities.md

@@ -236,6 +236,76 @@ class Author:
     bio: Optional[str] = None
 ```
 
+## Verified by
+
+The following conformance fixtures gate this feature's behavior across ports:
+
+**Basic entity loading**
+
+- [`fixtures/conformance/smoke-empty-metadata/`](../../fixtures/conformance/smoke-empty-metadata/) — empty metadata loads without error
+- [`fixtures/conformance/loader-basic-single-entity/`](../../fixtures/conformance/loader-basic-single-entity/) — single `object.entity` round-trip
+- [`fixtures/conformance/subtype-entity-with-identity/`](../../fixtures/conformance/subtype-entity-with-identity/) — `object.entity` accepts `identity.primary`
+- [`fixtures/conformance/subtype-entity-missing-primary-warning/`](../../fixtures/conformance/subtype-entity-missing-primary-warning/) — warning when an entity has no primary identity
+- [`fixtures/conformance/subtype-value-without-identity/`](../../fixtures/conformance/subtype-value-without-identity/) — `object.value` does NOT require identity
+
+**Inheritance via `extends:`**
+
+- [`fixtures/conformance/extends-single-level/`](../../fixtures/conformance/extends-single-level/) — basic `extends` resolution
+- [`fixtures/conformance/extends-multi-level/`](../../fixtures/conformance/extends-multi-level/) — multi-hop ancestor chain
+- [`fixtures/conformance/extends-abstract-base/`](../../fixtures/conformance/extends-abstract-base/) — `abstract: true` parents are not instantiable
+- [`fixtures/conformance/extends-cross-file/`](../../fixtures/conformance/extends-cross-file/) — deferred resolution across files
+- [`fixtures/conformance/error-extends-nonexistent/`](../../fixtures/conformance/error-extends-nonexistent/) — `ERR_UNKNOWN_EXTENDS` when parent missing
+
+**Identity**
+
+- [`fixtures/conformance/identity-primary-and-secondary/`](../../fixtures/conformance/identity-primary-and-secondary/) — multiple identities on one entity
+- [`fixtures/conformance/identity-reference-simple/`](../../fixtures/conformance/identity-reference-simple/) — FK via `identity.reference`
+
+**Attributes (`@`-prefixed)**
+
+- [`fixtures/conformance/attr-properties-basic/`](../../fixtures/conformance/attr-properties-basic/) — typed attr parsing
+- [`fixtures/conformance/attr-default-polymorphic/`](../../fixtures/conformance/attr-default-polymorphic/) — `@default` adopts the field's value type
+- [`fixtures/conformance/error-attr-missing-required/`](../../fixtures/conformance/error-attr-missing-required/) — `ERR_MISSING_REQUIRED_ATTR`
+- [`fixtures/conformance/error-attr-wrong-type/`](../../fixtures/conformance/error-attr-wrong-type/) — `ERR_BAD_ATTR_VALUE` on type mismatch
+- [`fixtures/conformance/error-attr-bad-allowed-value/`](../../fixtures/conformance/error-attr-bad-allowed-value/) — out-of-enumeration attr value rejected
+- [`fixtures/conformance/error-reserved-word-as-attr/`](../../fixtures/conformance/error-reserved-word-as-attr/) — `ERR_RESERVED_ATTR` on `@`-prefixing a reserved word
+
+**Documentation common attrs (`description`, `notes`, `title`, …)**
+
+- [`fixtures/conformance/doc-common-attrs-basic/`](../../fixtures/conformance/doc-common-attrs-basic/) — single-line description
+- [`fixtures/conformance/doc-common-attrs-multiline/`](../../fixtures/conformance/doc-common-attrs-multiline/) — multi-line description preserved
+- [`fixtures/conformance/doc-common-attrs-on-all-types/`](../../fixtures/conformance/doc-common-attrs-on-all-types/) — common attrs accepted on every node kind
+- [`fixtures/conformance/doc-common-attrs-stringarray-shapes/`](../../fixtures/conformance/doc-common-attrs-stringarray-shapes/) — `seeAlso` / `aliases` array shapes
+
+**Auto-set timestamps**
+
+- [`fixtures/conformance/auto-set-on-create/`](../../fixtures/conformance/auto-set-on-create/) — `@autoSetOnCreate` honored
+- [`fixtures/conformance/auto-set-on-update/`](../../fixtures/conformance/auto-set-on-update/) — `@autoSetOnUpdate` honored
+- [`fixtures/conformance/auto-set-on-create-and-update/`](../../fixtures/conformance/auto-set-on-create-and-update/) — both flags coexist
+
+**Filter / sort / data-grid layout**
+
+- [`fixtures/conformance/attr-filter-shorthand/`](../../fixtures/conformance/attr-filter-shorthand/) — `@filterable: true` shorthand
+- [`fixtures/conformance/attr-filter-explicit-ops/`](../../fixtures/conformance/attr-filter-explicit-ops/) — explicit op-list form
+- [`fixtures/conformance/error-attr-filter-bad-field/`](../../fixtures/conformance/error-attr-filter-bad-field/) — `@filterable` on a non-field rejected
+- [`fixtures/conformance/error-attr-filter-bad-op/`](../../fixtures/conformance/error-attr-filter-bad-op/) — unknown operator rejected
+- [`fixtures/conformance/error-attr-filter-legacy-string/`](../../fixtures/conformance/error-attr-filter-legacy-string/) — legacy string form rejected
+- [`fixtures/conformance/loader-filterable-on-indexed-no-warning/`](../../fixtures/conformance/loader-filterable-on-indexed-no-warning/) — indexed field + `@filterable` is silent
+- [`fixtures/conformance/warning-filterable-no-index/`](../../fixtures/conformance/warning-filterable-no-index/) — `@filterable` without an index emits a warning
+- [`fixtures/conformance/layout-data-grid-basic/`](../../fixtures/conformance/layout-data-grid-basic/) — `layout.dataGrid` columns + sort
+- [`fixtures/conformance/layout-data-grid-multiple-named/`](../../fixtures/conformance/layout-data-grid-multiple-named/) — multiple named grids per entity
+- [`fixtures/conformance/error-data-grid-bad-sort-field/`](../../fixtures/conformance/error-data-grid-bad-sort-field/) — `@defaultSortField` must be a real field
+
+**Overlay / merge**
+
+- [`fixtures/conformance/overlay-same-object-different-files/`](../../fixtures/conformance/overlay-same-object-different-files/) — same `package` + `name` merge across files
+- [`fixtures/conformance/overlay-attr-last-writer-wins/`](../../fixtures/conformance/overlay-attr-last-writer-wins/) — attr conflict resolution
+- [`fixtures/conformance/overlay-merge-flag-explicit/`](../../fixtures/conformance/overlay-merge-flag-explicit/) — `overlay: true` is explicit-merge-intent
+
+Cross-port runner coverage: TS / Java / Kotlin / C# / Python all execute these
+via their respective conformance runners. See [`docs/CONFORMANCE.md`](../CONFORMANCE.md)
+for the per-port pass/skip ledger.
+
 ## See also
 
 - [field-types.md](field-types.md) — all `field.*` subtypes and their per-port mappings

docs/features/field-types.md

@@ -217,6 +217,44 @@ class Author:
     created_at: Optional[datetime] = None
 ```
 
+## Verified by
+
+The following conformance fixtures gate this feature's behavior across ports:
+
+**Scalar field attributes**
+
+- [`fixtures/conformance/field-string-maxlength/`](../../fixtures/conformance/field-string-maxlength/) — `field.string @maxLength`
+- [`fixtures/conformance/field-decimal-precision-scale/`](../../fixtures/conformance/field-decimal-precision-scale/) — `field.decimal @precision @scale`
+
+**Currency**
+
+- [`fixtures/conformance/currency-default-usd/`](../../fixtures/conformance/currency-default-usd/) — `field.currency` defaults `@currency=USD` when omitted
+- [`fixtures/conformance/currency-explicit-jpy/`](../../fixtures/conformance/currency-explicit-jpy/) — explicit ISO 4217 honored
+- [`fixtures/conformance/currency-precedence-field-vs-view/`](../../fixtures/conformance/currency-precedence-field-vs-view/) — field `@currency` wins over `view.currency` override
+
+**Enum**
+
+- [`fixtures/conformance/enum-inline/`](../../fixtures/conformance/enum-inline/) — inline `field.enum @values`
+- [`fixtures/conformance/enum-array/`](../../fixtures/conformance/enum-array/) — array-of-enum field
+- [`fixtures/conformance/enum-abstract-extends/`](../../fixtures/conformance/enum-abstract-extends/) — reuse via abstract `field.enum` + `extends`
+- [`fixtures/conformance/error-enum-missing-values/`](../../fixtures/conformance/error-enum-missing-values/) — `ERR_MISSING_REQUIRED_ATTR` when `@values` absent
+- [`fixtures/conformance/error-enum-empty-values/`](../../fixtures/conformance/error-enum-empty-values/) — empty `@values` rejected
+- [`fixtures/conformance/error-enum-duplicate-member/`](../../fixtures/conformance/error-enum-duplicate-member/) — duplicate member symbols rejected
+- [`fixtures/conformance/error-enum-non-identifier-member/`](../../fixtures/conformance/error-enum-non-identifier-member/) — non-identifier member names rejected
+
+**Embedded value objects (`field.object` + `@storage`)**
+
+- [`fixtures/conformance/field-object-storage-flattened/`](../../fixtures/conformance/field-object-storage-flattened/) — `@storage=flattened` owned-type unfurled to columns
+- [`fixtures/conformance/field-object-storage-flattened-nullable/`](../../fixtures/conformance/field-object-storage-flattened-nullable/) — nullable owned-type with `@nullable: true`
+- [`fixtures/conformance/field-object-storage-jsonb-single/`](../../fixtures/conformance/field-object-storage-jsonb-single/) — `@storage=jsonb` single-record column
+- [`fixtures/conformance/field-object-storage-jsonb-array/`](../../fixtures/conformance/field-object-storage-jsonb-array/) — `@storage=jsonb` on array field
+- [`fixtures/conformance/error-field-object-storage-flattened-array/`](../../fixtures/conformance/error-field-object-storage-flattened-array/) — `@storage=flattened` on array field is illegal
+- [`fixtures/conformance/error-field-object-storage-no-object-ref/`](../../fixtures/conformance/error-field-object-storage-no-object-ref/) — `field.object` without `@objectRef` rejected
+
+Cross-port runner coverage: TS / Java / Kotlin / C# / Python all execute these
+via their respective conformance runners. See [`docs/CONFORMANCE.md`](../CONFORMANCE.md)
+for the per-port pass/skip ledger.
+
 ## See also
 
 - [entities.md](entities.md) — host node `object.entity`

docs/features/loaders.md

@@ -164,6 +164,26 @@ identical bad input. See
 for the full enumeration; every entry has a matching `fixtures/conformance/error-*`
 fixture that pins the cross-port behavior.
 
+## Verified by
+
+The following conformance fixtures gate this feature's behavior across ports:
+
+**Basic loader behavior**
+
+- [`fixtures/conformance/loader-basic-single-entity/`](../../fixtures/conformance/loader-basic-single-entity/) — single entity file round-trip
+- [`fixtures/conformance/loader-basic-empty-package/`](../../fixtures/conformance/loader-basic-empty-package/) — empty `package` allowed (top-level namespace)
+- [`fixtures/conformance/loader-basic-explicit-subtype/`](../../fixtures/conformance/loader-basic-explicit-subtype/) — explicit `<type>.<subtype>` keying
+- [`fixtures/conformance/loader-basic-multi-file-same-package/`](../../fixtures/conformance/loader-basic-multi-file-same-package/) — multiple files in one package
+- [`fixtures/conformance/error-parse-malformed-json/`](../../fixtures/conformance/error-parse-malformed-json/) — malformed JSON surfaces a structured parse error
+
+**All `fixtures/conformance/error-*` fixtures** double as a loader-error matrix; see the
+[`ERROR-CODES.json`](../../fixtures/conformance/ERROR-CODES.json) enumeration. Each
+error code has at least one matching fixture that pins the cross-port behavior.
+
+Cross-port runner coverage: TS / Java / Kotlin / C# / Python all execute these
+via their respective conformance runners. See [`docs/CONFORMANCE.md`](../CONFORMANCE.md)
+for the per-port pass/skip ledger.
+
 ## See also
 
 - [yaml-authoring.md](yaml-authoring.md) — how YAML lowers to canonical JSON