fix: two identity.reference nodes onto one entity made every association join the first FK (#368)

[dmealing]

Summary

When an entity declares two identity.reference nodes onto the same target entity
(e.g. Match.homeTeamRef and Match.awayTeamRef, both -> Team), a
@cardinality: one relationship.association names only its target via
@objectRef — never which reference it means. Every resolver that had to answer
"which FK does this relationship navigate?" took the first matching reference and
never noticed there was a second. The second relationship's generated code silently
joined on the first relationship's FK column.

Why this was invisible: the emitted code compiles, the DDL is correct (each FK
column is emitted with its own real foreign key — only the ORM navigation picks the
wrong one), both FK columns are type-identical integer references to the same target
PK so nothing in the type system can tell them apart, and meta verify was clean
(2 gate(s) ran, all clean, zero anti-patterns). The only symptom was wrong rows
coming back from a relational query that navigated the second association.

Resolution

An ambiguous @cardinality: one reference set now resolves by an explicit ladder,
identical across all four ports (ADR-0029 Amendment 1):

1. exactly one candidate identity.reference onto the target → that one (the common
   case, unchanged behavior);
2. a declared @sourceRefField → the candidate whose FK field it names (this check
   short-circuits: a value naming no candidate's FK field is a load error at any
   candidate count, it never falls through to name-pairing);
3. exactly one candidate whose name/FK field pairs with the relationship's own name
   (e.g. awayTeam pairs with awayTeamRef / awayTeamId) → that one;
4. otherwise → ERR_INVALID_RELATIONSHIP at load, naming the relationship and every
   candidate reference.

@sourceRefField is now legal on a @cardinality: one relationship — previously
it was M:N-only and declaring it on a to-one relationship was itself a load error.

Every surface fixed

• The TypeScript codegen relations() block (codegen-ts/src/relation-resolver.ts)
  — no longer takes refs.find(...) on target alone; resolves through the shared
  ladder and skips (rather than guesses) when the loader should already have refused
  the model.
• The runtime relation traversal (runtime-ts/src/relation-resolver.ts) — the
  forward and inverse relation-descriptor lookups both resolve through the same
  ladder instead of a bare "first reference to this target" scan.
• The projection join lookup (codegen-ts/src/projection/extract-view-spec.ts) —
  a @via join hop now prefers the specific reference/relationship the hop already
  named over re-deriving one from the target alone, so an explicit hop resolves
  cleanly even when the ladder alone could not disambiguate; a hop that is still
  genuinely ambiguous fails with a message pointing at a real fix rather than a
  dead-end attribute (round 2). origin.first's own correlation also refuses rather
  than silently taking the first match — but only when ONE HOLDER declares two or
  more references onto the other side; a mutual 1:1 (one reference per holder,
  pointing opposite ways) is legal and keeps working (see Limitations below).
• The docs link graph (docs-site/src/link-graph.ts) — the belongs-to edge used
  to dedupe against the FK edge it supersedes now resolves through the same ladder.
• The referential-actions correlation (TypeScript migrate-ts, the C# port, and
  the JVM tree's Kotlin Exposed table generator — Python does not implement this
  correlation and is unaffected) — this 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
  referential action on whichever FK wasn't examined first. Now correlated by
  inverting the same ladder (a relationship r belongs to reference ref iff
  resolving r's ladder returns ref itself); a genuinely ambiguous correlation
  contributes nothing rather than an arbitrary action. The Kotlin generator
  (KotlinExposedTableGenerator) had both halves of the defect — a first-match-on-
  target child-side tier and a first-match reverse tier — and is fixed the same way
  here: RelationshipReferences.resolveRelationshipReference is already on its
  classpath, so the inversion is the identical rule, not a parallel one.
• The Python ladder's @references head-parse (relationship_references.py) —
  Python compared the WHOLE @references value, so the normative dotted
  Entity.field form never matched a target: a valid dotted model was refused and an
  ambiguous one loaded clean, in both directions against TypeScript. It now takes the
  segment before the first . (searched after the last ::), exactly as the other
  three ports' targetEntity accessor does.
• Loader validation reaches all four ports (TypeScript, Python, C#, Java) — the
  ambiguity check and the @sourceRefField-on-cardinality:one legality change are
  both implemented identically in every loader, backed by four new shared
  conformance fixtures under fixtures/conformance/:
  relationship-one-two-refs-name-pairing (resolves via name pairing),
  relationship-one-two-refs-sourcerefield (resolves via the declared attribute),
  relationship-one-two-refs-dotted-references (the same shape with @references in
  the dotted Entity.field form — the corpus's only use of it, and the reason a
  Python-only head-parse divergence stayed green), and
  error-relationship-one-refs-ambiguous (refused with ERR_INVALID_RELATIONSHIP
  naming both candidates). Corpus 328 -> 329.

Registry / release consequence

expected-registry.json changed — the @sourceRefField attribute description and
the type-level rules prose (on association, aggregation, composition, and the
abstract base subtype) were corrected to describe the new dual meaning; no
attribute, subtype, or type was added, removed, or retyped. Per docs/RELEASING.md,
any change to expected-registry.json forces all four registries (npm / PyPI / NuGet
/ Maven) to publish together at the next release, regardless of which product files
changed — recording that here so it isn't a surprise at release time.
metamodelVersion stays 1.0 — this is a description/prose correction, not a
vocabulary change.

Adopters with the affected shapes will see FK referential-action diffs on their next
meta migrate. The correlation fix changes which ON DELETE / ON UPDATE a second
FK to the same target resolves to, so a model that was silently emitting the first
relationship's action now emits its own — a real, intended schema diff rather than
drift. The same applies to a Kotlin Exposed table's ReferenceOption arguments.

Java's relationship validation passes now collect all findings instead of
throwing on the first violation: validateRelationshipsM2M was converted from
void + throw to returning a List<MetaDataException>, and the new rule-(e) pass
(validateOneSideReferenceResolution) collects by construction. A Java loader run
now reports every broken relationship where it previously reported only the first —
user-visible output, not an internal refactor.

Documented limitations (not fixed here)

• Composite references can't be disambiguated — and this does not refuse. The
  ladder's @sourceRefField match and name-pairing both key off a candidate's
  first FK field only. Rule (e) accepts a @sourceRefField that matches any
  candidate's first column and the ladder's .find() then returns the first
  candidate, so two composite references sharing a first column load clean and
  resolve to whichever is declared first.
• The loader gate covers only @cardinality: one. A many-cardinality
  relationship, or a bare identity.reference pair with no relationship wrapper at
  all, still reaches codegen unvalidated.
• The load-time gate needs at least one candidate reference on the holder. Rule
  (e)'s candidates.length <= 1 skip skips zero as well as one, so a
  @cardinality: one relationship whose holder declares no identity.reference at
  the target is not covered. An inverted shape — the relationship on one entity, both
  FKs on the far side — loads clean, and codegen then silently drops the relation.
• origin.first projections on an ambiguous target remain unusable.
  origin.first's own @via is not consulted by the correlation that resolves its
  base↔child join (a separate, larger wiring gap, out of scope here); when ONE HOLDER
  declares more than one reference onto the other side, the projection now fails
  loudly at generation time instead of silently picking one. A mutual 1:1 (one
  reference per holder, pointing opposite ways) is not that ambiguity and keeps
  working.

Closes #368.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lfd8nat1WcSpXffd8YetiC