docs(agent-context): document TPH/discriminator inheritance in all ports + Kotlin snapshot gate

An AI session reading the codegen skill references concluded discriminator-based
(TPH — table-per-hierarchy) inheritance persistence "isn't supported" — because
only references/csharp.md documented it. TPH is fully supported and codegen-
emitted in all 5 ports (single shared table + discriminator + polymorphic
subtype CRUD, conformance-gated), but the Kotlin/Java/Python/TS codegen skill
references had ZERO mentions, so an agent saw no support and wrongly said so.

Root-cause doc fix:
- Add source-grounded TPH coverage to metaobjects-codegen/references/{kotlin,java,
  python,typescript}.md (each port's real idiom: Kotlin Exposed single-table +
  polymorphic controller, Java Spring-JPA, Python SQLAlchemy-polymorphic + FastAPI,
  TS Drizzle single-table + Fastify) — grounded in the actual generators (KotlinTphPlan
  / TphPlan / tph_plan.py / tph-discriminator.ts + runtime-ts/src/tph.ts).
- Add a "Discriminator inheritance (TPH)" note to metaobjects-authoring/SKILL.md.
- Add a "Discriminator-based inheritance (TPH) with persistence" section to
  docs/features/abstracts-and-inheritance.md (YAML example + per-port ORM mapping +
  runtime subtype contract).
- Regenerate fixtures/agent-context-conformance/ goldens (agent-context-conformance
  test green). NOTE: the all-or-nothing regen also corrects PRE-EXISTING stale
  verify/AGENTS/CLAUDE goldens (the live-DB-warning content from 49269da was never
  regenerated) — unrelated to TPH, swept in because goldens regenerate as a set.

Kotlin snapshot ("finish that work off"): add the entity-with-tph byte-level
snapshot fixture to codegen-kotlin so the generated AuthTable.kt (single table,
discriminator col, nullable subtype cols) + polymorphic AuthController.kt
(discriminator inject-from-URL, subtype-scoped CRUD, cross-subtype 404, immutable
discriminator) are gated at the unit level, not just integration.
KotlinCodegenSnapshotTest 13/0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ew1XfYSbEAezxjs9opynAe

Author: dmealing

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -580,6 +580,44 @@ across files (same `package` + same `name` → merged; last-writer-wins on attr
 conflicts, structural children accumulate). Use `extends` to share shape between
 distinct entities; use `overlay` to split one entity's declaration across files.
 
+## Discriminator inheritance (TPH)
+
+When several concrete entities are variants of one thing and should share a
+**single table** (table-per-hierarchy / single-table inheritance), model it with a
+**discriminator** rather than one table per variant:
+
+- The **base** `object.entity` declares `@discriminator` naming a discriminator
+  field — typically a `field.enum` whose `@values` are the subtype tags.
+- Each concrete **subtype** `extends` the base and declares `@discriminatorValue`
+  (one of those enum members).
+
+All subtypes persist to the base's single table (subtype-only columns fold in
+nullable). You author only the metadata; codegen emits the polymorphic surface —
+per-subtype routes at `/<base>/<discriminatorValue lowercased>` where create
+**injects** the discriminator from the URL, reads/updates/deletes are **scoped** to
+the subtype (cross-subtype → 404), and the discriminator is **immutable**.
+Supported + conformance-gated in all five ports (the repo's
+`docs/features/abstracts-and-inheritance.md` has the full example and per-port
+mapping).
+
+```yaml
+- object.entity:
+    name: Auth                      # TPH base — owns the single `auths` table
+    discriminator: type
+    children:
+      - source.rdb: { table: auths }
+      - field.long: { name: id }
+      - field.enum: { name: type, values: ["Bridge", "Copay"] }
+      - identity.primary: { fields: id }
+
+- object.entity:
+    name: BridgeAuth                # subtype — folded into `auths`, tagged type="Bridge"
+    extends: Auth
+    discriminatorValue: Bridge
+    children:
+      - field.int: { name: quantity, required: true }
+```
+
 ---
 
 For non-trivial schema design, use `/superpowers:brainstorming` if installed;

agent-context/skills/metaobjects-codegen/references/java.md

