@metaobjectsdev/metadata 1.0.2 → 1.0.4-rc.1

package/src/loader/meta-data-loader.ts

@@ -13,12 +13,19 @@ import { TypeId, TypeRegistry } from "../registry.js";
 import { coreProviders } from "../core-types.js";
 import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
-import { RESERVED_KEY_CHILDREN, RESERVED_KEY_OVERLAY } from "../shared/structural.js";
+import {
+  PACKAGE_SEPARATOR,
+  RESERVED_KEY_CHILDREN,
+  RESERVED_KEY_NAME,
+  RESERVED_KEY_OVERLAY,
+  RESERVED_KEY_PACKAGE,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "../shared/structural.js";
 import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateOneSideReferenceResolution, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
@@ -34,7 +41,8 @@ import { validateIdentityPassthrough } from "../core/identity/validate-identity-
 import { validateAttrSchema } from "../attr-schema-validate.js";
 import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
 import { InMemoryStringSource } from "./meta-data-source.js";
-import type { ParseOptions, ParseResult } from "../parser-core.js";
+import type { ParseOptions, ParseResult, PendingOverlay } from "../parser-core.js";
+import { expandPackageForPath, applyPendingOverlays } from "../parser-core.js";
 
 // Local mirror of DirectorySource's options shape. Deliberately inlined here
 // (instead of `import type`'d from ./sources/directory-source.js) so the
@@ -97,6 +105,113 @@ function makeSyntheticRoot(): MetaRoot {
   return new MetaRoot(new TypeId(TYPE_METADATA, SUBTYPE_ROOT), "");
 }
 
+// ---------------------------------------------------------------------------
+// declaredTopLevelKeys — structural pre-parse walk (#160, generalized)
+// ---------------------------------------------------------------------------
+
+/** One root-level declaration as `declaredTopLevelKeys` structurally scans it —
+ *  before registry-driven parsing, super resolution, or merge. */
+export interface DeclaredTopLevelKey {
+  /** The wrapper key's TYPE segment (e.g. "object" for "object.entity"). A bare
+   *  wrapper key with no "." is its own type — this walk never consults the
+   *  registry for a default subType, because it never needs the subType. */
+  type: string;
+  /** The resolution key the declaration would carry once parsed: the child's
+   *  own `package` if set (expanded against the root's `package` via
+   *  `expandPackageForPath` when it's a relative, `::`-prefixed path — e.g.
+   *  root `acme` + own `::garage` → `acme::garage`), else the root's
+   *  `package` verbatim, then `::`, then its `name`. Exactly
+   *  `rootChildResolutionKey` (parser-core.ts) — including the relative-path
+   *  expansion, reusing `expandPackageForPath` rather than reimplementing it,
+   *  because a second copy is exactly how this walk and the real parser
+   *  silently disagreed on a relative package (task 17 fix-round-1: this
+   *  function used to return `::garage::Garage` for a fixture the real
+   *  loader resolves to `acme::garage::Garage`). */
+  key: string;
+  /** Whether the declaration's body carries `overlay: true`. */
+  overlay: boolean;
+}
+
+/**
+ * Structurally scan a source's raw content (JSON via `JSON.parse`; sigil-free
+ * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
+ * before desugar) and report every top-level declaration under
+ * `metadata.root.children`: its type, the resolution key it would carry once
+ * parsed, and whether it carries `overlay: true`.
+ *
+ * A declaration with no (string, non-empty) `name` is skipped — a resolution
+ * key can't be computed for it, and the real parser will report it as a
+ * loader error rather than silently reusing or creating a node. Malformed
+ * root shapes (root missing, not an object, `children` absent or not an
+ * array) return `[]` rather than throwing — the real parse loop is where a
+ * genuine structural error surfaces; this walk must never crash a caller
+ * that is only trying to answer "what does this file declare".
+ *
+ * Written for the #160 overlay-only source partition, which ADR-0055 retired —
+ * overlays are now applied in a post-parse pass, so no ordering decision needs
+ * this walk. Its remaining caller is the `meta verify` overlay authoring lint,
+ * which needs per-file declaration provenance precisely because the MERGED tree
+ * has already lost which file contributed which declaration.
+ */
+export async function declaredTopLevelKeys(
+  content: string,
+  format: MetaDataFormat,
+): Promise<ReadonlyArray<DeclaredTopLevelKey>> {
+  // Strip UTF-8 BOM if present (mirrors parseJson / parseYaml).
+  const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+  let parsed: unknown;
+  if (format === "json") {
+    parsed = JSON.parse(normalized);
+  } else if (format === "yaml") {
+    const { parseYamlWithPositions } = await import("../core/yaml-positions-walker.js");
+    parsed = parseYamlWithPositions(normalized).value;
+  } else {
+    return [];
+  }
+  return declaredTopLevelKeysFromParsedRoot(parsed);
+}
+
+/** The structural walk `declaredTopLevelKeys` performs once content is
+ *  structurally parsed — split out so it takes no format/BOM concerns. */
+function declaredTopLevelKeysFromParsedRoot(parsed: unknown): ReadonlyArray<DeclaredTopLevelKey> {
+  if (typeof parsed !== "object" || parsed === null) return [];
+  const parsedRecord = parsed as Record<string, unknown>;
+  // Canonical JSON always fuses the subType onto the root wrapper key
+  // ("metadata.root"); sigil-free YAML authoring writes the bare type
+  // ("metadata") and leaves the default subType to the registry — this
+  // structural walk runs BEFORE desugar/registry resolution, so it must
+  // accept both spellings rather than only ever matching JSON's.
+  const explicitRootKey = `${TYPE_METADATA}${TYPE_SUBTYPE_SEPARATOR}${SUBTYPE_ROOT}`; // "metadata.root"
+  const rootBody = parsedRecord[explicitRootKey] ?? parsedRecord[TYPE_METADATA];
+  if (typeof rootBody !== "object" || rootBody === null) return [];
+  const rawRootPkg = (rootBody as Record<string, unknown>)[RESERVED_KEY_PACKAGE];
+  const rootPkg = typeof rawRootPkg === "string" ? rawRootPkg : "";
+  const children = (rootBody as Record<string, unknown>)[RESERVED_KEY_CHILDREN];
+  if (!Array.isArray(children)) return [];
+
+  const declared: DeclaredTopLevelKey[] = [];
+  for (const child of children) {
+    if (typeof child !== "object" || child === null) continue;
+    // Each child is a single-key wrapper: { "object.entity": { ... } }.
+    for (const [wrapperKey, body] of Object.entries(child as Record<string, unknown>)) {
+      if (typeof body !== "object" || body === null) continue;
+      const bodyRecord = body as Record<string, unknown>;
+      const name = bodyRecord[RESERVED_KEY_NAME];
+      if (typeof name !== "string" || name === "") continue;
+      const dotIdx = wrapperKey.indexOf(TYPE_SUBTYPE_SEPARATOR);
+      const type = dotIdx < 0 ? wrapperKey : wrapperKey.slice(0, dotIdx);
+      const rawOwnPkg = bodyRecord[RESERVED_KEY_PACKAGE];
+      const pkg =
+        typeof rawOwnPkg === "string" && rawOwnPkg !== ""
+          ? expandPackageForPath(rootPkg, rawOwnPkg)
+          : rootPkg;
+      const key = pkg !== "" ? `${pkg}${PACKAGE_SEPARATOR}${name}` : name;
+      declared.push({ type, key, overlay: bodyRecord[RESERVED_KEY_OVERLAY] === true });
+    }
+  }
+  return declared;
+}
+
 // ---------------------------------------------------------------------------
 // MetaDataLoader class
 // ---------------------------------------------------------------------------
@@ -330,92 +445,6 @@ export class MetaDataLoader {
     MetaDataLoader._yamlParser = mod.parseYaml;
   }
 
-  // ---------------------------------------------------------------------------
-  // #160 — overlay-only source partition (stable, overlay-only sources last)
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Stable-partition `sources` so that "overlay-only" sources — every top-level
-   * object declaration carries `overlay: true`, i.e. the source declares no base
-   * objects of its own and only re-opens objects declared elsewhere — are parsed
-   * LAST. Preserves original order within each group.
-   *
-   * A source whose content can't be read or structurally scanned stays in the
-   * base group (never overlay-only) — this partition must never crash the loader;
-   * any genuine read/parse failure surfaces later, in the real parse loop.
-   */
-  private static async _partitionOverlayLast(
-    sources: MetaDataSource[],
-  ): Promise<MetaDataSource[]> {
-    const base: MetaDataSource[] = [];
-    const overlayOnly: MetaDataSource[] = [];
-    for (const source of sources) {
-      let isOverlayOnly = false;
-      try {
-        const content = await source.read();
-        isOverlayOnly = await MetaDataLoader._isOverlayOnlySource(
-          content,
-          source.format,
-        );
-      } catch {
-        isOverlayOnly = false;
-      }
-      (isOverlayOnly ? overlayOnly : base).push(source);
-    }
-    return [...base, ...overlayOnly];
-  }
-
-  /**
-   * Structurally scan a source's raw content (JSON via JSON.parse; sigil-free
-   * authoring YAML via the raw YAML walker — `overlay: true` is a bare key
-   * before desugar) and report whether every top-level object declaration under
-   * `metadata.root.children` carries `overlay: true` (and there is at least one).
-   */
-  private static async _isOverlayOnlySource(
-    content: string,
-    format: MetaDataFormat,
-  ): Promise<boolean> {
-    // Strip UTF-8 BOM if present (mirrors parseJson / parseYaml).
-    const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
-    let parsed: unknown;
-    if (format === "json") {
-      parsed = JSON.parse(normalized);
-    } else if (format === "yaml") {
-      const { parseYamlWithPositions } = await import(
-        "../core/yaml-positions-walker.js"
-      );
-      parsed = parseYamlWithPositions(normalized).value;
-    } else {
-      return false;
-    }
-    return MetaDataLoader._rootIsOverlayOnly(parsed);
-  }
-
-  /** True when the structurally-parsed root has ≥1 child and every top-level
-   * child node carries `overlay: true` (declares no base objects). */
-  private static _rootIsOverlayOnly(parsed: unknown): boolean {
-    if (typeof parsed !== "object" || parsed === null) return false;
-    const rootKey = `${TYPE_METADATA}.${SUBTYPE_ROOT}`; // "metadata.root"
-    const rootBody = (parsed as Record<string, unknown>)[rootKey];
-    if (typeof rootBody !== "object" || rootBody === null) return false;
-    const children = (rootBody as Record<string, unknown>)[RESERVED_KEY_CHILDREN];
-    if (!Array.isArray(children) || children.length === 0) return false;
-    return children.every((child) => {
-      if (typeof child !== "object" || child === null) return false;
-      // Each child is a single-key wrapper: { "object.projection": { ... } }.
-      const bodies = Object.values(child as Record<string, unknown>);
-      return (
-        bodies.length > 0 &&
-        bodies.every(
-          (body) =>
-            typeof body === "object" &&
-            body !== null &&
-            (body as Record<string, unknown>)[RESERVED_KEY_OVERLAY] === true,
-        )
-      );
-    });
-  }
-
   // ---------------------------------------------------------------------------
   // load — async pipeline over MetaDataSource[]
   // ---------------------------------------------------------------------------
@@ -457,20 +486,17 @@ export class MetaDataLoader {
       await MetaDataLoader._ensureYamlParser();
     }
 
-    // #160 — this loader merges DURING parse (each source is streamed into the
-    // accumulating `root` via parseOpts.intoRoot). A source that ONLY re-opens
-    // objects declared elsewhere (every top-level object carries `overlay: true`)
-    // must therefore be parsed AFTER the sources that declare those base objects,
-    // or the overlaid node lands ahead of its base entities — leaving a projection
-    // before its base so order-dependent super-resolution can't resolve its
-    // `extends`/`@via`, and the streaming merge errors ERR_OVERLAY_NO_TARGET.
-    // Directory discovery order is not guaranteed to present base files first
-    // (basename sort can put an overlay-only file first), so stable-partition
-    // overlay-only sources to the END here, making the merge order-independent.
-    // Stable within each group preserves last-writer-wins overlay semantics.
-    sources = await MetaDataLoader._partitionOverlayLast(sources);
-
+    // ADR-0055 — sources are parsed in the order given. Overlays are not applied
+    // during the walk: each parse QUEUES its `overlay: true` declarations and the
+    // loader applies them below, once every base exists. That retired the #160
+    // overlay-only source partition, whose file-level predicate could not rescue a
+    // MIXED file (plain + overlay declarations together) and therefore left the
+    // load order-dependent — and divergent across ports, since every port's
+    // directory walk orders files differently.
     let root: MetaRoot | undefined;
+    // ADR-0055 — every source's queue, concatenated in parse order, which is
+    // already "source order, then declaration order within a source" (G2).
+    const pendingOverlays: PendingOverlay[] = [];
 
     // Parse all sources with super resolution DEFERRED so cross-file super
     // refs work — one source may declare a super target that's defined in a
@@ -495,6 +521,10 @@ export class MetaDataLoader {
         registry: this._registry,
         strict: this._strict,
         deferSuperResolution: true,
+        // ADR-0055 — queue overlays; this loader drains them after every source
+        // is parsed. Without it each document would drain its own queue and an
+        // overlay could still not reach a base declared in a later source.
+        deferOverlays: true,
         sourceName: source.id,
       };
       if (root !== undefined) parseOpts.intoRoot = root;
@@ -507,6 +537,7 @@ export class MetaDataLoader {
         // source). The legacy `warnings` channel still flows into the
         // WARN_LEGACY-wrapping path below for unchanged behavior.
         envelopeWarnings.push(...parseResult.envelopeWarnings);
+        pendingOverlays.push(...parseResult.pendingOverlays);
         root = parseResult.root;
       } catch (err) {
         errors.push(
@@ -517,6 +548,21 @@ export class MetaDataLoader {
       }
     }
 
+    // ADR-0055 — apply every queued overlay now: all plain declarations from all
+    // sources are in the tree (G1), so a base/overlay relation no longer depends
+    // on file order (G4). This runs BEFORE super resolution so a node an overlay
+    // contributes is visible to every `extends` (G5) — the ordering #160's
+    // partition was reaching for, now guaranteed rather than approximated.
+    if (root !== undefined && pendingOverlays.length > 0) {
+      const applied = applyPendingOverlays(pendingOverlays, {
+        registry: this._registry,
+        strict: this._strict,
+      });
+      warnings.push(...applied.warnings);
+      errors.push(...applied.errors);
+      envelopeWarnings.push(...applied.envelopeWarnings);
+    }
+
     // Second pass: resolve every deferred super ref against the full tree.
     // Unresolved refs are always errors (matches the original eager-throw
     // behavior — broken metadata is broken regardless of strict mode).
@@ -606,6 +652,12 @@ export class MetaDataLoader {
       // are invalid on a 1:N relationship.
       errors.push(...validateRelationships(root));
 
+      // Rule (e) — #368: a `@cardinality: one` relationship must resolve to
+      // exactly one identity.reference when its declaring entity holds more
+      // than one onto the same target; an unresolvable case is a load error
+      // naming the candidates (ADR-0029 §5).
+      errors.push(...validateOneSideReferenceResolution(root));
+
       // index.lookup @fields resolution — each index.lookup must name ≥1 field,
       // and every field must exist in the entity's effective (resolved) field set
       // (ADR-0039: resolving accessor, so inherited fields via extends are visible).

package/src/loader/sources/file-source.ts

@@ -27,16 +27,24 @@ async function getReadText(): Promise<(path: string) => Promise<string>> {
   return _readText;
 }
 
+/** Options for {@link FileSource}. */
+export interface FileSourceOptions {
+  /** Explicit source id (e.g. `dep:<name>/<artifact>` for a dependency snapshot).
+   *  Defaults to `basename(path)` when omitted. */
+  id?: string;
+}
+
 /** A metadata source backed by a file on disk. */
 export class FileSource implements MetaDataSource {
   readonly id: string;
   readonly format: MetaDataFormat;
   private readonly _path: string;
 
-  constructor(path: string) {
+  constructor(path: string, opts?: FileSourceOptions) {
     this._path = path;
     // basename() for readable error messages; cross-platform (handles both / and \). Full path retained for read().
-    this.id = basename(path);
+    // An explicit id (FR-023: dependency snapshots load with `dep:<name>/<artifact>`) overrides the default.
+    this.id = opts?.id ?? basename(path);
     this.format = inferFormat(path);
   }
 

package/src/loader/validation-passes.ts

@@ -129,6 +129,11 @@ import {
   CARDINALITY_ONE,
   CARDINALITY_MANY,
 } from "../core/relationship/relationship-constants.js";
+import {
+  referenceCandidatesFor,
+  resolveRelationshipReference,
+} from "../core/relationship/resolve-relationship-reference.js";
+import type { MetaRoot } from "../shared/meta-root.js";
 import { stripPackage } from "../naming.js";
 import {
   FILTER_COMPOSE_OR,
@@ -1938,11 +1943,29 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
 //   (c) When @through is present: the named entity must exist and declare exactly
 //       two identity.reference children; @sourceRefField (if present) must match
 //       one of those references' FK fields → ERR_INVALID_RELATIONSHIP.
-//   (d) @through / @sourceRefField / @symmetric are invalid on a non-M:N
-//       relationship (@cardinality != "many", or no @through) → ERR_INVALID_RELATIONSHIP.
+//   (d) @through / @symmetric are invalid on a non-M:N relationship
+//       (@cardinality != "many", or no @through) → ERR_INVALID_RELATIONSHIP.
+//       @sourceRefField is also invalid there, EXCEPT on @cardinality: "one"
+//       (#368: it then names which of several identity.reference nodes onto
+//       the same target the relationship navigates).
 //
-// Own-relationships only: a relationship is validated on the entity that declares
-// it (matching the own-attrs policy of the other passes).
+// ADR-0039: resolving, not own-only (#368 fix round 3) — every rule above
+// validates a property of the relationship's OWN declaration (its attrs,
+// plus for rule (c) the @through target resolved against the root), so a
+// relationship inherited via extends must be validated wherever it's
+// visible, or a child entity that only SEES the relationship through
+// inheritance could carry a violation no pass ever examines. That makes an
+// inherited, UNMODIFIED relationship visited once per inheriting entity —
+// checked once below (keyed on the relationship node's own identity), not
+// once per entity, using the DECLARING entity (rel.parent) rather than
+// whichever entity's effective view got there first for every piece of
+// context a rule reads (message text, @through's package per ADR-0042, rule
+// (a)'s self-join comparison). That keeps each check's result independent of
+// which entity triggered it, which is what makes "checked once" both
+// sufficient and correct. An override replaces the node in place
+// (MetaData._effectiveChildren), so it is never the same object as what it
+// overrides and is never skipped against it — a genuinely different
+// declaration is always independently checked.
 // ---------------------------------------------------------------------------
 
 // The junction's reference view: the validator and the runtime/codegen FK
@@ -1970,14 +1993,36 @@ function _countJunctionReferences(junction: MetaData): number {
 
 export function validateRelationships(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
+  // #368 fix round 3 — the outer loop below is now resolving (obj.relationships()),
+  // so a relationship inherited unmodified by N entities is reached N times. Its
+  // own attrs never change based on who inherits it, so re-validating it more
+  // than once would report the identical finding N times — pure noise. Checked
+  // is keyed on the relationship NODE's own object identity: MetaData._effectiveChildren
+  // reuses the super's child object in place for an unmodified inherited child,
+  // so the same physical declaration IS the same object everywhere it's visible,
+  // while an override replaces it with a genuinely different object (correctly
+  // NOT skipped — a distinct declaration is a distinct finding).
+  const checked = new Set<MetaData>();
   // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
   for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
-    // ADR-0042 — a bare @through resolves in the declaring entity's package.
-    const referrerPkg = obj.package ?? obj.fileDefaultPackage ?? "";
-    // ADR-0039: own — a relationship is validated on the entity that DECLARES it
-    // (the M:N slim-vocabulary rules apply to own-declared relationships; its
-    // inheritable attrs are read resolving below).
-    for (const rel of obj.ownChildren().filter((c) => c.type === TYPE_RELATIONSHIP)) {
+    // ADR-0039: resolving — see the header comment above: rule (d) (like rule
+    // (e)) must see a relationship inherited via extends, not just this
+    // entity's own declarations. `checked` absorbs the resulting revisits.
+    for (const rel of (obj as MetaObject).relationships()) {
+      if (checked.has(rel)) continue;
+      checked.add(rel);
+
+      // Every rule below validates a property of the relationship's OWN
+      // declaration (its attrs, plus for rule (c) the @through target), so
+      // context — the entity name in messages, the package a bare @through
+      // resolves in (ADR-0042), and rule (a)'s self-join comparison — is
+      // always the entity that DECLARES `rel` (rel.parent), never `obj` (the
+      // entity whose effective view happened to reach it first). This keeps
+      // the check's result independent of iteration order/inheritance depth,
+      // which is what makes checking each node exactly once correct.
+      const declaringEntity = rel.parent ?? obj;
+      const referrerPkg = declaringEntity.package ?? declaringEntity.fileDefaultPackage ?? "";
+
       // ADR-0039: resolving — a relationship may inherit its M:N attrs via extends.
       const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
       const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
@@ -1999,16 +2044,23 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (hasThrough) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_THROUGH} but is not a M:N ` +
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_THROUGH} but is not a M:N ` +
                 `relationship (requires @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_MANY}").`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
         }
-        if (hasSourceRefField) {
+        // #368: @sourceRefField also disambiguates a `@cardinality: one`
+        // relationship when the entity holds more than one identity.reference
+        // onto the same target. Only the M:N *junction* reading is rejected
+        // here; rule (e) — validateOneSideReferenceResolution, below in this
+        // file — checks that it names a real local reference.
+        if (hasSourceRefField && cardinality !== CARDINALITY_ONE) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} but is not a M:N relationship.`,
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} but is neither a M:N ` +
+                `relationship (requires @${RELATIONSHIP_ATTR_THROUGH} with @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_MANY}") ` +
+                `nor a @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_ONE}" relationship.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
@@ -2016,7 +2068,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (symmetric) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but is not a M:N relationship.`,
+              `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but is not a M:N relationship.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
           );
@@ -2028,7 +2080,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (symmetric && hasSourceRefField) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" sets both @${RELATIONSHIP_ATTR_SYMMETRIC} and ` +
+            `relationship "${declaringEntity.name}.${rel.name}" sets both @${RELATIONSHIP_ATTR_SYMMETRIC} and ` +
               `@${RELATIONSHIP_ATTR_SOURCE_REF_FIELD}; they are mutually exclusive.`,
             { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
           ),
@@ -2040,12 +2092,13 @@ export function validateRelationships(root: MetaData): ParseError[] {
       // in this package is self, but an FQN "other::Widget" (a different same-short-
       // name entity) is NOT (comparing stripped short names would misclassify it).
       const isSelfJoin =
-        typeof objectRef === "string" && resolveObjectRef(root, objectRef, referrerPkg).node === obj;
+        typeof objectRef === "string" &&
+        resolveObjectRef(root, objectRef, referrerPkg).node === declaringEntity;
       if (symmetric && !isSelfJoin) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but @${RELATIONSHIP_ATTR_OBJECT_REF} ` +
-              `"${String(objectRef)}" is not the declaring entity "${obj.name}"; @${RELATIONSHIP_ATTR_SYMMETRIC} is self-join-only.`,
+            `relationship "${declaringEntity.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but @${RELATIONSHIP_ATTR_OBJECT_REF} ` +
+              `"${String(objectRef)}" is not the declaring entity "${declaringEntity.name}"; @${RELATIONSHIP_ATTR_SYMMETRIC} is self-join-only.`,
             { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
           ),
         );
@@ -2056,8 +2109,8 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (!junction) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.${didYouMeanHint(root, String(through))}`,
-            { code: "ERR_INVALID_RELATIONSHIP", source: resolvedSource(rel.source, `${obj.fqn()}::${rel.name}`, String(through)) },
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.${didYouMeanHint(root, String(through))}`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: resolvedSource(rel.source, `${declaringEntity.fqn()}::${rel.name}`, String(through)) },
           ),
         );
         continue;
@@ -2069,7 +2122,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (junction.subType !== OBJECT_SUBTYPE_ENTITY) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" resolves to ` +
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" resolves to ` +
               `${junction.type}.${junction.subType}, not an entity — a junction is a persisted join table ` +
               `and must be object.entity.`,
             { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
@@ -2081,7 +2134,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
       if (refCount !== 2) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" must declare exactly two ` +
+            `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" must declare exactly two ` +
               `identity.reference children (one per FK side); found ${refCount}.`,
             { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
           ),
@@ -2094,7 +2147,7 @@ export function validateRelationships(root: MetaData): ParseError[] {
         if (!fkFields.includes(sourceRefField as string)) {
           errors.push(
             new ParseError(
-              `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} "${sourceRefField}" does not match ` +
+              `relationship "${declaringEntity.name}.${rel.name}" @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} "${sourceRefField}" does not match ` +
                 `any identity.reference FK field on junction "${through}". Available: ${fkFields.join(", ") || "(none)"}.`,
               { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
             ),
@@ -2106,6 +2159,111 @@ export function validateRelationships(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Rule (e) — #368: a `@cardinality: one` relationship must resolve to exactly
+// one identity.reference. Two references onto the same target are
+// indistinguishable from the relationship's @objectRef alone, so the resolver
+// would silently emit the first one's FK column. ADR-0029 §5: a second path
+// is a load error naming the candidates.
+//
+// Registered alongside validateRelationships (the M:N slim-vocabulary pass,
+// above) — same deferred-resolution timing (after all files load + extends
+// resolution).
+//
+// Scope differs deliberately from rule (d) — in SUBJECT, not in which
+// relationships each pass walks (both walk the EFFECTIVE set; rule (d) is
+// no longer own-scoped, or an M:N declaration reached only via extends
+// would go unchecked). Rule (d) validates attrs that travel with the
+// relationship's OWN declaration (@through/@symmetric/@sourceRefField), so
+// it checks each declaration EXACTLY ONCE — deduped by node identity, and
+// reported against the entity that declares it — because those attrs don't
+// change meaning depending on who inherits the relationship. Rule (e)
+// instead validates whether THIS entity's reference set resolves the
+// relationship uniquely, which is a property of the EFFECTIVE entity, not of
+// wherever the relationship happens to be declared. A child entity that
+// extends a clean parent and adds a second identity.reference onto the same
+// target makes an INHERITED relationship ambiguous on the child even though
+// the parent (and the relationship's own declaration) are untouched — own-
+// scoping this pass would leave that case unchecked, and codegen/runtime
+// (which resolve against the effective entity) would silently drop the
+// relation (#368 fix round 2). If a parent and a child are both genuinely
+// ambiguous, both are reported — two entities are broken, not one error
+// duplicated.
+// ---------------------------------------------------------------------------
+
+export function validateOneSideReferenceResolution(root: MetaRoot): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.objects()) {
+    // ADR-0039: resolving — see the scope note above: rule (e) checks THIS
+    // entity's effective reference set against every relationship it can see,
+    // including one only inherited via extends.
+    for (const rel of obj.relationships()) {
+      // ADR-0039: resolving — @cardinality/@objectRef may be inherited via extends.
+      if (rel.attr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_ONE) continue;
+      const objectRef = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
+      if (typeof objectRef !== "string" || objectRef === "") continue;
+
+      const candidates = referenceCandidatesFor(obj, objectRef);
+
+      const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      const declared = typeof sourceRefField === "string" && sourceRefField !== ""
+        ? sourceRefField
+        : undefined;
+
+      if (declared !== undefined) {
+        // A declared @sourceRefField short-circuits the ladder at ANY
+        // candidate count — checked independently of resolveRelationshipReference,
+        // whose step 1 ("exactly one candidate -> that one") would otherwise
+        // silently return the lone candidate even when it disagrees with the
+        // declared field. The author named a specific FK; it must exist,
+        // whether there are zero, one, or many candidates.
+        const matchesDeclared = candidates.some((c) => c.fields[0] === declared);
+        if (matchesDeclared) continue;
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} ` +
+              `"${declared}", which names no identity.reference targeting "${objectRef}". ` +
+              `Candidates: ${formatReferenceCandidates(candidates)}.`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+          ),
+        );
+        continue;
+      }
+
+      // No @sourceRefField declared: ambiguity only exists with 2+ candidates —
+      // resolveRelationshipReference's name-pairing step (ladder step 3) decides.
+      if (candidates.length <= 1) continue;
+      const resolved = resolveRelationshipReference(obj, rel.name, objectRef);
+      if (resolved) continue;
+
+      errors.push(
+        new ParseError(
+          `relationship "${obj.name}.${rel.name}" is ambiguous: "${obj.name}" declares ` +
+            `${candidates.length} identity.reference nodes targeting "${objectRef}" and the ` +
+            `relationship name does not pair with exactly one. Candidates: ${formatReferenceCandidates(candidates)}. ` +
+            `Set @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} to the FK field this relationship navigates.`,
+          { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Render a candidate reference as `name(fkField)`, or `name(fieldA, fieldB)`
+ * for a composite reference — so two composite references sharing a first
+ * column (e.g. both starting `tenantId`) still print distinguishably.
+ *
+ * NOTE: this is display only. Matching (both here and in
+ * resolveRelationshipReference) still keys on `fields[0]` alone — a
+ * composite reference cannot actually be disambiguated by @sourceRefField.
+ * That's a documented limitation, not fixed by this rendering change.
+ */
+function formatReferenceCandidates(candidates: readonly MetaReferenceIdentity[]): string {
+  return candidates.map((c) => `${c.name}(${c.fields.join(", ")})`).join(", ");
+}
+
 // NOTE: identity.reference @references resolution moved to the validation registry
 // (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).