docs: #368 — correct the Kotlin claim, add the rule-(e) zero-candidate gap, state the composite fallback

Three corrections to the public record.

I2 — CHANGELOG and PR-BODY both said "Python and Java do not implement this
correlation and are unaffected". That was FALSE for the Java tree's Kotlin Exposed
generator, which had the same first-match-on-target defect (fixed in the preceding
commit). Both now name TypeScript migrate-ts, the C# port and the Kotlin generator,
and say only Python is unaffected.

I3 — the ledger ruled that rule (e)'s ZERO-candidate gap goes in the limitation
list and it never landed. Added: the gate covers a @Cardinality: one relationship
only when its holder declares at least one identity.reference at the target, because
`candidates.length <= 1` skips zero as well as one. The user-visible consequence is
stated plainly — an inverted shape (relationship on one entity, both FKs on the far
side) loads clean and codegen then SILENTLY DROPS the relation.

M5 — the composite-reference limitation was understated: it does not refuse. Rule
(e) accepts a @sourceRefField matching any candidate's first column and the ladder's
.find() returns the FIRST candidate, so such a model loads clean and resolves to
whichever composite reference is declared first.

Also recorded in CHANGELOG, both user-visible: Java's relationship validation moved
from eager-throw-on-first-violation to collect-all-findings (a change to Java loader
OUTPUT), and adopters with the affected shapes will see FK referential-action diffs
on their next `meta migrate`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lfd8nat1WcSpXffd8YetiC

Author: dmealing

CHANGELOG.md

@@ -96,12 +96,13 @@ here.**
   even when the hop explicitly named the other reference, and the docs-site link graph
   drew the wrong edge. All four produce a join that typechecks, emits correct DDL, and
   passes `meta verify` — the only symptom is wrong rows. The referential-actions
-  correlation (TypeScript's `migrate-ts` and the C# port; Python and Java do not
-  implement this correlation and are untouched) had the same defect one level over:
-  every FK past the first silently inherited the *first* relationship's `@onDelete` /
-  `@onUpdate` instead of its own, so a model mixing `restrict` and `cascade` across two
-  references to the same target emitted the wrong action on whichever FK wasn't
-  examined first.
+  correlation (TypeScript's `migrate-ts`, the C# port, and the JVM tree's Kotlin
+  Exposed table generator; Python does not implement this correlation) had the same
+  defect one level over: every FK past the first silently inherited the *first*
+  relationship's `@onDelete` / `@onUpdate` instead of its own, so a model mixing
+  `restrict` and `cascade` across two references to the same target emitted the wrong
+  action on whichever FK wasn't examined first. All three are now correlated by
+  inverting the same ladder, and fail closed rather than guessing.
 
   Resolution is now explicit and identical across TypeScript, Python, C# and Java: an
   ambiguous `@cardinality: one` reference set resolves by a ladder — the sole
@@ -112,11 +113,25 @@ here.**
   Amendment 1). `@sourceRefField` is now legal on a `@cardinality: one` relationship —
   it previously failed to load there as an M:N-only attribute. Two limits are
   documented rather than fixed here: the ladder matches a candidate's first FK field
-  only, so two composite references sharing a first column stay indistinguishable, and
-  the loader gate covers `@cardinality: one` relationships only — a `many`-cardinality
-  relationship, or a bare `identity.reference` pair with no relationship wrapper, still
-  reaches codegen unvalidated. See
-  [`docs/features/relationships.md`](docs/features/relationships.md).
+  only, so two composite references sharing a first column stay indistinguishable (and
+  resolve to the first, rather than being refused); the loader gate covers
+  `@cardinality: one` relationships only — a `many`-cardinality relationship, or a bare
+  `identity.reference` pair with no relationship wrapper, still reaches codegen
+  unvalidated; and the gate needs at least one candidate on the holder, so an inverted
+  shape with both FKs on the far side loads clean and codegen then silently drops the
+  relation. See [`docs/features/relationships.md`](docs/features/relationships.md).
+
+  Two consequences worth stating outright. **Java's relationship validation changed
+  from eager-throw-on-first-violation to collect-all-findings** —
+  `validateRelationshipsM2M` now returns a `List<MetaDataException>` rather than
+  throwing, and the new rule-(e) pass collects the same way, so a Java loader run
+  reports every broken relationship where it previously reported only the first; that
+  is a change to Java loader OUTPUT, not an internal refactor. And **adopters with the
+  affected shapes will see FK referential-action diffs on their next `meta migrate`**:
+  a second FK to the same target now resolves its OWN `@onDelete` / `@onUpdate`
+  instead of inheriting the first relationship's, so the generated `ON DELETE` /
+  `ON UPDATE` (and a Kotlin Exposed table's `ReferenceOption` arguments) legitimately
+  change.
 
   No vocabulary was added, removed or retyped — the only change to
   `expected-registry.json` corrects `@sourceRefField`'s own description, which no

docs/features/relationships.md

@@ -209,13 +209,23 @@ Resolution follows a ladder, checked in order:
 **Limitations, documented rather than fixed:**
 
 - The ladder matches a candidate's **first** FK field only, so two composite
-  references sharing a first column are indistinguishable from each other. The load
-  error still renders each candidate's full field tuple (`name(fieldA, fieldB)`) so the
-  ambiguity is visible even where `@sourceRefField` cannot resolve it.
+  references sharing a first column are indistinguishable from each other — and this
+  does **not** refuse. Rule (e) accepts a `@sourceRefField` that matches *any*
+  candidate's first column (`candidates.some(c => c.fields[0] === declared)`), and the
+  ladder's `.find()` then returns the **first** such candidate. The model loads clean
+  and resolves to whichever composite reference is declared first, which may not be the
+  one meant. Where an error *is* raised, it still renders each candidate's full field
+  tuple (`name(fieldA, fieldB)`) so the collision is at least visible.
 - The load-time gate covers `@cardinality: one` relationships only. A
   `many`-cardinality relationship, and a bare `identity.reference` pair with no
   relationship wrapper at all, reach codegen unvalidated — an ambiguous reference set
   in either shape is not caught at load.
+- The load-time gate covers a `@cardinality: one` relationship only when its **holder
+  declares at least one `identity.reference` at the target**. Rule (e)'s
+  `candidates.length <= 1` skip (`validation-passes.ts`, and its three ports) skips
+  **zero** as well as one, so an inverted shape — the relationship on one entity, both
+  FKs on the far side — loads clean, and codegen then **silently drops the relation**:
+  no join, no error, no diagnostic.
 - A projection's `@via` hop (above) resolves the identical ambiguity for the hop it
   names, but `origin.first`'s own `@via` is never consulted for its base↔child
   correlation — an ambiguous target there has no `@via`-based fix; the only escape is