Merge branch 'worktree-agent-a7158261af3b52cc6'

# Conflicts:
#	CHANGELOG.md

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,76 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — parent-side `relationship.composition` reaches the child's FK (migrate-ts; ADR-0047)
+
+> **ADOPTER-VISIBLE MIGRATION — production delete semantics change.** After
+> upgrading, the first `meta migrate` against a live database emits a one-time
+> migration **adding `ON DELETE CASCADE` (or the relationship's declared/default
+> action) to FKs whose parent-side relationship was previously silently
+> ignored** — deleting a parent row then deletes its children instead of
+> failing. This is the documented semantic the metadata always declared, but it
+> was never enforced, so review that migration deliberately; pin
+> `@onDelete: "no-action"` on any relationship whose DB behavior you want kept.
+> The same applies to a child-side relationship authored with an FQN
+> `@objectRef`, which the old exact-string correlation silently missed.
+> Give this entry top billing at cut time.
+
+The authoring the docs and the `metaobjects-authoring` skill teach — declaring the
+relationship on the PARENT (`relationship.composition { @objectRef: "Post",
+@cardinality: "many" }` on `Author`, with the subtype implying the default action) —
+contributed **nothing** to the foreign key: `resolveReferentialActions` correlated only
+relationships declared on the FK-owning child, so the documented "composition ⇒
+`ON DELETE CASCADE` default" never fired and deleting a parent with children was a raw
+FK violation at runtime. The resolver now correlates the **reverse relationship on the
+target entity** as a third precedence tier (reference-level attr → child-side
+relationship → parent-side relationship; each relationship contributing its explicit
+action, else its subtype default). Tier-2 correlation is now **package-aware**
+(`refMatchesObject` / ADR-0042) and excludes M:N `@through` relationships — an FQN
+child-side `@objectRef` previously missed the exact-string match and contributed
+nothing (post-fix it would otherwise have been OVERRIDDEN by the parent side), and a
+`@through` relationship wrongly armed cascade on a sibling direct FK to the same
+target. Guards on the new reverse tier, each failing closed: the M:N exclusion; a
+reverse relationship contributes nothing unless the child holds exactly one enforced
+reference to the target (it cannot say which FK carries the ownership edge); and an
+INFERRED set-null default (parent-side aggregation, no explicit `@onDelete`) on a NOT
+NULL FK drops its inferred contributions rather than turning a previously-valid model
+into a hard `SetNullNotNullableError` — while an explicitly authored `set-null` still
+errors loudly and an explicitly authored `@onUpdate` on that same relationship is
+still honored. Models whose FKs already resolved an action are byte-identical; the
+two intentional output changes both restore declared intent that was silently
+dropped. The Kotlin Exposed table generator's
+decorated `identity.reference` columns now resolve actions with the same precedence
+(they previously emitted raw relationship attrs only, and the canonical
+parent-relationship + child-reference shape lost the action entirely through the
+FK-dedup pass).
+
+### Added — `@onDelete` / `@onUpdate` registered on `identity.reference` (all five ports; ADR-0047)
+
+The migrate engine has long honored `@onDelete` / `@onUpdate` declared directly on
+`identity.reference` (highest precedence — the reference IS the FK), and
+`docs/features/relationships.md`'s own canonical example authored it — but the attrs
+were never registered, so a model `meta migrate` accepted and applied **failed strict
+`meta verify` outright** with `ERR_UNKNOWN_ATTR`. Those two must never disagree.
+[ADR-0047](spec/decisions/ADR-0047-referential-actions-on-identity-reference.md)
+rules the attrs REGISTERED (db-provider, like `@constraintName`; optional string,
+allowedValues `cascade | set-null | restrict | no-action`) in all five ports +
+`expected-registry.json`, with the written can't-be-computed justification ADR-0023
+requires: a reference-only FK (no relationship) and an M:N junction's FK sides have
+NO existing metadata implying any action, and the per-FK override is information the
+relationship layer does not carry. Recommended authoring stays relationship-level.
+Consequences: the legacy `"setnull"` alias is retired — `allowedValues` is enforced
+unconditionally at load, so it now fails BOTH migrate and verify with
+`ERR_BAD_ATTR_VALUE` (it was only ever reachable through the unregistered-attr hole);
+Java's `ReferenceIdentity` regains the accessors SP-G Unit 6a removed; and the JVM
+validation pass extends its referential-action value check to `identity.reference`.
+Gated by a new shared conformance fixture (`identity-reference-referential-actions`,
+strict-loaded by every port) exercising BOTH previously-untested shapes — the
+parent-side `many` composition relying on its subtype default, and the
+reference-level attrs — plus migrate emit tests asserting the action lands in the
+DDL, and the migrate referential-action test corpus now loads `strict: true`, pinning
+the durable invariant that **any model `meta migrate` accepts must load under strict
+`meta verify`**.
+
 ### Fixed — `meta gen` emitted duplicate imports under a split dependency tree (npm: `codegen-ts` + `cli`)
 
 With a **globally-installed or linked `meta` CLI** and a project-local ts-poet (which
@@ -83,48 +153,6 @@ READMEs, `README.md`, `CLAUDE.md`, `docs/ports/typescript-client.md`,
 sweep the pair into lockstep), and the `SOURCE_ONLY` rationale in
 `scripts/check-publish-intent.sh`.
 
