@metaobjectsdev/metadata 1.0.2 → 1.0.4-rc.1

package/dist/serializer-json.js

@@ -8,7 +8,8 @@
 import { ATTR_PREFIX, TYPE_SUBTYPE_SEPARATOR, RESERVED_KEY_NAME, RESERVED_KEY_PACKAGE, RESERVED_KEY_EXTENDS, RESERVED_KEY_ABSTRACT, RESERVED_KEY_IS_ARRAY, RESERVED_KEY_CHILDREN, } from "./shared/structural.js";
 import { ATTR_SUBTYPE_STRING, ATTR_SUBTYPE_INT, ATTR_SUBTYPE_LONG, ATTR_SUBTYPE_DOUBLE, ATTR_SUBTYPE_BOOLEAN, ATTR_SUBTYPE_STRINGARRAY, } from "./core/attr/attr-constants.js";
 import { SOURCE_SUBTYPE_RDB, SOURCE_ATTR_KIND, SOURCE_ATTR_TABLE, DEFAULT_SOURCE_KIND, PHYSICAL_NAME_ATTR_BY_KIND, } from "./persistence/source/source-constants.js";
-import { TYPE_SOURCE } from "./shared/base-types.js";
+import { TYPE_METADATA, TYPE_SOURCE, SUBTYPE_ROOT } from "./shared/base-types.js";
+import { packageOfResolutionKey } from "./naming.js";
 const SOURCE_RDB_FUSED_KEY = `${TYPE_SOURCE}${TYPE_SUBTYPE_SEPARATOR}${SOURCE_SUBTYPE_RDB}`;
 export function serializeJson(model, opts) {
     const indent = opts?.indent ?? 2;
@@ -236,4 +237,45 @@ function sortAttrValue(value) {
     }
     return value;
 }
