@metaobjectsdev/metadata 1.0.3 → 1.0.4-rc.1

package/dist/core/relationship/derive-m2m-fields.d.ts

@@ -17,7 +17,9 @@ export interface M2MFields {
  *
  * @param rel     the M:N relationship (carries @objectRef + @through + optional
  *                @sourceRefField / @symmetric)
- * @param source  the entity declaring `rel`
+ * @param source  the entity the caller is navigating from. Accepted alongside
+ *                `rel.parent` as a name for the relationship's subject, and used
+ *                as the declaring entity when `rel` has no entity parent.
  * @param root    the loaded model root (to find the junction entity)
  * @throws M2MDerivationError when the junction is missing/malformed or the
  *         self-join is ambiguous.

package/dist/core/relationship/derive-m2m-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-m2m-fields.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/derive-m2m-fields.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,8BAA8B;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAOD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,QAAQ,GACb,SAAS,CA0FX"}
+{"version":3,"file":"derive-m2m-fields.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/derive-m2m-fields.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,8BAA8B;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,QAAQ,GACb,SAAS,CA+IX"}

package/dist/core/relationship/derive-m2m-fields.js

@@ -17,7 +17,30 @@
 //      two references are taken in declaration order (sourceField = first,
 //      targetField = second). Resolution unions both at read time.
 // Ambiguous (source == target, neither @sourceRefField nor @symmetric) → throw.
+//
+// "source" above means the relationship's SUBJECT, and under `extends` there are two
+// legitimate names for it. Every caller walks the RESOLVING `obj.relationships()`
+// (codegen-ts's relation-resolver, runtime-ts's n2m-resolver, docs-site's link-graph)
+// and passes the entity it is ITERATING, which for an inherited relationship is not
+// the one that declared it. So the DECLARING entity is resolved here from `rel.parent`
+// (same shape as the #368 loader fix, validation-passes' `declaringEntity = rel.parent
+// ?? obj`), and the passed `source` is kept alongside it rather than discarded: a
+// junction FK usually references the CONCRETE entity, because the abstract base has no
+// table, while @objectRef on an inherited self-join names the base. Both are accepted,
+// for the self-join classification and the hetero reference match alike. `source` is
+// also the fallback when `rel` has no entity parent, which keeps the exported signature
+// unchanged. Not covered: a junction reference naming an entity strictly BETWEEN the
+// base and the navigating entity in a deeper hierarchy.
+//
+// The subject comparison is made on RESOLVED OBJECT IDENTITY, not on stripped
+// short names, matching the Java reference (M2MFields.java). Bare-name equality
+// cannot tell `a::NodeBase` from `b::NodeBase`, so once the subject set held two
+// names a genuine CROSS-PACKAGE hetero M:N whose target shares a short name with
+// the subject read as a self-join and refused to derive. Scoped deliberately to
+// this one predicate — every other name comparison in this file is untouched.
 import { stripPackage } from "../../naming.js";
+import { TYPE_OBJECT } from "../../shared/base-types.js";
+import { PACKAGE_SEPARATOR } from "../../shared/structural.js";
 /** Thrown when a M:N relationship's junction FK fields cannot be derived. */
 export class M2MDerivationError extends Error {
     code = "ERR_INVALID_RELATIONSHIP";
@@ -30,20 +53,53 @@ export class M2MDerivationError extends Error {
 function refFkField(ref) {
     return ref.fields[0];
 }
+/**
+ * The root entity a reference name denotes, or undefined. Mirrors the Java
+ * reference's `M2MFields.findObject` exactly: a FULLY-QUALIFIED name (one
+ * containing "::") resolves EXACTLY on the object's package-folded key, never a
+ * bare-tail fallback; a bare name matches a short name, first match wins (the
+ * bare-collision case is the deferred follow-up Java records as issue #174).
+ *
+ * This exists so the SUBJECT comparison below can be made on object IDENTITY the
+ * way Java's already is. A bare-name compare cannot tell `a::NodeBase` from
+ * `b::NodeBase`, which made a genuine cross-package hetero M:N read as a
+ * self-join the moment the subject set held two names.
+ */
+function findEntity(root, name) {
+    if (name === undefined || name === "")
+        return undefined;
+    const objects = root.objects();
+    if (name.includes(PACKAGE_SEPARATOR)) {
+        return objects.find((o) => o.resolutionKey() === name);
+    }
+    const bare = stripPackage(name);
+    return objects.find((o) => o.name === bare);
+}
 /**
  * Derive the source/target junction FK fields for a M:N relationship.
  *
  * @param rel     the M:N relationship (carries @objectRef + @through + optional
  *                @sourceRefField / @symmetric)
- * @param source  the entity declaring `rel`
+ * @param source  the entity the caller is navigating from. Accepted alongside
+ *                `rel.parent` as a name for the relationship's subject, and used
+ *                as the declaring entity when `rel` has no entity parent.
  * @param root    the loaded model root (to find the junction entity)
  * @throws M2MDerivationError when the junction is missing/malformed or the
  *         self-join is ambiguous.
  */
 export function deriveM2MFields(rel, source, root) {
+    // The entity that DECLARES `rel` — see the header note. `rel.parent` is the
+    // owning entity for both an own declaration and an inherited one (an unmodified
+    // inherited child is the SAME node object, reused in place by
+    // MetaData._effectiveChildren; an override is a genuinely different node whose
+    // parent is the overriding entity, which is also correct).
+    const relParent = rel.parent;
+    const declaringEntity = relParent !== undefined && relParent.type === TYPE_OBJECT
+        ? relParent
+        : source;
     const throughName = rel.through;
     if (throughName === undefined) {
-        throw new M2MDerivationError(`relationship "${source.name}.${rel.name}" is missing @through (required for M:N derivation)`);
+        throw new M2MDerivationError(`relationship "${declaringEntity.name}.${rel.name}" is missing @through (required for M:N derivation)`);
     }
     // @through may be package-qualified (FQN); findObject is keyed by bare name,
     // so fall back to the bare suffix after the last "::". Mirrors the
@@ -54,27 +110,66 @@ export function deriveM2MFields(rel, source, root) {
             ? root.findObject(throughName.slice(throughName.lastIndexOf("::") + 2))
             : undefined);
     if (junction === undefined) {
-        throw new M2MDerivationError(`relationship "${source.name}.${rel.name}" @through "${throughName}" does not resolve to an entity`);
+        throw new M2MDerivationError(`relationship "${declaringEntity.name}.${rel.name}" @through "${throughName}" does not resolve to an entity`);
     }
     const targetName = rel.objectRef;
     if (targetName === undefined) {
-        throw new M2MDerivationError(`relationship "${source.name}.${rel.name}" is missing @objectRef (the M:N target)`);
+        throw new M2MDerivationError(`relationship "${declaringEntity.name}.${rel.name}" is missing @objectRef (the M:N target)`);
     }
     const refs = junction.referenceIdentities();
     if (refs.length !== 2) {
-        throw new M2MDerivationError(`junction "${throughName}" for relationship "${source.name}.${rel.name}" must declare exactly two ` +
+        throw new M2MDerivationError(`junction "${throughName}" for relationship "${declaringEntity.name}.${rel.name}" must declare exactly two ` +
             `identity.reference children (found ${refs.length})`);
     }
-    const isSelfJoin = stripPackage(targetName) === source.name;
+    // The relationship's SUBJECT — the entity the M:N hangs off. Under `extends`
+    // there are two legitimate names for it and BOTH occur in real models:
+    //   * the DECLARING entity (rel.parent) — what @objectRef names for a self-join
+    //     declared on an abstract base, and what a junction reference names when the
+    //     author points the FK at the base type;
+    //   * the NAVIGATING entity (`source`) — the concrete entity the caller is
+    //     iterating, which is what a junction FK usually references, because that is
+    //     the entity with the physical table.
+    // Accepting either is what makes the derivation independent of which entity's
+    // effective view reached the relationship. (Not covered: a junction reference
+    // naming an entity strictly BETWEEN the declaring base and the navigating
+    // entity in a deeper hierarchy — no model does that, and widening to the whole
+    // super chain would make the "must declare one identity.reference to ..." error
+    // unfalsifiable.)
+    const subjectNames = declaringEntity.name === source.name
+        ? [declaringEntity.name]
+        : [declaringEntity.name, source.name];
+    const subjectLabel = subjectNames.map((n) => `"${n}"`).join(" or ");
+    // Compared by resolved object IDENTITY, matching the Java reference. A
+    // stripPackage() compare cannot distinguish `a::NodeBase` from `b::NodeBase`,
+    // so with two names in the set a genuine cross-package hetero M:N read as a
+    // self-join and refused to derive.
+    const isSubject = (entity) => entity !== undefined && (entity === declaringEntity || entity === source);
+    const isSubjectName = (name) => name !== undefined && subjectNames.includes(stripPackage(name));
+    // Defensive bare fallback when @objectRef does not resolve — loader validation
+    // normally guarantees it does. Same carve-out the Java reference makes.
+    const targetEntityNode = findEntity(root, targetName);
+    const isSelfJoin = targetEntityNode !== undefined
+        ? isSubject(targetEntityNode)
+        : isSubjectName(targetName);
     if (!isSelfJoin) {
-        // Hetero: match each reference by the entity it resolves to.
-        const sourceRef = refs.find((r) => r.targetEntity !== undefined && stripPackage(r.targetEntity) === source.name);
-        const targetRef = refs.find((r) => r.targetEntity !== undefined && stripPackage(r.targetEntity) === stripPackage(targetName));
+        // Hetero: match each reference by the ENTITY OBJECT it resolves to.
+        const sourceRef = refs.find((r) => isSubject(findEntity(root, r.targetEntity)));
+        // Identity here too. The two searches are INDEPENDENT — nothing excludes
+        // sourceRef from this one, unlike the directed self-join branch below — so a
+        // bare compare could match the SOURCE-side reference again whenever the
+        // target's short name equals the source's, and silently return (srcFk, srcFk).
+        // Structurally unreachable while isSelfJoin was also bare (a colliding short
+        // name forced the self-join branch); making only isSelfJoin identity-based
+        // broke that invariant. Java matches identity on both sides (findRefToSubject
+        // + findRefToObject) and never had the hole.
+        const targetRef = targetEntityNode !== undefined
+            ? refs.find((r) => findEntity(root, r.targetEntity) === targetEntityNode)
+            : refs.find((r) => r.targetEntity !== undefined && stripPackage(r.targetEntity) === stripPackage(targetName));
         const sourceField = sourceRef ? refFkField(sourceRef) : undefined;
         const targetField = targetRef ? refFkField(targetRef) : undefined;
         if (sourceField === undefined || targetField === undefined) {
-            throw new M2MDerivationError(`junction "${throughName}" for relationship "${source.name}.${rel.name}" must declare one ` +
-                `identity.reference to "${source.name}" and one to "${stripPackage(targetName)}"`);
+            throw new M2MDerivationError(`junction "${throughName}" for relationship "${declaringEntity.name}.${rel.name}" must declare one ` +
+                `identity.reference to ${subjectLabel} and one to "${stripPackage(targetName)}"`);
         }
         return { sourceField, targetField };
     }
@@ -84,25 +179,25 @@ export function deriveM2MFields(rel, source, root) {
         const a = refFkField(refs[0]);
         const b = refFkField(refs[1]);
         if (a === undefined || b === undefined) {
-            throw new M2MDerivationError(`symmetric junction "${throughName}" for "${source.name}.${rel.name}" has a reference with no @fields`);
+            throw new M2MDerivationError(`symmetric junction "${throughName}" for "${declaringEntity.name}.${rel.name}" has a reference with no @fields`);
         }
         return { sourceField: a, targetField: b };
     }
     const sourceRefField = rel.sourceRefField;
     if (sourceRefField === undefined) {
-        throw new M2MDerivationError(`self-join relationship "${source.name}.${rel.name}" through "${throughName}" is ambiguous: ` +
+        throw new M2MDerivationError(`self-join relationship "${declaringEntity.name}.${rel.name}" through "${throughName}" is ambiguous: ` +
             `set @sourceRefField (directed) or @symmetric (undirected)`);
     }
     // Directed self-join: @sourceRefField names the source-side FK; the other ref is the target.
     const sourceRef = refs.find((r) => refFkField(r) === sourceRefField);
     if (sourceRef === undefined) {
-        throw new M2MDerivationError(`@sourceRefField "${sourceRefField}" on "${source.name}.${rel.name}" does not match any ` +
+        throw new M2MDerivationError(`@sourceRefField "${sourceRefField}" on "${declaringEntity.name}.${rel.name}" does not match any ` +
             `identity.reference FK field on junction "${throughName}"`);
     }
     const targetRef = refs.find((r) => r !== sourceRef);
     const targetField = targetRef ? refFkField(targetRef) : undefined;
     if (targetField === undefined) {
-        throw new M2MDerivationError(`junction "${throughName}" for "${source.name}.${rel.name}" has no distinct target-side reference`);
+        throw new M2MDerivationError(`junction "${throughName}" for "${declaringEntity.name}.${rel.name}" has no distinct target-side reference`);
     }
     return { sourceField: sourceRefField, targetField };
 }

package/dist/core/relationship/derive-m2m-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-m2m-fields.js","sourceRoot":"","sources":["../../../src/core/relationship/derive-m2m-fields.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"derive-m2m-fields.js","sourceRoot":"","sources":["../../../src/core/relationship/derive-m2m-fields.ts"],"names":[],"mappings":"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"}

package/dist/core/relationship/find-reference.d.ts

@@ -8,15 +8,31 @@ export interface ReferenceLookup {
     /** The matching identity.reference declaration on `holder`. */
     readonly referenceIdentity: MetaReferenceIdentity;
 }
+/**
+ * Every identity.reference on `a` or `b` whose @references targets the other
+ * side, `a` walked first. Comparison is package-insensitive: `@references` may
+ * be a bare entity name ("User") or a fully-qualified one ("pkg::User"); both
+ * match `other.name`.
+ *
+ * #368: an entity may legally declare more than one identity.reference onto
+ * the same target (e.g. Match.homeTeamRef and Match.awayTeamRef both -> Team).
+ * Callers that must not silently guess which one is meant enumerate here and
+ * report the ambiguity themselves; see also `findReferenceBetween`, which
+ * keeps the historical first-match contract for callers that legitimately
+ * expect at most one reference between the pair.
+ */
+export declare function findReferencesBetween(a: MetaObject, b: MetaObject): ReferenceLookup[];
 /**
  * Find an identity.reference on either `a` or `b` whose @references targets the
  * other side. Returns undefined if neither side declares one.
  *
- * Comparison is package-insensitive: `@references` may be a bare entity name
- * ("User") or a fully-qualified one ("pkg::User"); both match `other.name`.
- *
- * If both sides declare references targeting each other (rare, but legal for
- * mutual 1:1), returns the first found, walking `a` first.
+ * Delegates to `findReferencesBetween` and returns its first entry — kept for
+ * backward compatibility (this is exported public API) and for the mutual-1:1
+ * case where both sides declare references targeting each other. #368: two
+ * references onto the SAME target are also legal and indistinguishable from
+ * here — a caller that must not guess which one is meant should call
+ * `findReferencesBetween` directly and handle ambiguity explicitly rather than
+ * relying on this function's first-match behaviour.
  */
 export declare function findReferenceBetween(a: MetaObject, b: MetaObject): ReferenceLookup | undefined;
 //# sourceMappingURL=find-reference.d.ts.map

package/dist/core/relationship/find-reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-reference.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/find-reference.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAG1E,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,eAAe,GAAG,SAAS,CAS7B"}
+{"version":3,"file":"find-reference.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/find-reference.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAG1E,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,CAAC;CACnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,eAAe,EAAE,CAUnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,eAAe,GAAG,SAAS,CAE7B"}

package/dist/core/relationship/find-reference.js

@@ -7,23 +7,42 @@
 // migration schema comparison.
 import { stripPackage } from "../../naming.js";
 /**
- * Find an identity.reference on either `a` or `b` whose @references targets the
- * other side. Returns undefined if neither side declares one.
- *
- * Comparison is package-insensitive: `@references` may be a bare entity name
- * ("User") or a fully-qualified one ("pkg::User"); both match `other.name`.
+ * Every identity.reference on `a` or `b` whose @references targets the other
+ * side, `a` walked first. Comparison is package-insensitive: `@references` may
+ * be a bare entity name ("User") or a fully-qualified one ("pkg::User"); both
+ * match `other.name`.
  *
- * If both sides declare references targeting each other (rare, but legal for
- * mutual 1:1), returns the first found, walking `a` first.
+ * #368: an entity may legally declare more than one identity.reference onto
+ * the same target (e.g. Match.homeTeamRef and Match.awayTeamRef both -> Team).
+ * Callers that must not silently guess which one is meant enumerate here and
+ * report the ambiguity themselves; see also `findReferenceBetween`, which
+ * keeps the historical first-match contract for callers that legitimately
+ * expect at most one reference between the pair.
  */
-export function findReferenceBetween(a, b) {
+export function findReferencesBetween(a, b) {
+    const found = [];
     for (const [holder, other] of [[a, b], [b, a]]) {
         for (const ref of holder.referenceIdentities()) {
             if (stripPackage(ref.targetEntity) === other.name) {
-                return { holder, other, referenceIdentity: ref };
+                found.push({ holder, other, referenceIdentity: ref });
             }
         }
     }
-    return undefined;
+    return found;
+}
+/**
+ * Find an identity.reference on either `a` or `b` whose @references targets the
+ * other side. Returns undefined if neither side declares one.
+ *
+ * Delegates to `findReferencesBetween` and returns its first entry — kept for
+ * backward compatibility (this is exported public API) and for the mutual-1:1
+ * case where both sides declare references targeting each other. #368: two
+ * references onto the SAME target are also legal and indistinguishable from
+ * here — a caller that must not guess which one is meant should call
+ * `findReferencesBetween` directly and handle ambiguity explicitly rather than
+ * relying on this function's first-match behaviour.
+ */
+export function findReferenceBetween(a, b) {
+    return findReferencesBetween(a, b)[0];
 }
 //# sourceMappingURL=find-reference.js.map

package/dist/core/relationship/find-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-reference.js","sourceRoot":"","sources":["../../../src/core/relationship/find-reference.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,2EAA2E;AAC3E,0EAA0E;AAC1E,+BAA+B;AAI/B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAW/C;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,CAAa,EACb,CAAa;IAEb,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAU,EAAE,CAAC;QACxD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC/C,IAAI,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;gBAClD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"find-reference.js","sourceRoot":"","sources":["../../../src/core/relationship/find-reference.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,2EAA2E;AAC3E,0EAA0E;AAC1E,+BAA+B;AAI/B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAW/C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,CAAa,EACb,CAAa;IAEb,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAU,EAAE,CAAC;QACxD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC/C,IAAI,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;gBAClD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,CAAa,EACb,CAAa;IAEb,OAAO,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/core/relationship/relationship-definition.embedded.js

@@ -5,7 +5,7 @@ export const RELATIONSHIP_DEFINITION = {
             "type": "relationship",
             "subType": "base",
             "description": "Abstract relationship base — shared shape for the concrete association/aggregation/composition subtypes; not authored directly. A `relationship.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED): this subtype is a registry anchor concrete subtypes inherit from, never a node in a document.",
-            "rules": "@cardinality is an open string at the metamodel level ('one'/'many', and Java-canonical composite forms such as 'many-to-one'); @objectRef names the target entity. M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. @onDelete/@onUpdate carry referential actions (cascade/set-null/restrict/no-action).",
+            "rules": "@cardinality is an open string at the metamodel level ('one'/'many', and Java-canonical composite forms such as 'many-to-one'); @objectRef names the target entity. M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction, or on a @cardinality:'one' relationship names which of several identity.reference nodes onto the same target it navigates when name-pairing does not resolve it uniquely; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. @onDelete/@onUpdate carry referential actions (cascade/set-null/restrict/no-action).",
             "children": [
                 {
                     "type": "attr",
@@ -37,7 +37,7 @@ export const RELATIONSHIP_DEFINITION = {
                     "name": "sourceRefField",
                     "min": 0,
                     "max": 1,
-                    "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+                    "description": "Disambiguates which reference/FK field a relationship uses when more than one candidate exists: on a directed self-join M:N it names the junction's source-side reference (mutually exclusive with @symmetric), and on a @cardinality:'one' relationship it names which of several identity.reference nodes onto the same target the relationship navigates when name-pairing does not resolve it uniquely."
                 },
                 {
                     "type": "attr",
@@ -82,7 +82,7 @@ export const RELATIONSHIP_DEFINITION = {
             "subType": "association",
             "description": "A plain reference to another entity — no ownership; the target has an independent lifecycle (default @onDelete restrict).",
             "whenToUse": "A plain directed reference to another entity, no ownership or cascade. The lightest link — when you just need to point at another entity.",
-            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).",
+            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction, or on a @cardinality:'one' relationship names which of several identity.reference nodes onto the same target it navigates when name-pairing does not resolve it uniquely; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).",
             "children": [
                 {
                     "type": "attr",
@@ -114,7 +114,7 @@ export const RELATIONSHIP_DEFINITION = {
                     "name": "sourceRefField",
                     "min": 0,
                     "max": 1,
-                    "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+                    "description": "Disambiguates which reference/FK field a relationship uses when more than one candidate exists: on a directed self-join M:N it names the junction's source-side reference (mutually exclusive with @symmetric), and on a @cardinality:'one' relationship it names which of several identity.reference nodes onto the same target the relationship navigates when name-pairing does not resolve it uniquely."
                 },
                 {
                     "type": "attr",
@@ -159,7 +159,7 @@ export const RELATIONSHIP_DEFINITION = {
             "subType": "aggregation",
             "description": "A shared/independent containment — the parent groups the target but does not own its lifecycle (default @onDelete set-null).",
             "whenToUse": "One entity groups others it does NOT own (children outlive the parent; delete sets the FK null). Use instead of composition when there is no ownership.",
-            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).",
+            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction, or on a @cardinality:'one' relationship names which of several identity.reference nodes onto the same target it navigates when name-pairing does not resolve it uniquely; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).",
             "children": [
                 {
                     "type": "attr",
@@ -191,7 +191,7 @@ export const RELATIONSHIP_DEFINITION = {
                     "name": "sourceRefField",
                     "min": 0,
                     "max": 1,
-                    "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+                    "description": "Disambiguates which reference/FK field a relationship uses when more than one candidate exists: on a directed self-join M:N it names the junction's source-side reference (mutually exclusive with @symmetric), and on a @cardinality:'one' relationship it names which of several identity.reference nodes onto the same target the relationship navigates when name-pairing does not resolve it uniquely."
                 },
                 {
                     "type": "attr",
@@ -236,7 +236,7 @@ export const RELATIONSHIP_DEFINITION = {
             "subType": "composition",
             "description": "An owned containment — the parent owns the target's lifecycle; deleting the parent deletes the children (default @onDelete cascade).",
             "whenToUse": "You need a parent that OWNS a child collection (one-to-many, cascade on delete). Declare it to generate the FK + typed navigation instead of a bare FK field + hand-written joins.",
-            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).",
+            "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction, or on a @cardinality:'one' relationship names which of several identity.reference nodes onto the same target it navigates when name-pairing does not resolve it uniquely; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).",
             "children": [
                 {
                     "type": "attr",
@@ -268,7 +268,7 @@ export const RELATIONSHIP_DEFINITION = {
                     "name": "sourceRefField",
                     "min": 0,
                     "max": 1,
-                    "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+                    "description": "Disambiguates which reference/FK field a relationship uses when more than one candidate exists: on a directed self-join M:N it names the junction's source-side reference (mutually exclusive with @symmetric), and on a @cardinality:'one' relationship it names which of several identity.reference nodes onto the same target the relationship navigates when name-pairing does not resolve it uniquely."
                 },
                 {
                     "type": "attr",

package/dist/core/relationship/relationship-definition.embedded.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relationship-definition.embedded.js","sourceRoot":"","sources":["../../../src/core/relationship/relationship-definition.embedded.ts"],"names":[],"mappings":"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"}

package/dist/core/relationship/resolve-relationship-reference.d.ts

@@ -0,0 +1,27 @@
+import type { MetaObject } from "../object/meta-object.js";
+import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
+/**
+ * The set of lowercased names a candidate reference answers to: its own name
+ * and its FK field, each with and without one stripped suffix.
+ */
+export declare function referencePairingKeys(ref: MetaReferenceIdentity): Set<string>;
+/**
+ * Every identity.reference on `holder` whose @references targets `targetEntity`.
+ * Package-insensitive on both sides: @references and @objectRef may each be bare
+ * or fully qualified.
+ */
+export declare function referenceCandidatesFor(holder: MetaObject, targetEntity: string): MetaReferenceIdentity[];
+/**
+ * Which identity.reference does this `@cardinality: one` relationship navigate
+ * through? The ladder, in order:
+ *
+ *   1. exactly one candidate            -> that one (the common case; unchanged behaviour)
+ *   2. `@sourceRefField` declared       -> the candidate whose FK field it names
+ *   3. exactly one candidate name-pairs -> that one
+ *   4. otherwise                        -> undefined (caller reports the ambiguity)
+ *
+ * Returns undefined for "no candidate" and "cannot choose" alike; callers that
+ * need to tell them apart use referenceCandidatesFor().
+ */
+export declare function resolveRelationshipReference(holder: MetaObject, relationshipName: string, targetEntity: string, sourceRefField?: string): MetaReferenceIdentity | undefined;
+//# sourceMappingURL=resolve-relationship-reference.d.ts.map

package/dist/core/relationship/resolve-relationship-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-relationship-reference.d.ts","sourceRoot":"","sources":["../../../src/core/relationship/resolve-relationship-reference.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAwB1E;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,qBAAqB,GAAG,GAAG,CAAC,MAAM,CAAC,CAW5E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,MAAM,GACnB,qBAAqB,EAAE,CAOzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,UAAU,EAClB,gBAAgB,EAAE,MAAM,EACxB,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,MAAM,GACtB,qBAAqB,GAAG,SAAS,CAYnC"}

package/dist/core/relationship/resolve-relationship-reference.js

@@ -0,0 +1,84 @@
+// Association -> identity.reference resolution (issue #368).
+//
+// An entity may declare more than one identity.reference onto the SAME target
+// entity (Match.homeTeamRef and Match.awayTeamRef both -> Team). A
+// `@cardinality: one` relationship names only its target, so when two
+// references match, the target alone cannot say which FK the navigation uses.
+// Taking the first match emits a join on the wrong column that typechecks, has
+// correct DDL and passes verify — so the ladder below resolves it explicitly or
+// not at all. ADR-0029 §5: ambiguity is a load error naming the candidates.
+import { stripPackage } from "../../naming.js";
+/**
+ * Trailing suffixes stripped from a CANDIDATE's name/FK field when building its
+ * pairing keys. Ordered — first match wins, so "reference" is tested before
+ * "ref". Never applied to the relationship name (see referencePairingKeys).
+ */
+const PAIRING_SUFFIXES = ["reference", "ref", "id", "key"];
+function stripOneSuffix(value) {
+    for (const suffix of PAIRING_SUFFIXES) {
+        if (value.length > suffix.length && value.endsWith(suffix)) {
+            return value.slice(0, value.length - suffix.length);
+        }
+    }
+    return value;
+}
+/** The FK field a reference is anchored on (first field; composite FKs pair on their first column). */
+function refFkField(ref) {
+    return ref.fields.length > 0 ? ref.fields[0] : undefined;
+}
+/**
+ * The set of lowercased names a candidate reference answers to: its own name
+ * and its FK field, each with and without one stripped suffix.
+ */
+export function referencePairingKeys(ref) {
+    const keys = new Set();
+    const add = (value) => {
+        if (!value)
+            return;
+        const lower = value.toLowerCase();
+        keys.add(lower);
+        keys.add(stripOneSuffix(lower));
+    };
+    add(ref.name);
+    add(refFkField(ref));
+    return keys;
+}
+/**
+ * Every identity.reference on `holder` whose @references targets `targetEntity`.
+ * Package-insensitive on both sides: @references and @objectRef may each be bare
+ * or fully qualified.
+ */
+export function referenceCandidatesFor(holder, targetEntity) {
+    const target = stripPackage(targetEntity);
+    // ADR-0039: resolving — referenceIdentities() honors references inherited via extends.
+    return holder
+        .referenceIdentities()
+        .filter((ref) => stripPackage(ref.targetEntity ?? "") === target)
+        .filter((ref) => refFkField(ref) !== undefined);
+}
+/**
+ * Which identity.reference does this `@cardinality: one` relationship navigate
+ * through? The ladder, in order:
+ *
+ *   1. exactly one candidate            -> that one (the common case; unchanged behaviour)
+ *   2. `@sourceRefField` declared       -> the candidate whose FK field it names
+ *   3. exactly one candidate name-pairs -> that one
+ *   4. otherwise                        -> undefined (caller reports the ambiguity)
+ *
+ * Returns undefined for "no candidate" and "cannot choose" alike; callers that
+ * need to tell them apart use referenceCandidatesFor().
+ */
+export function resolveRelationshipReference(holder, relationshipName, targetEntity, sourceRefField) {
+    const candidates = referenceCandidatesFor(holder, targetEntity);
+    if (candidates.length === 0)
+        return undefined;
+    if (candidates.length === 1)
+        return candidates[0];
+    if (sourceRefField !== undefined && sourceRefField !== "") {
+        return candidates.find((ref) => refFkField(ref) === sourceRefField);
+    }
+    const wanted = relationshipName.toLowerCase();
+    const paired = candidates.filter((ref) => referencePairingKeys(ref).has(wanted));
+    return paired.length === 1 ? paired[0] : undefined;
+}
+//# sourceMappingURL=resolve-relationship-reference.js.map

package/dist/core/relationship/resolve-relationship-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-relationship-reference.js","sourceRoot":"","sources":["../../../src/core/relationship/resolve-relationship-reference.ts"],"names":[],"mappings":"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"}