-||||||| ba88c0d9
-
-### Fixed — the `like` filter operator is case-sensitive SQL LIKE, uniformly (ADR-0049)
-
-Resolves the 0.21.5 known-issue: cross-port `like` semantics contradicted each other and
-the shared corpora were case-aligned **by construction**, so they could not see it. The
-ruling ([ADR-0049](spec/decisions/ADR-0049-filter-like-is-case-sensitive-sql-like.md)):
-`like` binds the author-supplied pattern **verbatim** — `%`/`_` wildcards, no case
-folding — identically on every port and engine. The written record already said so
-(FR-009 defines `like` as "SQL LIKE semantics" and lists case-insensitive `ilike` as
-explicitly out of scope; ADR-0036 reserves `ilike` as a future additive operator), and
-the reference implementation was not univocal the other way: TS's Kysely/Drizzle/
-in-memory persistence drivers were always verbatim LIKE — only the HTTP filter parser
-dispatched ILIKE, so the TS reference api-contract lane and the TS generated lane
-answered the same request differently.
-
-- **TS (`runtime-ts`, adopter-visible on Postgres)**: `parseFilterParams` no longer
-  lowers `like` to ILIKE on Postgres — every Fastify/Hono mount (CRUD + read-only) now
-  case-sensitive. On **sqlite/D1**, where the engine's native LIKE folds ASCII case,
-  `like` lowers to **GLOB** with an exactly-translated pattern (`%`→`*`, `_`→`?`,
-  GLOB's own metacharacters escaped), proven against a real sqlite engine — behavior,
-  not SQL spelling, is the contract. The TS-only `?search` extension stays deliberately
-  case-INSENSITIVE (it is a human search box, and is now documented as such).
-- **C# (test-only)**: the persistence-conformance adapter reflected Npgsql's `ILike`
-  while the product ships `EF.Functions.Like` — the gate was testing semantics the
-  product never had. The adapter now runs the product's dispatch. No C# product change.
-- **Java / Kotlin / Python**: already conformant (Java since 0.21.4's
-  `Expression.LIKE`); no product change.
-- **Corpora de-blinded** (the actual gate): `filter-like-and-ne`
-  (persistence-conformance) now seeds a case-mismatched pair
-  (`Foundations`/`foundations lab`) and probes both casings — each prefix probe must
-  match exactly one; `filter-like` (api-contract-conformance) adds lowercase `a%` and
-  `a_an%` probes that must match nothing against the capitalized seed. Before the port
-  fixes, the de-blinded corpus failed the TS generated lane (returned `[1, 2]` for
-  `a%` on real Postgres) and the C# persistence lane (`title-like-prefix` matched both
-  casings) — and passes all five ports after. The "case-aligned so the test passes
-  either way" comment is deleted.
-
-Adopters relying on the old TS-on-Postgres case-folding: normalize case in the data or
-the pattern, or use `?search`; a true case-insensitive operator remains chartered as a
-future additive extension gated on real consumer demand.
-
 ## [0.21.5] — npm `0.21.5` · PyPI `0.21.5` · NuGet `0.21.5` · Maven `7.21.5`
 
 A coordinated PATCH across all four registries. Ten fixes, every one reproduced before