+// ---------------------------------------------------------------------------
+// serializeSharedDocument — the FR-023 shared-model artifact form
+//
+// One canonical-JSON `metadata.root` document holding top-level nodes from any
+// number of packages: NO root `package`, and every top-level node carries its own
+// explicit `package` (a root-level child may name its package — ADR-0029's
+// addressing model — so the document re-loads to the same resolution keys in
+// every port). Each node is its canonicalSerialize form: raw own-layer, `extends`
+// preserved (not flattened), attribute keys alphabetized, the FR-016 physical-name
+// rewrite applied. Top-level nodes are sorted by resolution key; each node's
+// children keep their authored order. Body key order: name, package, then the
+// canonical rest. Byte-identical to Python's `serialize_shared_document`.
+// ---------------------------------------------------------------------------
+export function serializeSharedDocument(nodes) {
+    const sorted = [...nodes].sort((a, b) => {
+        const ka = a.resolutionKey();
+        const kb = b.resolutionKey();
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const children = sorted.map((node) => {
+        const pkg = packageOfResolutionKey(node.resolutionKey());
+        if (pkg === "") {
+            throw new Error(`serializeSharedDocument: ${node.resolutionKey()} has no package; a shared document carries only packaged nodes`);
+        }
+        const parsed = JSON.parse(canonicalSerialize(node));
+        const [fused, body] = Object.entries(parsed)[0];
+        // The node's own `package` (if it declared one) is replaced by the RESOLVED
+        // one: a node inheriting its file's root package declares none of its own.
+        const ordered = {
+            [RESERVED_KEY_NAME]: body[RESERVED_KEY_NAME],
+            [RESERVED_KEY_PACKAGE]: pkg,
+        };
+        for (const [key, value] of Object.entries(body)) {
+            if (key !== RESERVED_KEY_NAME && key !== RESERVED_KEY_PACKAGE)
+                ordered[key] = value;
+        }
+        return { [fused]: ordered };
+    });
+    const doc = { [fusedKey(TYPE_METADATA, SUBTYPE_ROOT)]: { [RESERVED_KEY_CHILDREN]: children } };
+    return JSON.stringify(doc, null, 2) + "\n";
+}
 //# sourceMappingURL=serializer-json.js.map

package/dist/serializer-json.js.map

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

package/dist/vocabulary-rewrite-yaml.d.ts

@@ -0,0 +1,2 @@
+export { rewriteYamlDocument, type YamlRewriteResult } from "./core/vocabulary-rewrite-yaml.js";
+//# sourceMappingURL=vocabulary-rewrite-yaml.d.ts.map

package/dist/vocabulary-rewrite-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary-rewrite-yaml.d.ts","sourceRoot":"","sources":["../src/vocabulary-rewrite-yaml.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/vocabulary-rewrite-yaml.js

@@ -0,0 +1,22 @@
+// @metaobjectsdev/metadata/vocabulary-rewrite-yaml — the YAML arm of `meta upgrade`.
+//
+// The implementation stays under `core/`, beside the canonical-JSON rewriter it mirrors.
+// This file exists so the SUBPATH NAME mirrors the layout under `src/`, which is what
+// `tsconfig.scripts.json`'s `@metaobjectsdev/metadata/*` → `src/*` mapping requires.
+//
+// Nesting is NOT the problem — the `*` matches across `/`, which is why
+// `@metaobjectsdev/codegen-ts/templates/entity-file` resolves to
+// `src/templates/entity-file.ts` perfectly well. The problem was a subpath NAMED
+// `vocabulary-rewrite-yaml` whose source sat at `src/core/vocabulary-rewrite-yaml.ts`:
+// the substitution yields `src/vocabulary-rewrite-yaml`, and that is not where the module
+// is. Renaming the export to `./core/vocabulary-rewrite-yaml` would also have satisfied
+// the rule and was the cheaper edit, but this package is published and that subpath is
+// public API, so the name stays and the layout moves to meet it.
+//
+// When the mapping misses, tsc falls through to `node_modules` and reads `dist/` — present
+// for anyone who has built, absent on a fresh CI checkout where the `gates` lane runs
+// `bun install` and never builds. `./library` shipped that way and took the lane down;
+// this one had not been imported from anywhere `scripts/` typechecks, so it was latent.
+// `cli/test/subpath-resolves-under-scripts-paths.test.ts` now gates the class.
+export { rewriteYamlDocument } from "./core/vocabulary-rewrite-yaml.js";
+//# sourceMappingURL=vocabulary-rewrite-yaml.js.map

package/dist/vocabulary-rewrite-yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary-rewrite-yaml.js","sourceRoot":"","sources":["../src/vocabulary-rewrite-yaml.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,yFAAyF;AACzF,sFAAsF;AACtF,qFAAqF;AACrF,EAAE;AACF,wEAAwE;AACxE,iEAAiE;AACjE,iFAAiF;AACjF,uFAAuF;AACvF,0FAA0F;AAC1F,wFAAwF;AACxF,uFAAuF;AACvF,iEAAiE;AACjE,EAAE;AACF,2FAA2F;AAC3F,sFAAsF;AACtF,uFAAuF;AACvF,wFAAwF;AACxF,+EAA+E;AAC/E,OAAO,EAAE,mBAAmB,EAA0B,MAAM,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/metadata",
-  "version": "1.0.2",
+  "version": "1.0.4-rc.1",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,9 +17,9 @@
       "default": "./dist/core/index.js"
     },
     "./library": {
-      "bun": "./src/library/library-sources.ts",
-      "types": "./dist/library/library-sources.d.ts",
-      "default": "./dist/library/library-sources.js"
+      "bun": "./src/library/index.ts",
+      "types": "./dist/library/index.d.ts",
+      "default": "./dist/library/index.js"
     },
     "./constants": {
       "bun": "./src/constants.ts",
@@ -27,9 +27,9 @@
       "default": "./dist/constants.js"
     },
     "./vocabulary-rewrite-yaml": {
-      "bun": "./src/core/vocabulary-rewrite-yaml.ts",
-      "types": "./dist/core/vocabulary-rewrite-yaml.d.ts",
-      "default": "./dist/core/vocabulary-rewrite-yaml.js"
+      "bun": "./src/vocabulary-rewrite-yaml.ts",
+      "types": "./dist/vocabulary-rewrite-yaml.d.ts",
+      "default": "./dist/vocabulary-rewrite-yaml.js"
     }
   },
   "files": [

package/src/core/parser-yaml.ts

@@ -85,5 +85,9 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     warnings: result.warnings,
     errors: [...desugarParseErrors, ...result.errors],
     envelopeWarnings: result.envelopeWarnings,
+    // ADR-0055 — pass the deferred-overlay queue through untouched. This door
+    // rebuilds the result to prepend desugar errors, so it has to forward every
+    // member; dropping it left the loader spreading `undefined`.
+    pendingOverlays: result.pendingOverlays,
   };
 }