@@ -82,13 +82,29 @@ first group together:
 
 | Generator | Output |
 |---|---|
-| `SpringControllerGenerator` | `<Entity>Controller.java` per writable entity (`source.rdb` `@kind="table"`) — Spring Web MVC, five CRUD endpoints on the cross-port REST contract (`?sort`, `?limit`/`?offset`, `?withCount=1` envelope, 404/400 envelopes) |
-| `SpringDtoGenerator` | `<Entity>Dto.java` as a Java 21 `record`; wrapped primitives (`Long`/`Integer`/`Boolean`) so missing JSON props deserialise to `null`; currency = `Long` (integer minor units) |
-| `SpringRepositoryGenerator` | `<Entity>Repository.java` — a hand-stubbed `interface` the consumer implements with their persistence layer (Spring Data JPA / jOOQ / JDBC) |
+| `SpringControllerGenerator` | `<Entity>Controller.java` per writable entity (`source.rdb` `@kind="table"`) — Spring Web MVC, five CRUD endpoints on the cross-port REST contract (`?sort`, `?limit`/`?offset`, `?withCount=1` envelope, 404/400 envelopes). A TPH `@discriminator` base emits ONE controller: polymorphic `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable. |
+| `SpringDtoGenerator` | `<Entity>Dto.java` as a Java 21 `record`; wrapped primitives (`Long`/`Integer`/`Boolean`) so missing JSON props deserialise to `null`; currency = `Long` (integer minor units). A TPH `@discriminator` base's DTO is the **union** of every subtype's columns (subtype-only fields folded nullable, validation dropped), so one wire shape backs the polymorphic + per-subtype endpoints. |
+| `SpringRepositoryGenerator` | `<Entity>Repository.java` — a hand-stubbed `interface` the consumer implements with their persistence layer (Spring Data JPA / jOOQ / JDBC). For a TPH base the interface is polymorphic + per-subtype-scoped (`listByType`/`findByIdAndType`/`createWithType`/`updateByIdAndType`/`deleteByIdAndType`) over the single table; subtype entities emit no own controller/DTO/repository — they fold into the base. |
 | `SpringPayloadGenerator` | a Java 21 `record` per template payload VO |
 | `SpringOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
 | `SpringFilterAllowlistGenerator` | per-entity filter allowlist |
 
 Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
 ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed
 physical column.
+
+## Discriminator inheritance (TPH)
+
+`codegen-spring` fully supports **table-per-hierarchy (TPH) inheritance**. `TphPlan`
+is the shared descriptor every TPH-aware generator reads: an `object.entity`
+carrying `@discriminator` (naming a `field.enum`) is the base; concrete entities
+that `extends` it and declare `@discriminatorValue` are its subtypes, all persisted
+to the base's **single** table (single-table inheritance). `SpringDtoGenerator`
+emits the base DTO as the union of subtype columns (each folded nullable);
+`SpringControllerGenerator` mounts polymorphic reads + per-subtype CRUD scoped by
+the discriminator (inject on create, subtype-scope + cross-subtype 404 on
+get/update/delete, immutable discriminator); `SpringRepositoryGenerator` emits the
+polymorphic + per-subtype-scoped repository seam the consumer implements against
+Spring Data JPA / JDBC. Conformance-gated by `fixtures/api-contract-conformance/tph`
+(HTTP wire shape) and `fixtures/persistence-conformance/tph-*` (single-table
+runtime semantics).

agent-context/skills/metaobjects-codegen/references/kotlin.md

@@ -94,10 +94,10 @@ All live in `metaobjects-codegen-kotlin` under
 
 | Generator | Output |
 |---|---|
-| `KotlinEntityGenerator` | `<Entity>.kt` — `@Serializable data class` per `object.entity` / `object.value` |
-| `KotlinExposedTableGenerator` | `<Entity>Table.kt` — Exposed `Table` object (PK + FK + `@storage` columns) for entities with `source.rdb` |
+| `KotlinEntityGenerator` | `<Entity>.kt` — `@Serializable data class` per `object.entity` / `object.value`. A TPH `@discriminator` base's data class is the **union** of every subtype's columns (each folded nullable, validation dropped) so one wire shape backs the polymorphic + per-subtype endpoints. |
+| `KotlinExposedTableGenerator` | `<Entity>Table.kt` — Exposed `Table` object (PK + FK + `@storage` columns) for entities with `source.rdb`. A TPH `@discriminator` base emits ONE `Table` for the whole hierarchy — every subtype-only column folded in `.nullable()` (a row of another subtype stores null there) — single-table inheritance; subtype entities emit no table of their own. |
 | `KotlinRelationsGenerator` | `<Entity>Relations.kt` — extension fns for `@cardinality="many"` query helpers |