CLAUDE.md

@@ -40,7 +40,7 @@ _Last refreshed 2026-08-09._
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
 **Cross-port conformance corpora** (every port runs the shared corpus):
-- Metamodel: `fixtures/conformance/` (270 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
+- Metamodel: `fixtures/conformance/` (271 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
 - Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
 - Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed.

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

@@ -548,8 +548,13 @@ The `[]` key-suffix declares an array field: `field.long[]: weekIds` lowers to
 canonical JSON. `@enforce` on a reference (default `true`) controls whether the
 backend physically enforces it (a SQL FK constraint); set `false` for a logical
 reference for navigation/typing/codegen only. Referential actions
-(`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
-`relationship.*` node (see Relationships below).
+(`@onDelete`/`@onUpdate`) normally live on the `relationship.*` node (see
+Relationships below — the subtype carries the default), but `identity.reference`
+also registers them as the **explicit per-FK override** (ADR-0047): use them for
+a reference-only FK with no relationship, an M:N junction's FK sides (no
+relationship ever correlates with a junction FK), or a single FK that must
+deviate from its relationship's action. A reference-level action always wins
+over the correlated relationship's.
 
 `@references` resolves cross-package by **fully-qualified name**
 (`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
@@ -658,6 +663,11 @@ The `PostTag` junction supplies the FK direction via its two references:
 ] } }
 ```
 
+A junction's FK actions are declared on its `identity.reference` children
+directly (`"@onDelete": "cascade"` on `postRef`/`tagRef` above) — the M:N
+relationship's `@objectRef` names the far side, never the junction, so no
+relationship ever correlates with a junction FK (ADR-0047).
+
 **Adoption footgun — pin BOTH actions.** `@onDelete` defaults *per subtype* (above)
 and `@onUpdate` defaults to `cascade` — but a plain SQL foreign key is `NO ACTION` on
 both. If you're adopting an existing database (matching metadata to a live schema),

agent-context/skills/metaobjects-verify/references/migration.md

@@ -245,6 +245,11 @@ schema without a rewrite:
 - **`identity.reference @constraintName`** pins a foreign-key constraint name so the
   metadata can match an existing DB's naming convention without a destructive
   rename.
+- **`identity.reference @onDelete` / `@onUpdate`** pin a foreign key's referential
+  actions directly on the FK (ADR-0047) — the way to match an adopted DB's existing
+  `ON DELETE`/`ON UPDATE` behavior when the model declares no `relationship.*` for
+  that FK (a relationship's explicit action or subtype default otherwise supplies
+  it, whichever side of the FK declares the relationship).
 
 ## Not yet shipped
 

docs/CONFORMANCE.md

@@ -25,7 +25,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l`.
 
 | Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
 |---|---|---|---|---|---|---|
-| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 270 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
+| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 271 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
 | [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 15 | 15 / 15 | 14 / 15 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 14 / 15 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 15 / 15 |
 | [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 31 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
 | [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -69,7 +69,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
 
 ## Fixture-to-doc mapping
 
-### `fixtures/conformance/` — metamodel loader + canonical serializer (270)
+### `fixtures/conformance/` — metamodel loader + canonical serializer (271)
 
 | Fixture prefix | Feature doc |
 |---|---|

docs/features/relationships.md

@@ -102,14 +102,42 @@ metadata:
 | `@cardinality` | `relationship.composition` | `one` / `many` | Multiplicity on the target side |
 | `@fields` | `identity.reference` | One field name or array | The FK column(s) on this entity |
 | `@references` | `identity.reference` | Entity name | The target entity (PK on the other side) |
-| `@onDelete` | `relationship.*` only | `cascade` / `set-null` / `restrict` / `no-action` | RDB referential action. Default derives from the subtype: composition -> `cascade`, aggregation -> `set-null`, association -> `restrict`. |
-| `@onUpdate` | `relationship.*` only | same as `@onDelete` (default `cascade`) | RDB referential action |
+| `@onDelete` | `relationship.*` and `identity.reference` | `cascade` / `set-null` / `restrict` / `no-action` | RDB referential action. Default derives from the relationship subtype: composition -> `cascade`, aggregation -> `set-null`, association -> `restrict`. |
+| `@onUpdate` | `relationship.*` and `identity.reference` | same as `@onDelete` (default `cascade` when a relationship correlates) | RDB referential action |
 
 `@onDelete` / `@onUpdate` are registered on `relationship.association` /
-`aggregation` / `composition`. They are **not** attributes of `identity.reference` —
-putting one there fails load with `ERR_UNKNOWN_ATTR`. Declare the action on the
-relationship; the reference stays a pure FK declaration (`@fields`, `@references`,
-`@constraintName`, `@enforce`).
+`aggregation` / `composition` **and** — as the explicit per-FK override
+([ADR-0047](../../spec/decisions/ADR-0047-referential-actions-on-identity-reference.md))
+— on `identity.reference` itself. Resolution precedence for the FK's emitted
+action, highest first:
+
+1. `@onDelete` / `@onUpdate` declared directly on the `identity.reference` —
+   the reference IS the FK, so the action may be declared right where the FK
+   is. This is the only way to put an action on a **reference-only FK** (no
+   relationship node) or on an **M:N junction's** FK sides (no relationship
+   ever correlates with a junction FK).
+2. A relationship declared on the FK-owning (child) entity targeting the
+   referenced entity (matched package-aware, so bare and FQN spellings pair
+   correctly; an M:N `@through` relationship never correlates with a direct
+   FK): its explicit action, else its subtype default.
+3. A relationship declared on the **referenced (parent) entity** pointing back
+   at the FK-owning entity — the canonical parent-side authoring above
+   (`Author` declares `posts`): its explicit action, else its subtype default.
+   Guards: the M:N exclusion again; when the child holds more than one FK to
+   the same parent the parent-side relationship contributes to none of them
+   (it cannot say which FK carries the ownership edge); and an inferred
+   set-null default (aggregation, no explicit `@onDelete`) on a NOT NULL FK
+   contributes nothing — SET NULL cannot fire there (an explicit `set-null`
+   instead fails migration generation loudly, telling you to make the FK
+   nullable).
+4. None of the above → the FK is emitted with no `ON DELETE` / `ON UPDATE`
+   clause (SQL `NO ACTION`).
+
+Prefer declaring the action on the relationship (the subtype carries the
+semantics and the default); reach for the reference-level attr only when no
+relationship exists or a single FK needs to deviate. The values are
+load-validated everywhere — a misspelling (e.g. the retired `setnull` alias)
+fails load with `ERR_BAD_ATTR_VALUE`.
 
 The kebab-case metamodel values map to the SCREAMING_SNAKE forms in Exposed / EF
 Core / the target ORM or DDL at codegen time.
@@ -248,6 +276,7 @@ The following conformance fixtures gate this feature's behavior across ports:
 - [`fixtures/conformance/relationship-one-to-many/`](../../fixtures/conformance/relationship-one-to-many/) — `relationship.composition` 1:N with the parent owning the collection
 - [`fixtures/conformance/identity-reference-simple/`](../../fixtures/conformance/identity-reference-simple/) — `identity.reference` declares the FK column-set on the child
 - [`fixtures/conformance/source-rdb-referential-actions/`](../../fixtures/conformance/source-rdb-referential-actions/) — `@onDelete` / `@onUpdate` on relationships
+- [`fixtures/conformance/identity-reference-referential-actions/`](../../fixtures/conformance/identity-reference-referential-actions/) — the parent-side `@cardinality: many` composition (subtype-default cascade) + `@onDelete` / `@onUpdate` declared directly on `identity.reference` (ADR-0047)
 - [`fixtures/conformance/error-unknown-relationship-subtype/`](../../fixtures/conformance/error-unknown-relationship-subtype/) — unknown `relationship.<subtype>` rejected
 
 Cross-port runner coverage: TS / Java / Kotlin / C# / Python all execute these