@metaobjectsdev/metadata 0.15.19 → 0.15.20

package/src/loader/validation-passes.ts

@@ -14,7 +14,7 @@ import type { MetaData } from "../shared/meta-data.js";
 import type { MetaObject } from "../core/object/meta-object.js";
 import type { MetaReferenceIdentity } from "../core/identity/meta-identity.js";
 import { ParseError } from "../errors.js";
-import { refMatchesObject, resolveObjectRef, REF_BEARING_ATTR_NAMES } from "../naming-refs.js";
+import { resolveObjectRef, didYouMeanHint } from "../naming-refs.js";
 import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "../shared/structural.js";
 import { resolvedSource, type ErrorSource } from "../source.js";
 import {
@@ -222,11 +222,14 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       }
     }
 
+    // ADR-0042 — a bare @payloadRef/@responseRef resolves in the template's package.
+    const referrerPkg = tmpl.package ?? tmpl.fileDefaultPackage ?? "";
     // ADR-0039: resolving — a template may inherit @payloadRef via extends.
     const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
     // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
-    const payload = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
+    // ADR-0042: resolveObjectRef prefers the referrer's own package before a root-level object.
+    const payload = resolveObjectRef(root, payloadRef, referrerPkg).node;
     if (!payload || payload.subType !== OBJECT_SUBTYPE_VALUE) {
       // FR5d — @payloadRef is a reference; emit format=resolved with
       // referrer=template FQN, target=the unresolved payloadRef string.
@@ -245,7 +248,8 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     const responseRef = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
     if (typeof responseRef === "string") {
       // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
-      const resVo = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, responseRef));
+      // ADR-0042: resolveObjectRef prefers the referrer's own package before a root-level object.
+      const resVo = resolveObjectRef(root, responseRef, referrerPkg).node;
       if (!resVo || resVo.subType !== OBJECT_SUBTYPE_VALUE) {
         errors.push(
           new ParseError(
@@ -282,56 +286,12 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
   return errors;
 }
 
-// ---------------------------------------------------------------------------
-// Cross-package reference ambiguity (the object-ref contract)
-// ---------------------------------------------------------------------------
-
-/**
- * A BARE object reference (no `::`) that names an object present in MORE THAN ONE
- * package, with NO match in the referrer's own package, is ambiguous → emit
- * ERR_AMBIGUOUS_REF (the author must qualify it with the package). An FQN ref is
- * exact (never ambiguous); a bare ref that matches the referrer's own package, or
- * exactly one package anywhere, resolves fine. Covers every object-ref-bearing
- * attr in `REF_BEARING_ATTR_NAMES` (@objectRef / @references / @from / @of / @via
- * / @parameterRef / @payloadRef / @responseRef) — the dotted `.child` tail of the
- * origin heads is stripped to the entity OWNER. `extends` is intentionally NOT
- * covered: its FR-032 super-resolver is same-package/root-strict and never
- * matches a packaged object by bare name, so a bare cross-package `extends` is
- * unresolved (ERR_UNRESOLVED_SUPER), not ambiguous.
- */
-export function validateCrossPackageRefs(root: MetaData): ParseError[] {
-  const errors: ParseError[] = [];
-  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
-    const referrerPkg = obj.package ?? obj.fileDefaultPackage ?? "";
-    const visit = (node: MetaData): void => {
-      for (const attrName of REF_BEARING_ATTR_NAMES) {
-        const raw = node.ownAttr(attrName);
-        if (typeof raw !== "string") continue;
-        // Owner = the object part; strip any FR-024 dotted `.child` tail. An FQN
-        // owner (has `::`) is resolved exactly and can never be ambiguous.
-        const dot = raw.indexOf(CHILD_REF_SEPARATOR);
-        const owner = dot === -1 ? raw : raw.slice(0, dot);
-        if (owner.includes(PACKAGE_SEPARATOR) || owner === "") continue;
-        if (!resolveObjectRef(root, owner, referrerPkg).ambiguous) continue;
-        const pkgs = root
-          .children()
-          .filter((c) => c.type === TYPE_OBJECT && c.name === owner)
-          .map((c) => c.resolutionKey());
-        errors.push(
-          new ParseError(
-            `${attrName} "${raw}" on ${obj.fqn()}: bare reference "${owner}" is ambiguous — it names an object ` +
-              `in multiple packages (${pkgs.join(", ")}) and none is in the referrer's package "${referrerPkg}". ` +
-              `Qualify it with the package (FQN).`,
-            { code: "ERR_AMBIGUOUS_REF", source: resolvedSource(node.source, obj.fqn(), owner) },
-          ),
-        );
-      }
-      for (const c of node.ownChildren()) visit(c);
-    };
-    visit(obj);
-  }
-  return errors;
-}
+// ADR-0042 — the cross-package ambiguity pass (ERR_AMBIGUOUS_REF) is RETIRED.
+// A bare reference now resolves package-locally (referrer's package, else
+// root-level) at every ref site via resolveObjectRef / refMatchesObject, so
+// cross-package ambiguity is unreachable; an unresolved ref fails closed with
+// its per-attr code (ERR_INVALID_RELATIONSHIP / ERR_INVALID_REFERENCE /
+// ERR_UNRESOLVED_OBJECT_REF / ERR_INVALID_ORIGIN / ERR_INVALID_TEMPLATE).
 
 // ---------------------------------------------------------------------------
 // @filterable without index validation
@@ -418,11 +378,11 @@ export function validateFilterableHasSupportedOps(root: MetaData): ParseError[]
 // allowedValues on the origin.aggregate @agg attr schema — not here.
 // ---------------------------------------------------------------------------
 
-function _findObject(root: MetaData, name: string): MetaData | undefined {
-  // FR-032 — origin heads are FQN-qualified after the desugar/sweep; match on
-  // the effective FQN resolution key (with bare back-compat).
-  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+function _findObject(root: MetaData, name: string, referrerPkg: string): MetaData | undefined {
+  // ADR-0042 package-local resolution — an FQN resolves exactly on its
+  // resolution key; a bare name resolves in the referrer's package, else a
+  // root-level object. Shares the single resolveObjectRef matcher.
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 function _findField(obj: MetaData, name: string): MetaData | undefined {
@@ -490,6 +450,8 @@ function _validateFromPath(
   // FR5d — referrer is `<projection-FQN>::<fieldName>` (the canonical
   // "where the broken reference lives" identifier).
   const referrer = `${projection.fqn()}::${fieldName}`;
+  // ADR-0042 — a bare @from/@of head resolves in the projection's package.
+  const referrerPkg = projection.package ?? projection.fileDefaultPackage ?? "";
   const dotIdx = fromAttr.indexOf(".");
   if (dotIdx < 1 || dotIdx === fromAttr.length - 1) {
     // Malformed shape (not "Entity.field") — not a reference resolution
@@ -508,7 +470,7 @@ function _validateFromPath(
   }
   const entityName = fromAttr.slice(0, dotIdx);
   const targetFieldName = fromAttr.slice(dotIdx + 1);
-  const sourceObj = _findObject(root, entityName);
+  const sourceObj = _findObject(root, entityName, referrerPkg);
   if (!sourceObj) {
     // FR5d — entity half of the ref didn't resolve. target = full ref.
     errors.push(
@@ -555,6 +517,8 @@ function _validateViaPath(
   const projectionName = projection.name;
   // FR5d — referrer is `<projection-FQN>::<fieldName>`.
   const referrer = `${projection.fqn()}::${fieldName}`;
+  // ADR-0042 — a bare @via HEAD resolves in the projection's package.
+  const referrerPkg = projection.package ?? projection.fileDefaultPackage ?? "";
   const segments = viaAttr.split(".");
   if (segments.length < 2) {
     errors.push(
@@ -569,7 +533,7 @@ function _validateViaPath(
     return undefined;
   }
   const [entityName, ...relSegments] = segments as [string, ...string[]];
-  let currentObj = _findObject(root, entityName);
+  let currentObj = _findObject(root, entityName, referrerPkg);
   if (!currentObj) {
     errors.push(
       new ParseError(
@@ -624,7 +588,13 @@ function _validateViaPath(
       );
       return undefined;
     }
-    const nextObj = _findObject(root, refTarget);
+    // ADR-0042 — the hop target (@objectRef/@references) resolves in the package
+    // of the entity that DECLARES the relationship/reference, i.e. currentObj.
+    const nextObj = _findObject(
+      root,
+      refTarget,
+      currentObj.package ?? currentObj.fileDefaultPackage ?? "",
+    );
     if (!nextObj) {
       // FR5d — relationship's @objectRef points at a missing entity. This
       // is the @objectRef-resolution edge of the via-path walk (the "5th
@@ -682,14 +652,18 @@ function _hopCardinality(rel: MetaData): string | undefined {
  * anchor `Product` (what the author wrote), never `BaseEntity` (where the
  * child physically lives).
  */
-function _refNamedOwner(node: MetaData, root: MetaData): MetaData | undefined {
+function _refNamedOwner(node: MetaData, root: MetaData, referrerPkg: string): MetaData | undefined {
   const ref = node.superRef;
   if (ref === undefined) return undefined;
-  const lastSep = ref.lastIndexOf("::");
-  const tail = lastSep === -1 ? ref : ref.slice(lastSep + 2);
-  const dot = tail.indexOf(".");
-  if (dot <= 0) return undefined;
-  return _findObject(root, tail.slice(0, dot));
+  // Owner = everything before the child dot in the FINAL ::-segment (the object
+  // the extends anchors at). ADR-0042: resolve it AS AUTHORED — an FQN owner
+  // (`acme::Customer`) resolves exactly, a bare owner (`Product`) resolves in
+  // the referrer's package. Do NOT strip the package to a bare tail.
+  const lastSep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+  const dotInSeg = ref.indexOf(CHILD_REF_SEPARATOR, segStart);
+  if (dotInSeg <= segStart) return undefined; // no dotted child owner
+  return _findObject(root, ref.slice(0, dotInSeg), referrerPkg);
 }
 
 function _deriveBaseEntity(
@@ -700,6 +674,8 @@ function _deriveBaseEntity(
   errors: ParseError[],
 ): MetaData | undefined {
   if (obj.subType !== OBJECT_SUBTYPE_PROJECTION) return obj;
+  // ADR-0042 — a bare extends owner resolves in this projection's package.
+  const referrerPkg = obj.package ?? obj.fileDefaultPackage ?? "";
 
   // 1) The extended identity anchors the base entity (declared, not inferred).
   //    The anchor is the entity NAMED in the ref's owner part — see _refNamedOwner.
@@ -708,7 +684,7 @@ function _deriveBaseEntity(
   for (const identity of obj.ownChildren().filter((c) => c.type === TYPE_IDENTITY)) {
     const extended = identity.superResolved;
     if (extended !== undefined && extended.type === TYPE_IDENTITY) {
-      const named = _refNamedOwner(identity, root);
+      const named = _refNamedOwner(identity, root, referrerPkg);
       if (named !== undefined) return named;
       const owner = extended.parent;
       if (owner !== undefined && owner.type === TYPE_OBJECT) return owner;
@@ -723,7 +699,7 @@ function _deriveBaseEntity(
   for (const f of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
     const sup = f.superResolved;
     if (sup === undefined) continue;
-    const named = _refNamedOwner(f, root);
+    const named = _refNamedOwner(f, root, referrerPkg);
     const owner = named ?? sup.parent;
     if (
       owner !== undefined &&
@@ -1459,6 +1435,8 @@ export function validateRelationships(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
   // 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).
@@ -1521,7 +1499,11 @@ export function validateRelationships(root: MetaData): ParseError[] {
       }
 
       // Rule (a): @symmetric is valid only on a self-join (@objectRef == declaring entity).
-      const isSelfJoin = typeof objectRef === "string" && stripPackage(objectRef) === obj.name;
+      // ADR-0042: resolve @objectRef and compare NODE IDENTITY — a bare "Widget"
+      // 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;
       if (symmetric && !isSelfJoin) {
         errors.push(
           new ParseError(
@@ -1533,11 +1515,11 @@ export function validateRelationships(root: MetaData): ParseError[] {
       }
 
       // Rule (c): @through must name an entity declaring exactly two identity.reference children.
-      const junction = _findObject(root, through as string);
+      const junction = _findObject(root, through as string, referrerPkg);
       if (!junction) {
         errors.push(
           new ParseError(
-            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.`,
+            `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)) },
           ),
         );

package/src/loader/validation-registry.ts

@@ -8,34 +8,35 @@
 
 import type { MetaData } from "../shared/meta-data.js";
 import { ParseError } from "../errors.js";
-import { refMatchesObject } from "../naming-refs.js";
+import { didYouMeanHint } from "../naming-refs.js";
 import { TYPE_OBJECT } from "../shared/base-types.js";
+import { PACKAGE_SEPARATOR } from "../shared/structural.js";
 import type { TypeRegistry } from "../registry.js";
 import type { LoaderCode, SymbolTable, ValidationContext } from "../validation-types.js";
 
 /** A symbol table of every top-level object, built once per load (the binder analogue). */
 class SymbolTableImpl implements SymbolTable {
-  private readonly byRef = new Map<string, MetaData>();
+  private readonly byKey = new Map<string, MetaData>();
 
   static build(root: MetaData): SymbolTableImpl {
     const t = new SymbolTableImpl();
     // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
     for (const child of root.children()) {
       if (child.type !== TYPE_OBJECT) continue;
-      if (child.name) t.byRef.set(child.name, child);
-      t.byRef.set(child.fqn(), child);
-      t.byRef.set(child.resolutionKey(), child);
+      // ADR-0042: key by the canonical resolution key ONLY (the FQN, or the bare
+      // name for a root-level/empty-package object) — NO bare-name fallback, so a
+      // bare ref never binds a same-named object in another package.
+      t.byKey.set(child.resolutionKey(), child);
     }
     return t;
   }
 
-  resolveObject(ref: string): MetaData | undefined {
-    const hit = this.byRef.get(ref);
-    if (hit) return hit;
-    for (const obj of this.byRef.values()) {
-      if (refMatchesObject(obj, ref)) return obj;
-    }
-    return undefined;
+  /** ADR-0042 package-local resolution: FQN → exact resolution-key match; bare →
+   *  the referrer's own package (`<referrerPkg>::<ref>`), else a root-level object. */
+  resolveObject(ref: string, referrerPkg: string): MetaData | undefined {
+    if (ref.includes(PACKAGE_SEPARATOR)) return this.byKey.get(ref);
+    const localKey = referrerPkg !== "" ? `${referrerPkg}${PACKAGE_SEPARATOR}${ref}` : ref;
+    return this.byKey.get(localKey) ?? this.byKey.get(ref);
   }
 }
 
@@ -54,10 +55,17 @@ class ValidationContextImpl implements ValidationContext {
  */
 export function runRegisteredValidation(root: MetaData, registry: TypeRegistry): ParseError[] {
   const ctx = new ValidationContextImpl(SymbolTableImpl.build(root));
-  walk(root);
+  walk(root, "");
   return ctx.errors;
 
-  function walk(node: MetaData): void {
+  function walk(node: MetaData, referrerPkg: string): void {
+    // ADR-0042: a top-level object establishes the package context for its
+    // subtree; nested ref-bearing nodes (relationship/field.object/
+    // identity.reference) resolve BARE refs against it. Nested nodes carry no
+    // `package`, so they inherit the enclosing object's (via fileDefaultPackage,
+    // else the threaded context).
+    const pkg =
+      node.type === TYPE_OBJECT ? (node.package ?? node.fileDefaultPackage ?? referrerPkg) : referrerPkg;
     const def = registry.find(node.type, node.subType);
     if (def) {
       for (const desc of def.references ?? []) {
@@ -66,7 +74,7 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
         const raw = node.attr(desc.attr);
         if (typeof raw !== "string" || raw === "") continue; // absence is the required-attr pass's job
         const entityRef = desc.dottedFieldPath ? (raw.split(".")[0] ?? raw) : raw;
-        const target = ctx.symbols.resolveObject(entityRef);
+        const target = ctx.symbols.resolveObject(entityRef, pkg);
         // Qualify the node name with its owning entity (e.g. "Order.items") so the error is
         // locatable from the message alone, not just the source envelope.
         const qname = node.parent?.name ? `${node.parent.name}.${node.name}` : node.name;
@@ -74,7 +82,7 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
           ctx.error(
             desc.errorCode,
             node,
-            `${node.type}.${node.subType} "${qname}" @${desc.attr} "${raw}" does not resolve to an object.`,
+            `${node.type}.${node.subType} "${qname}" @${desc.attr} "${raw}" does not resolve to an object.${didYouMeanHint(root, entityRef)}`,
           );
         } else if (
           target.type !== desc.targetType ||
@@ -93,6 +101,6 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
     }
     // ADR-0039: own — structural walk visiting every physical node once at its
     // declaration site (an inherited child is validated on its declaring parent).
-    for (const child of node.ownChildren()) walk(child);
+    for (const child of node.ownChildren()) walk(child, pkg);
   }
 }

package/src/naming-refs.ts

@@ -29,7 +29,7 @@
 import type { MetaData } from "./shared/meta-data.js";
 import { PACKAGE_SEPARATOR, PACKAGE_PARENT, CHILD_REF_SEPARATOR } from "./shared/structural.js";
 import { TYPE_OBJECT } from "./shared/base-types.js";
-import { RELATIONSHIP_ATTR_OBJECT_REF } from "./core/relationship/relationship-constants.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH } from "./core/relationship/relationship-constants.js";
 import { FIELD_ATTR_OBJECT_REF } from "./core/field/field-constants.js";
 import { IDENTITY_REFERENCE_ATTR_REFERENCES } from "./core/identity/identity-constants.js";
 import {
@@ -52,12 +52,15 @@ const PARENT_PREFIX = PACKAGE_PARENT + PACKAGE_SEPARATOR; // "..::"
  * a dotted relationship/field tail — expandRef preserves the tail);
  * `@parameterRef`/`@payloadRef`/`@responseRef` reference value-objects. These are
  * expanded by the YAML desugar and rejected (when still relative) by the
- * canonical-JSON guard. `@sourceRefField` (a FK FIELD name, not an object ref)
- * and `@through` are intentionally NOT in this set (out of scope for FR-032 T-slice).
+ * canonical-JSON guard. `@through` (the M:N junction ref) is in the set per
+ * ADR-0042 §4 — it desugars to FQN and resolves package-local like every other
+ * object ref. `@sourceRefField` (a FK FIELD name, not an object ref) is NOT in
+ * the set.
  */
 export const REF_BEARING_ATTR_NAMES: ReadonlySet<string> = new Set<string>([
   RELATIONSHIP_ATTR_OBJECT_REF, // = FIELD_ATTR_OBJECT_REF (same spelling "objectRef")
   FIELD_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_THROUGH, // ADR-0042: the M:N junction ref joins the desugar+resolution set.
   IDENTITY_REFERENCE_ATTR_REFERENCES,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
   ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA = ORIGIN_COLLECTION_ATTR_VIA ("via")
@@ -146,56 +149,79 @@ export function expandRef(raw: string, packageContext: string): string {
 }
 
 /**
- * FR-032 — does a root-level object `node` satisfy an (already-expanded)
- * object reference `ref`? After the YAML desugar + corpus sweep every ref is
- * fully qualified, so resolution is a pure FQN match. Objects keep a BARE
- * `fqn()` per the FR5d cross-port contract, so the canonical FQN accessor is
- * `resolutionKey()` (`<package | fileDefaultPackage>::<name>`) — this mirrors
- * `super-resolve`'s `findInTree`. The bare `name`/`fqn()` arms cover legacy
- * same-tree refs and root-level (empty-package) objects.
+ * ADR-0042 — does root-level object `node` satisfy object reference `ref`,
+ * declared by a node whose effective package is `referrerPkg`? A single
+ * package-local matcher:
+ *   - **FQN** `ref` (contains `::`) → EXACT match on `resolutionKey()`. No
+ *     bare-tail fallback, so an FQN pointing at one package never binds a
+ *     same-named object in another.
+ *   - **bare** `ref` (no `::`) → the referrer's OWN package
+ *     (`<referrerPkg>::<ref>`), else a **root-level** (empty-package) object
+ *     whose resolution key IS `ref`. No cross-package bare resolution, no
+ *     globally-unique scan.
  *
- * This is the single matcher the non-super resolvers (origin `@from`/`@of`/
- * `@via` heads, template `@payloadRef`/`@responseRef`, source `@parameterRef`)
- * share, so FQN matching behaves identically everywhere a ref resolves.
+ * Objects keep a BARE `fqn()` per the FR5d cross-port contract, so the canonical
+ * FQN accessor is `resolutionKey()` (`<package | fileDefaultPackage>::<name>`) —
+ * this mirrors `super-resolve`'s `findInTree`. This is the single matcher the
+ * non-super resolvers (origin `@from`/`@of`/`@via` heads, template
+ * `@payloadRef`/`@responseRef`, source `@parameterRef`, relationship `@through`)
+ * share, so resolution behaves identically everywhere a ref resolves.
+ *
+ * `referrerPkg` defaults to `""` — the fail-closed FQN-exact-plus-root-level
+ * behavior. The LOADER always passes the real referrer package (bare refs there
+ * must resolve package-locally); downstream CODEGEN resolvers, which run on
+ * already-validated metadata whose refs are FQN, may omit it. An empty
+ * `referrerPkg` never binds a bare ref across a package boundary (fail-closed),
+ * so omission can only fail to resolve — never mis-resolve.
  */
-export function refMatchesObject(node: MetaData, ref: string): boolean {
-  return node.resolutionKey() === ref || node.fqn() === ref || node.name === ref;
-}
-
-/** The effective package of a root-level object (its `resolutionKey()` minus the
- *  trailing `::<name>`; "" for a root-level/empty-package object). */
-function objectPackage(node: MetaData): string {
+export function refMatchesObject(node: MetaData, ref: string, referrerPkg = ""): boolean {
   const key = node.resolutionKey();
-  const i = key.lastIndexOf(PACKAGE_SEPARATOR);
-  return i === -1 ? "" : key.slice(0, i);
+  if (ref.includes(PACKAGE_SEPARATOR)) return key === ref;
+  if (referrerPkg !== "" && key === `${referrerPkg}${PACKAGE_SEPARATOR}${ref}`) return true;
+  return key === ref; // root-level (empty-package) object whose key is the bare name
 }
 
 /**
- * Resolve a metadata OBJECT reference under the cross-package contract:
- *   - **FQN** (`ref` contains `::`) → EXACT match on `resolutionKey()`/`fqn()`.
- *     Never a bare-tail fallback, so an FQN pointing at one package never binds a
- *     same-named object in another (the cross-port bug this closes).
- *   - **bare** (no `::`) → prefer an object of that name in the REFERRER's own
- *     package; else a UNIQUE object of that name across all packages; else
- *     (>1 across OTHER packages, none in the referrer's) → `ambiguous`.
- *
- * `referrerPkg` is the effective package of the node carrying the ref. Returns
- * `{ node }` on a unique resolution, `{ ambiguous: true }` when a bare ref is
- * cross-package-ambiguous, or `{}` (node undefined) when nothing matches. The
- * SINGLE resolver every object-ref site shares so the contract is uniform.
+ * Resolve a metadata OBJECT reference under the ADR-0042 package-local contract
+ * (see `refMatchesObject` for the matcher). `referrerPkg` is the effective
+ * package of the node carrying the ref. Returns `{ node }` on resolution, or
+ * `{}` (node undefined) when nothing matches — there is NO ambiguous outcome
+ * (bare = package-local, so ambiguity is unreachable). The SINGLE resolver every
+ * object-ref site shares so the contract is uniform.
  */
 export function resolveObjectRef(
   root: MetaData,
   ref: string,
   referrerPkg: string,
-): { node?: MetaData | undefined; ambiguous?: boolean } {
+): { node?: MetaData | undefined } {
   const objects = root.children().filter((c) => c.type === TYPE_OBJECT);
   if (ref.includes(PACKAGE_SEPARATOR)) {
-    return { node: objects.find((c) => c.resolutionKey() === ref || c.fqn() === ref) };
+    return { node: objects.find((c) => c.resolutionKey() === ref) };
   }
-  const matches = objects.filter((c) => c.name === ref);
-  if (matches.length <= 1) return { node: matches[0] };
-  const own = matches.find((c) => objectPackage(c) === referrerPkg);
+  // Bare: PREFER the referrer's own package, THEN a root-level (empty-package)
+  // object — mirroring the loader symbol table's `byKey.get(localKey) ?? get(ref)`
+  // so both resolvers agree when a root-level object shares the bare name.
+  const localKey = referrerPkg !== "" ? `${referrerPkg}${PACKAGE_SEPARATOR}${ref}` : ref;
+  const own = objects.find((c) => c.resolutionKey() === localKey);
   if (own !== undefined) return { node: own };
-  return { ambiguous: true };
+  return { node: localKey !== ref ? objects.find((c) => c.resolutionKey() === ref) : undefined };
+}
+
+/**
+ * ADR-0042 §5 — a did-you-mean suffix for an UNRESOLVED object reference: the
+ * FQNs of same-short-name objects that DO exist (typically in other packages),
+ * so the author can qualify a bare ref they meant to point across a package
+ * boundary. Returns "" when no same-short-name object exists (nothing to
+ * suggest). Appended to the per-attr unresolved-ref error message.
+ */
+export function didYouMeanHint(root: MetaData, ref: string): string {
+  const { owner } = splitChildTail(ref);
+  const sep = owner.lastIndexOf(PACKAGE_SEPARATOR);
+  const shortName = sep === -1 ? owner : owner.slice(sep + PACKAGE_SEPARATOR.length);
+  const candidates = root
+    .children()
+    .filter((c) => c.type === TYPE_OBJECT && c.name === shortName)
+    .map((c) => c.resolutionKey());
+  if (candidates.length === 0) return "";
+  return ` An object named "${shortName}" exists in: ${candidates.join(", ")}. Qualify it with its package (FQN).`;
 }

package/src/persistence/origin/origin-constants.ts

@@ -40,9 +40,10 @@ export const ORIGIN_COLLECTION_ATTR_VIA = "via";
 export const ORIGIN_AGGREGATE_ATTR_AGG = "agg";
 export const ORIGIN_AGGREGATE_ATTR_OF  = "of";
 export const ORIGIN_AGGREGATE_ATTR_VIA = "via";
-// @filter (attr.filter object): optional scoping predicate restricting which
-// related rows the aggregate spans — rendered as SQL FILTER (WHERE …). Same
-// structured shape as a preset filter; consumed by the projection view emitter.
+// @filter (attr.filter object): an optional PORTABLE structured predicate scoping
+// which related rows the aggregate spans (same shape as a preset filter). Codegen
+// renders it per target — the projection view emitter turns it into SQL
+// FILTER (WHERE …) / SQLite CASE WHEN.
 export const ORIGIN_AGGREGATE_ATTR_FILTER = "filter";
 
 // aggregate function vocabulary

package/src/persistence/origin/origin-definition.embedded.ts

@@ -90,7 +90,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
           "name": "filter",
           "min": 0,
           "max": 1,
-          "description": "Optional scoping filter restricting which related rows the aggregate spans, rendered as a SQL FILTER (WHERE ...) clause. Structured filter object desugared to canonical { field: { op: value } } form at parse time."
+          "description": "Optional structured predicate scoping which related rows the aggregate spans. A portable attr.filter object (eq/ne/in/isNull with and/or), desugared to canonical { field: { op: value } } at parse time; codegen renders it per target (e.g. SQL FILTER (WHERE ...) or SQLite CASE WHEN for a relational view)."
         }
       ]
     },

package/src/persistence/source/validate-source-parameter-ref.ts

@@ -24,7 +24,7 @@ import {
   OBJECT_SUBTYPE_VALUE,
   OBJECT_SUBTYPE_ENTITY,
 } from "../../core/object/object-constants.js";
-import { PACKAGE_SEPARATOR } from "../../shared/structural.js";
+import { resolveObjectRef } from "../../naming-refs.js";
 import { MetaSource } from "./meta-source.js";
 import {
   SOURCE_ATTR_PARAMETER_REF,
@@ -41,25 +41,13 @@ const CALLABLE_KINDS = new Set<string>([
 export function validateSourceParameterRef(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
 
-  // Pre-index every object by name, fqn AND effective FQN resolution key so
-  // resolution costs O(1) per source. FR-032 — @parameterRef is FQN-qualified
-  // after the desugar/sweep, but objects keep a BARE fqn() per the FR5d
-  // contract, so the FQN form `<package | fileDefaultPackage>::<name>` only
-  // matches via resolutionKey() (these fixtures declare package at metadata.root
-  // only, so obj.package is undefined and the file-default must be folded in).
-  const objectIndex = new Map<string, 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)) {
-    objectIndex.set(obj.name, obj);
-    const fqn = obj.package !== undefined && obj.package !== ""
-      ? `${obj.package}${PACKAGE_SEPARATOR}${obj.name}`
-      : obj.name;
-    objectIndex.set(fqn, obj);
-    objectIndex.set(obj.resolutionKey(), obj);
-  }
-
   // 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 @parameterRef resolves package-local (this object's
+    // package, else root-level); an FQN resolves exactly. Shares the single
+    // resolveObjectRef matcher — NO bare-name-anywhere fallback (which would
+    // silently bind a same-named value-object in another package).
+    const referrerPkg = obj.package ?? obj.fileDefaultPackage ?? "";
     // ADR-0039: own — declaration-layer source iteration (mirrors validateSourceRoles).
     for (const source of obj.ownChildren().filter(
       (c): c is MetaSource =>
@@ -82,7 +70,7 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
         continue;
       }
 
-      const target = objectIndex.get(ref);
+      const target = resolveObjectRef(root, ref, referrerPkg).node;
       if (target === undefined) {
         errors.push(
           new ParseError(

package/src/validation-types.ts

@@ -30,9 +30,11 @@ export interface ReferenceDescriptor {
   readonly errorCode: LoaderCode;
 }
 
-/** Resolve a ref string to its object node. */
+/** Resolve a ref string to its object node under the ADR-0042 package-local
+ *  contract. `referrerPkg` is the effective package of the node that declares
+ *  the ref (a bare ref resolves in that package, else root-level). */
 export interface SymbolTable {
-  resolveObject(ref: string): MetaData | undefined;
+  resolveObject(ref: string, referrerPkg: string): MetaData | undefined;
 }
 
 /** Handed to every validator: the symbol table + an error sink. */