-| `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController`, five CRUD endpoints on the cross-port REST contract, for writable entities (`source.rdb` `@kind="table"`) |
+| `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController`, five CRUD endpoints on the cross-port REST contract, for writable entities (`source.rdb` `@kind="table"`). A TPH `@discriminator` base emits ONE controller: polymorphic `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete are scoped to the subtype (cross-subtype → 404); the discriminator is immutable. |
 | `KotlinPayloadGenerator` | `<Template>Payload.kt` — `@Serializable` payload data class from a template's `@payloadRef` |
 | `KotlinOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` (once per project) |
@@ -108,3 +108,19 @@ All live in `metaobjects-codegen-kotlin` under
 Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
 ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed
 physical column.
+
+## Discriminator inheritance (TPH)
+
+`codegen-kotlin` fully supports **table-per-hierarchy (TPH) inheritance**.
+`KotlinTphPlan` is the shared descriptor every TPH-aware generator reads: an
+`object.entity` carrying `@discriminator` (naming a `field.enum`) is the base;
+concrete entities that `extends` it and declare `@discriminatorValue` are its
+subtypes, all persisted to the base's **single** Exposed `Table` (single-table
+inheritance). `KotlinExposedTableGenerator` folds each subtype's own columns into
+that table as `.nullable()`; `KotlinEntityGenerator` builds the base data class as
+the union of subtype columns; `KotlinFilterAllowlistGenerator` unions the
+subtypes' filterable columns; `KotlinSpringControllerGenerator` mounts the
+polymorphic reads + per-subtype CRUD scoped by the discriminator (inject on create,
+subtype-scope + cross-subtype 404 on get/update/delete, immutable discriminator).
+Conformance-gated by `fixtures/api-contract-conformance/tph` (HTTP wire shape) and
+`fixtures/persistence-conformance/tph-*` (single-table runtime semantics).

agent-context/skills/metaobjects-codegen/references/python.md

@@ -37,12 +37,28 @@ a renamed physical column).
 
 | Stable name | Output |
 |---|---|
-| `entity` | one **Pydantic model** per `object.entity` / projection (the `entity-model` generator): typed fields from the metadata, nullability from `@required`, `@maxLength`/validators, enum fields → a Python `Enum`. This is the typed data model. |
-| `routes` | a **FastAPI `APIRouter`** per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). The router declares a repository **`Protocol`** you implement and inject. |
+| `entity` | one **Pydantic model** per `object.entity` / projection (the `entity-model` generator): typed fields from the metadata, nullability from `@required`, `@maxLength`/validators, enum fields → a Python `Enum`. This is the typed data model. A TPH concrete subtype (`@discriminatorValue`) pins the inherited `@discriminator` field to a `Literal[...]` so the model rejects a foreign-subtype tag. |
+| `routes` | a **FastAPI `APIRouter`** per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). The router declares a repository **`Protocol`** you implement and inject. A TPH `@discriminator` base emits ONE polymorphic router: `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable. Its repository `Protocol` is subtype-keyed (`subtype=None` for the polymorphic base) so your implementation applies the single-table discriminator scope. |
 | `filter-allowlist` | per-entity filter allowlist (FR-009 — the server-side field+operator allowlist the routes validate against). |
 | `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-helper` | the `template.output` prompt-pillar artifacts — see the **prompts** reference. |
 | `template` | the generic Mustache `template` primitive. |
 