package/src/core/relationship/derive-m2m-fields.ts

@@ -17,12 +17,35 @@
 //      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 type { MetaObject } from "../object/meta-object.js";
 import type { MetaRoot } from "../../shared/meta-root.js";
 import type { MetaRelationship } from "./meta-relationship.js";
 import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
 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 {
@@ -45,12 +68,36 @@ function refFkField(ref: MetaReferenceIdentity): string | undefined {
   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: MetaRoot, name: string | undefined): MetaObject | undefined {
+  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.
@@ -60,10 +107,21 @@ export function deriveM2MFields(
   source: MetaObject,
   root: MetaRoot,
 ): M2MFields {
+  // 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: MetaObject =
+    relParent !== undefined && relParent.type === TYPE_OBJECT
+      ? (relParent as MetaObject)
+      : source;
+
   const throughName = rel.through;
   if (throughName === undefined) {
     throw new M2MDerivationError(
-      `relationship "${source.name}.${rel.name}" is missing @through (required for M:N derivation)`,
+      `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,
@@ -76,37 +134,79 @@ export function deriveM2MFields(
       : undefined);
   if (junction === undefined) {
     throw new M2MDerivationError(
-      `relationship "${source.name}.${rel.name}" @through "${throughName}" does not resolve to an entity`,
+      `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)`,
+      `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 ` +
+      `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: MetaObject | undefined): boolean =>
+    entity !== undefined && (entity === declaringEntity || entity === source);
+  const isSubjectName = (name: string | undefined): boolean =>
+    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)}"`,
+        `junction "${throughName}" for relationship "${declaringEntity.name}.${rel.name}" must declare one ` +
+          `identity.reference to ${subjectLabel} and one to "${stripPackage(targetName)}"`,
       );
     }
     return { sourceField, targetField };
@@ -119,7 +219,7 @@ export function deriveM2MFields(
     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`,
+        `symmetric junction "${throughName}" for "${declaringEntity.name}.${rel.name}" has a reference with no @fields`,
       );
     }
     return { sourceField: a, targetField: b };
@@ -128,7 +228,7 @@ export function deriveM2MFields(
   const sourceRefField = rel.sourceRefField;
   if (sourceRefField === undefined) {
     throw new M2MDerivationError(
-      `self-join relationship "${source.name}.${rel.name}" through "${throughName}" is ambiguous: ` +
+      `self-join relationship "${declaringEntity.name}.${rel.name}" through "${throughName}" is ambiguous: ` +
         `set @sourceRefField (directed) or @symmetric (undirected)`,
     );
   }
@@ -137,7 +237,7 @@ export function deriveM2MFields(
   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 ` +
+      `@sourceRefField "${sourceRefField}" on "${declaringEntity.name}.${rel.name}" does not match any ` +
         `identity.reference FK field on junction "${throughName}"`,
     );
   }
@@ -145,7 +245,7 @@ export function deriveM2MFields(
   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`,
+      `junction "${throughName}" for "${declaringEntity.name}.${rel.name}" has no distinct target-side reference`,
     );
   }
   return { sourceField: sourceRefField, targetField };

package/src/core/relationship/find-reference.ts

@@ -20,25 +20,48 @@ export interface ReferenceLookup {
 }
 
 /**
- * Find an identity.reference on either `a` or `b` whose @references targets the
- * other side. Returns undefined if neither side declares one.
+ * 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`.
  *
- * 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(
+export function findReferencesBetween(
   a: MetaObject,
   b: MetaObject,
-): ReferenceLookup | undefined {
+): ReferenceLookup[] {
+  const found: ReferenceLookup[] = [];
   for (const [holder, other] of [[a, b], [b, a]] as const) {
     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: MetaObject,
+  b: MetaObject,
+): ReferenceLookup | undefined {
+  return findReferencesBetween(a, b)[0];
 }

package/src/core/relationship/relationship-definition.embedded.ts

@@ -13,7 +13,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
       "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",
@@ -45,7 +45,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
           "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",
@@ -90,7 +90,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
       "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",
@@ -122,7 +122,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
           "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",
@@ -167,7 +167,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
       "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",
@@ -199,7 +199,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
           "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",
@@ -244,7 +244,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
       "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",
@@ -276,7 +276,7 @@ export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
           "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",