+## Discriminator inheritance (TPH)
+
+Python codegen fully supports **table-per-hierarchy (TPH) inheritance**
+(`tph_plan.py` is the shared descriptor): an `object.entity` carrying
+`@discriminator` (naming a `field.enum`) is the base; concrete entities that
+`extends` it and declare `@discriminatorValue` are its subtypes, all persisted to
+the base's **single** table (single-table inheritance). The `entity` generator
+pins each subtype's inherited discriminator to a `Literal`; the `routes` generator
+emits the polymorphic router + per-subtype CRUD scoped by the discriminator (inject
+on create, subtype-scope + cross-subtype 404 on get/update/delete, immutable
+discriminator). Because Python owns no ORM (see below), your repository — keyed by
+subtype — applies the single-table discriminator scope (idiomatically a
+SQLAlchemy polymorphic/single-table mapping). Conformance-gated by
+`fixtures/api-contract-conformance/tph` (HTTP wire shape) and
+`fixtures/persistence-conformance/tph-*` (single-table runtime semantics).
+
 ## No ORM — you own persistence (unlike the C# port)
 
 Python codegen emits the **Pydantic models + the FastAPI routers**, but **no ORM /

agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -69,13 +69,31 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 
 | Generator | Emits per entity |
 |---|---|
-| `entityFile()` | `<Entity>.ts` — Drizzle table + FK `.references()` + `relations()` + inferred types + Zod insert/update schemas + `<Entity>FilterAllowlist` / `<Entity>SortAllowlist` |
+| `entityFile()` | `<Entity>.ts` — Drizzle table + FK `.references()` + `relations()` + inferred types + Zod insert/update schemas + `<Entity>FilterAllowlist` / `<Entity>SortAllowlist`. A TPH `@discriminator` base folds every subtype's columns into ONE Drizzle table (subtype-only columns nullable, no default — single-table inheritance) and emits a discriminated-union type + per-subtype Zod schemas + a `parse<Base>` dispatcher; subtype entities emit no table of their own. |
 | `queriesFile()` | `<Entity>.queries.ts` — typed CRUD (`findPostById`, `listPosts`, `createPost`, `updatePost`, `deletePostById`) |
-| `routesFile()` | `<Entity>.routes.ts` — Fastify CRUD routes on the cross-port REST contract. `routesFileHono()` is the Hono/Workers variant |
+| `routesFile()` | `<Entity>.routes.ts` — Fastify CRUD routes on the cross-port REST contract. `routesFileHono()` is the Hono/Workers variant. A TPH `@discriminator` base mounts polymorphic `GET /<base>(+/:id)` plus a per-subtype CRUD set at `<basePath>/<discriminatorValue lowercased>` — create omits the discriminator (the URL names the subtype; the runtime injects it); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable via the runtime `discriminator` option. |
 | `barrel()` | `index.ts` re-exporting each `<Entity>.ts` (one-shot, not per-entity) |
 | `promptRender()` | `render<Name>()` per `template.prompt` |
 | `outputParser()` | `<Name>.output.ts` (`parse*` / `safeParse*`) per `template.output` |
 
+## Discriminator inheritance (TPH)
+
+The TS reference implementation fully supports **table-per-hierarchy (TPH)
+inheritance** (`tph-discriminator.ts` is the shared descriptor): an `object.entity`
+carrying `@discriminator` (naming a `field.enum`) is the base; concrete entities
+that `extends` it and declare `@discriminatorValue` are its subtypes, all persisted
+to the base's **single** Drizzle table (single-table inheritance). `entityFile()`
+folds each subtype's columns into that table nullable and emits the
+discriminated-union type + per-subtype Zod schemas + a `parse<Base>` dispatcher;
+`routesFile()` mounts polymorphic reads + per-subtype CRUD scoped by the
+discriminator. At runtime, `@metaobjectsdev/runtime-ts`'s ObjectManager enforces the
+subtype contract: it injects the discriminator on create, scopes every
+read/update/delete to the subtype (a foreign-subtype row is invisible), and treats
+the discriminator as immutable — mirroring the generated per-subtype route's
+cross-subtype 404. Conformance-gated by `fixtures/api-contract-conformance/tph`
+(HTTP wire shape) and `fixtures/persistence-conformance/tph-*` (single-table
+runtime semantics).
+
 ## Docs — `meta docs` (one door, two surfaces)
 
 Documentation is NOT a `meta gen` generator. The single door is the `meta docs`