@metaobjectsdev/metadata 1.0.12 → 1.1.0

package/src/parser-core.ts

@@ -39,6 +39,7 @@ import {
   extendsTargetCompatible,
   EXTENDS_TARGET_MISMATCH_RULE,
 } from "./super-resolve.js";
+import { RefOverDropError } from "./naming-refs.js";
 import { JsonPathBuilder, type Segment as JsonPathSegment } from "./json-path.js";
 import { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
@@ -66,7 +67,6 @@ import {
 import { ATTR_SUBTYPE_PROPERTIES, ATTR_SUBTYPE_STRINGARRAY } from "./core/attr/attr-constants.js";
 import { attrClassFor } from "./attr-class-map.js";
 import type { AttrValue } from "./shared/meta-data.js";
-import { isRelativeRef, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -234,44 +234,6 @@ function reportProblem(
   warnings.push(msg);
 }
 
-// ---------------------------------------------------------------------------
-// FR-032 (ADR-0032) — canonical-JSON ref guard.
-//
-// Canonical JSON is the self-contained interchange form: every ref-bearing attr
-// MUST be fully-qualified. A relative authoring form (leading `::` or `..::`)
-// surviving into canonical JSON is `ERR_RELATIVE_REF_IN_CANONICAL`. The guard
-// fires ONLY for JSON-format input — YAML-format input has already been
-// desugar-expanded via expandRef (so any `::`/`..::` there is correct authoring
-// that was lowered to FQN before buildTree sees it). Like ERR_RESERVED_ATTR,
-// this is a hard error routed through the loader's error sink even in lax mode.
-// ---------------------------------------------------------------------------
-
-function guardRelativeRefInCanonical(
-  refLabel: string,
-  rawValue: unknown,
-  strict: boolean,
-  warnings: string[],
-  path: string,
-): void {
-  if (_currentFormat !== "json") return;
-  if (typeof rawValue !== "string") return;
-  if (!isRelativeRef(rawValue)) return;
-  const msg =
-    `Relative reference '${rawValue}' on ${refLabel} at ${path} is not allowed in ` +
-    `canonical JSON — canonical JSON must be fully-qualified. Relative forms ` +
-    `(leading '::' or '..::') are YAML-authoring sugar that the desugar expands.`;
-  if (strict) {
-    throw new ParseError(msg, { code: "ERR_RELATIVE_REF_IN_CANONICAL", source: errSource() });
-  }
-  if (_currentErrors !== undefined) {
-    _currentErrors.push(
-      new ParseError(msg, { code: "ERR_RELATIVE_REF_IN_CANONICAL", source: errSource() }),
-    );
-  } else {
-    warnings.push(msg);
-  }
-}
-
 // ---------------------------------------------------------------------------
 // The one message for an authored `<type>.base`, so both doors say the same thing.
 //
@@ -701,10 +663,11 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     if (opts.intoRoot !== undefined) {
       // --- Merge mode: parse root's attrs/children into the existing root ---
       // The JSON root's own package/super/reserved-keys are not re-applied to the
-      // existing root. BUT: children from the NEW JSON should inherit from the
-      // NEW root's package, not the existing root's.
+      // existing root. Children from the NEW document take the NEW document's
+      // package — and a document with no `package` declares root-level nodes,
+      // whatever was loaded before it (ADR-0059 R10: the default package is per file).
       const newRootPkg = rootDataObj[RESERVED_KEY_PACKAGE];
-      const contextPkg = (typeof newRootPkg === "string" ? newRootPkg : opts.intoRoot.package) ?? "";
+      const contextPkg = typeof newRootPkg === "string" ? newRootPkg : "";
       parseNodeInto(
         rootDataObj,
         opts.intoRoot,
@@ -825,9 +788,9 @@ function parseNodeFresh(
   // this node by its effective qualified key regardless of post-merge tree
   // shape or load order. This does NOT touch the node's `package` or `fqn()`
   // (objects stay bare per FR5d). Mirrors Java's parse-time getDefaultPackageName().
-  if (inheritedContextPkg !== "") {
-    model.setFileDefaultPackage(inheritedContextPkg);
-  }
+  // Recorded even when empty: "" says the file declares no package (ADR-0059
+  // R10), which is not the same as a node built in code with no file at all.
+  model.setFileDefaultPackage(inheritedContextPkg);
 
   // --- Apply reserved keys (package, extends, abstract, isArray) ---
   applyReservedKeys(model, nodeData, strict, source, path, warnings, inheritedContextPkg);
@@ -861,7 +824,17 @@ function parseNodeFresh(
   if (model.superRef !== undefined && accumRoot !== undefined && !_deferSuperResolution) {
     // FR-024: thread the referrer's type so dotted `Entity.child` refs resolve
     // type-scoped — kept consistent with the deferred path (super-resolve.ts).
-    const superModel = resolveSuperRef(model.superRef, effectivePkg, accumRoot, { type: model.type });
+    let superModel: MetaData | undefined;
+    try {
+      superModel = resolveSuperRef(model.superRef, effectivePkg, accumRoot, { type: model.type });
+    } catch (e) {
+      if (!(e instanceof RefOverDropError)) throw e;
+      // ADR-0059 R2 — `..::` dropped more segments than the package has.
+      throw new ParseError(
+        `the extends ref '${model.superRef}' on ${model.fqn()} climbs above the root package — each '..::' drops one segment of the declaring package`,
+        { code: "ERR_BAD_ATTR_VALUE", source: resolvedSource(errSource(), model.fqn(), model.superRef) },
+      );
+    }
     if (superModel !== undefined) {
       // FR-024 — a dotted child-targeting ref must resolve to a node of the
       // SAME type and subtype as the extending node. Dotted-only check; the
@@ -1458,9 +1431,6 @@ function applyReservedKeys(
     if (typeof rawExtends !== "string") {
       reportProblem(`"${RESERVED_KEY_EXTENDS}" must be a string at ${path}`, strict, warnings, "ERR_UNRESOLVED_SUPER");
     } else {
-      // FR-032: canonical JSON `extends` must be FQN; reject a surviving
-      // relative form (no-op for YAML-format input, which was desugar-expanded).
-      guardRelativeRefInCanonical(`"${RESERVED_KEY_EXTENDS}"`, rawExtends, strict, warnings, path);
       model.setSuper(rawExtends);
     }
   }
@@ -1548,13 +1518,6 @@ function applyInlineAttrsAndUnknownKeys(
 
     const rawVal = nodeData[key];
 
-    // FR-032: a ref-bearing inline attr (@objectRef/@references/@from/@of/@via/
-    // @parameterRef/@payloadRef/@responseRef) in canonical JSON must be FQN —
-    // reject a surviving relative form. No-op for YAML-format input.
-    if (REF_BEARING_ATTR_NAMES.has(attrName)) {
-      guardRelativeRefInCanonical(`${ATTR_PREFIX}${attrName}`, rawVal, strict, warnings, path);
-    }
-
     try {
       const attr = materializeAttr(model, attrName, rawVal, registry);
       model.setMetaAttr(attr);

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

@@ -19,7 +19,7 @@ export const DB_DEFINITION: ProviderDefinition = {
           "name": "column",
           "min": 0,
           "max": 1,
-          "description": "Physical column name for this field on an rdb source. Defaults to the field name via columnNamingStrategy."
+          "description": "Physical column name for this field on an rdb source. Defaults to the field name under the project's naming.columns rule (the \"naming\" setting in .metaobjects/config.json)."
         },
         {
           "type": "attr",
@@ -108,7 +108,7 @@ export const DB_DEFINITION: ProviderDefinition = {
           "name": "table",
           "min": 0,
           "max": 1,
-          "description": "Physical SQL table name for source.rdb @kind: \"table\" (default). FR-016: Defaults from the source's bare structural `name` via the project's columnNamingStrategy when omitted, then from the owning entity's name. Pre-1.0 legacy spelling for view/materializedView/storedProc/tableFunction kinds during the transition; canonical-serializer rewrites to the kind-matching alias."
+          "description": "Physical SQL table name for source.rdb @kind: \"table\" (default). FR-016: Defaults from the source's bare structural `name` under the project's naming.tables rule (the \"naming\" setting in .metaobjects/config.json) when omitted, then from the owning entity's name. Pre-1.0 legacy spelling for view/materializedView/storedProc/tableFunction kinds during the transition; canonical-serializer rewrites to the kind-matching alias."
         },
         {
           "type": "attr",

package/src/persistence/source/meta-source.ts

@@ -6,7 +6,7 @@
 // Extends MetaData directly: no model wrapper, no metaOf() indirection.
 
 import { MetaData } from "../../shared/meta-data.js";
-import { pluralize, toSnakeCase } from "../../naming.js";
+import { applyTableNamingRule, physicalNamingOf, pluralizeTableNameLegacy } from "../../naming.js";
 import {
   SOURCE_ATTR_TABLE,
   SOURCE_ATTR_VIEW,
@@ -100,8 +100,11 @@ export class MetaSource extends MetaData {
    * four-step rule:
    *   1. Kind-matching alias (e.g. @proc when @kind: "storedProc").
    *   2. Legacy @table for non-table kind (pre-1.0 fallback).
-   *   3. Source's bare structural `name` via snake_case.
-   *   4. Owning entity's name via pluralize(snake_case).
+   *   3. Source's bare structural `name`, cased by the project's table rule.
+   *   4. Owning entity's name, cased by the project's table rule, through the frozen
+   *      legacy pluralizer — see pluralizeTableNameLegacy's doc for why it is frozen.
+   * The table rule is `naming.tables` in `.metaobjects/config.json` (ADR-0058), carried by
+   * the loaded root; default `snake_case`.
    *
    * Callers needing the legacy raw @table slot only should use `tableName`;
    * codegen / migrate / runtime should use `physicalName`.
@@ -127,14 +130,15 @@ export class MetaSource extends MetaData {
     // Step 3: source's structural `name` via snake_case (no pluralization —
     // the source's name IS the logical name).
     if (this.name !== "") {
-      return toSnakeCase(this.name);
+      return applyTableNamingRule(this.name, physicalNamingOf(this).tables);
     }
 
     // Step 4: owning entity's name via pluralize(snake_case). The MetaData
-    // parent of a source is always the entity that declared it.
+    // parent of a source is always the entity that declared it. Frozen legacy
+    // rule — this is a DEFAULT PHYSICAL name, not an API-surface name.
     const owner = this.parent;
     if (owner !== undefined && owner.name !== "") {
-      return pluralize(toSnakeCase(owner.name));
+      return pluralizeTableNameLegacy(applyTableNamingRule(owner.name, physicalNamingOf(this).tables));
     }
 
     return "";

package/src/registry-manifest-exclusions.ts

@@ -38,8 +38,8 @@
 //                           — a TS-web presentation facet (TS web client + TS
 //                           form codegen consume them; zero backend/codegen/
 //                           render consumers in any port), like the TS-only `D1`
-//                           dialect. Stay REGISTERED in TS; deregistered in
-//                           C#/Python; EXCLUDED from the manifest everywhere.
+//                           dialect. REGISTERED in every port, for LOADING
+//                           only; EXCLUDED from the manifest everywhere.
 //
 // The boundary is now an EXPLICIT classification (not a silent default): the
 // port-private set is enumerated WITH a reason category, and a TRIPWIRE

package/src/registry-manifest.ts

@@ -112,7 +112,7 @@ export interface ManifestType {
  * constant read `"0.10"`). Bump with that script — never by hand — so the manifest and
  * all four port constants move together.
  */
-export const METAMODEL_VERSION = "1.0";
+export const METAMODEL_VERSION = "1.1";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {

package/src/release-docs.ts

@@ -0,0 +1,48 @@
+// release-docs.ts — guide URLs pinned to the release this toolchain belongs to.
+//
+// Node-only (reads package.json), so it sits behind its own subpath
+// (`@metaobjectsdev/metadata/release-docs`) and is never reachable from the root entry,
+// which must stay browser-safe. The pure rule (`docsRefForVersion`) is in `docs-ref.ts`.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { docsBlobUrl, docsRefForVersion } from "./docs-ref.js";
+import { PHYSICAL_NAMING_MIGRATION_GUIDE_PATH } from "./naming.js";
+
+let cachedVersion: string | undefined;
+
+/**
+ * The version of this package, read from its own package.json (walking up from this
+ * module). All `@metaobjectsdev/*` npm packages release in lockstep, so it is also the
+ * version of the toolchain a message is printed by. "0.0.0" when not found.
+ */
+export function metadataPackageVersion(): string {
+  if (cachedVersion !== undefined) return cachedVersion;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string; version?: string };
+        if (pkg.name === "@metaobjectsdev/metadata" && pkg.version) return (cachedVersion = pkg.version);
+      } catch {
+        // not our manifest / unreadable — keep walking up
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return (cachedVersion = "0.0.0");
+}
+
+/** A guide URL pinned to the release this package belongs to. */
+export function guideUrl(repoRelativePath: string): string {
+  return docsBlobUrl(repoRelativePath, docsRefForVersion(metadataPackageVersion()));
+}
+
+/** The physical-naming migration guide, pinned: what `physicalNamingRemovedMessage` is given. */
+export function physicalNamingGuideUrl(): string {
+  return guideUrl(PHYSICAL_NAMING_MIGRATION_GUIDE_PATH);
+}

package/src/serializer-json.ts

@@ -41,15 +41,28 @@ const SOURCE_RDB_FUSED_KEY = `${TYPE_SOURCE}${TYPE_SUBTYPE_SEPARATOR}${SOURCE_SU
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * How references are written (ADR-0059 R8).
+ * - "canonical" (default): each reference as the loader resolved it — `pkg::Name`,
+ *   `::Name` for a root-level target from a packaged referrer — and the document
+ *   package rule below. The output loads back to the same model from any source.
+ * - "authored": each reference, `extends` included, exactly as written, and every
+ *   `package` where it was written. Only `meta fmt` uses it, so formatting never
+ *   rewrites what an author wrote (ADR-0059, C2).
+ */
+export type RefSpelling = "canonical" | "authored";
+
 export interface SerializeOptions {
   /** Pretty-print indent. 0 = no whitespace. Default 2. */
   indent?: number;
+  /** Reference spelling; default "canonical". */
+  refs?: RefSpelling;
 }
 
 export function serializeJson(model: MetaData, opts?: SerializeOptions): string {
   const indent = opts?.indent ?? 2;
 
-  const nodeObj = serializeNode(model, false);
+  const nodeObj = serializeNode(model, false, opts?.refs ?? "canonical", undefined);
   return JSON.stringify(nodeObj, null, indent === 0 ? undefined : indent);
 }
 
@@ -82,17 +95,57 @@ function fusedKey(type: string, subType: string): string {
 // Serialize a single node — returns { "<type>.<subType>": { ...body } }
 // ---------------------------------------------------------------------------
 
+/**
+ * How a node's `package` key is written. `undefined`: the node's own `package`, as
+ * authored. Otherwise the package the document rule (ADR-0059 R8) assigns it; ""
+ * writes none.
+ */
+type PackageSlot = string | undefined;
+
 function serializeNode(
   model: MetaData,
   effective: boolean,
+  refs: RefSpelling,
+  pkgSlot: PackageSlot,
 ): Record<string, unknown> {
-  const inner = serializeNodeInner(model, effective);
+  const inner = serializeNodeInner(model, effective, refs, pkgSlot);
   return { [fusedKey(model.type, model.subType)]: inner };
 }
 
+/** Effective package of a top-level node (ADR-0059 R10): own, else its file's. A
+ *  node built in code has no file, so it takes the root's package, as re-loading the
+ *  output would give it. */
+function topLevelPackage(node: MetaData, root: MetaData): string {
+  return node.package ?? node.fileDefaultPackage ?? root.package ?? "";
+}
+
+/**
+ * ADR-0059 R8 document package rule, for a `metadata.root` in canonical mode.
+ * Every top-level node in one non-empty package P: the root carries P (a node keeps
+ * a package it carries itself, as before). Otherwise the root carries none and each packaged top-level node
+ * carries its own. A root with no named top-level node keeps its own package.
+ */
+function documentPackages(root: MetaData): { rootPkg: string | undefined; perNode: boolean } {
+  // ADR-0039: own — the serializer writes the declared layer; the root has no super.
+  const named = root.ownChildren().filter((c) => c.name !== "");
+  if (named.length === 0) return { rootPkg: root.package, perNode: false };
+  const pkgs = new Set(named.map((c) => topLevelPackage(c, root)));
+  if (pkgs.size === 1) {
+    const only = [...pkgs][0]!;
+    // When every node already names P itself and the root names none, the
+    // document is already complete as written; adding a root package would only
+    // repeat it.
+    const selfNamed = root.package === undefined && named.every((c) => c.package === only);
+    if (only !== "") return { rootPkg: selfNamed ? undefined : only, perNode: false };
+  }
+  return { rootPkg: undefined, perNode: true };
+}
+
 function serializeNodeInner(
   model: MetaData,
   effective: boolean,
+  refs: RefSpelling,
+  pkgSlot: PackageSlot,
 ): Record<string, unknown> {
   // Canonical body-key order:
   //   1. name  2. package  3. extends  4. abstract
@@ -104,12 +157,19 @@ function serializeNodeInner(
     obj[RESERVED_KEY_NAME] = model.name;
   }
 
-  if (model.package !== undefined && model.package !== "") {
-    obj[RESERVED_KEY_PACKAGE] = model.package;
+  const isDocRoot = model.type === TYPE_METADATA && model.subType === SUBTYPE_ROOT;
+  const doc = isDocRoot && refs === "canonical" ? documentPackages(model) : undefined;
+
+  const pkg = doc !== undefined ? doc.rootPkg : pkgSlot !== undefined ? pkgSlot : model.package;
+  if (pkg !== undefined && pkg !== "") {
+    obj[RESERVED_KEY_PACKAGE] = pkg;
   }
 
-  if (model.superRef !== undefined) {
-    obj[RESERVED_KEY_EXTENDS] = model.superRef;
+  // After the loader's resolveReferences pass `superRef` is canonical (ADR-0059 R5);
+  // the authored spelling is kept beside it for `meta fmt`.
+  const superRef = refs === "authored" ? (model.authoredSuperRef ?? model.superRef) : model.superRef;
+  if (superRef !== undefined) {
+    obj[RESERVED_KEY_EXTENDS] = superRef;
   }
 
   if (model.isAbstract === true) {
@@ -141,13 +201,20 @@ function serializeNodeInner(
 
   const serializedChildren: Record<string, unknown>[] = [];
   for (const child of childList) {
-    // Attrs never appear in children(); only structural nodes recurse.
-    serializedChildren.push(serializeNode(child, effective));
+    // Attrs never appear in children(); only structural nodes recurse. A top-level
+    // node's package follows the document rule; deeper nodes keep their own.
+    // In a one-package document a node keeps any package it carries itself (the parser
+    // gives a root-level field its file's package), so single-package output is unchanged.
+    const childSlot: PackageSlot =
+      doc === undefined || !doc.perNode ? undefined : child.name !== "" ? topLevelPackage(child, model) : "";
+    serializedChildren.push(serializeNode(child, effective, refs, childSlot));
   }
 
   // Attrs ALWAYS emit inline @name (D5 — attrs have no children, one canonical form).
   for (const [attrName, attrValue] of attrMap) {
-    obj[`${ATTR_PREFIX}${attrName}`] = attrValue;
+    // ADR-0039: own — the authored value lives on the declaring attr node.
+    const authored = refs === "authored" && !effective ? model.ownMetaAttr(attrName)?.authoredValue : undefined;
+    obj[`${ATTR_PREFIX}${attrName}`] = authored ?? attrValue;
   }
 
   if (serializedChildren.length > 0) {
@@ -167,8 +234,8 @@ function serializeNodeInner(
 // byte-identical output from the same input metamodel.
 // ---------------------------------------------------------------------------
 
-export function canonicalSerialize(model: MetaData): string {
-  const raw = serializeJson(model, { indent: 2 });
+export function canonicalSerialize(model: MetaData, opts?: { refs?: RefSpelling }): string {
+  const raw = serializeJson(model, { indent: 2, refs: opts?.refs ?? "canonical" });
 
   const parsed = JSON.parse(raw) as unknown;
   // FR-016 / ADR-0018: rewrite legacy @table → kind-matching alias on source.rdb
@@ -188,7 +255,7 @@ export function canonicalSerialize(model: MetaData): string {
  * Used by the conformance harness's expected-effective fixtures.
  */
 export function canonicalSerializeEffective(model: MetaData): string {
-  const nodeObj = serializeNode(model, true);
+  const nodeObj = serializeNode(model, true, "canonical", undefined);
   const raw = JSON.stringify(nodeObj, null, 2);
 
   const parsed = JSON.parse(raw) as unknown;

package/src/shared/base-types.ts

@@ -22,6 +22,12 @@ export const TYPE_INDEX = "index";
 /** Capability / requirement records — `requirement.functional` (existence check)
  *  and `requirement.architectural` (universality check). Ruling amendment 3. */
 export const TYPE_REQUIREMENT = "requirement";
+/** FR-044 reporting vocabulary — a named group-by attribute (`dimension.attribute`,
+ *  `dimension.time`), a named aggregate (`measure.aggregate`, `measure.ratio`) and a
+ *  named row filter (`segment.filter`), all declared on an `object.entity`. */
+export const TYPE_DIMENSION = "dimension";
+export const TYPE_MEASURE = "measure";
+export const TYPE_SEGMENT = "segment";
 
 export const BASE_TYPES = [
   TYPE_METADATA,
@@ -38,6 +44,9 @@ export const BASE_TYPES = [
   TYPE_TEMPLATE,
   TYPE_INDEX,
   TYPE_REQUIREMENT,
+  TYPE_DIMENSION,
+  TYPE_MEASURE,
+  TYPE_SEGMENT,
 ] as const;
 export type BaseType = (typeof BASE_TYPES)[number];
 

package/src/shared/meta-data.ts

@@ -34,7 +34,10 @@ export abstract class MetaData {
   // order and post-merge tree shape. Mirrors Java's BaseMetaDataParser, which
   // folds getDefaultPackageName() into the registered name at parse time.
   fileDefaultPackage?: string;
-  superRef?: string;         // raw super reference string, pre-resolution
+  superRef?: string;         // super reference string; canonical after the loader's resolveReferences pass
+  /** ADR-0059 R5 — the `extends` value exactly as authored, kept when the loader's
+   *  `resolveReferences` pass rewrites `superRef` to its canonical spelling. */
+  authoredSuperRef?: string;
   private _superData?: MetaData; // post-resolution pointer; set by setSuperResolved() after parsing
   isAbstract: boolean = false;
 
@@ -384,6 +387,24 @@ export abstract class MetaData {
     return this.attrs().get(name);
   }
 
+  /**
+   * ADR-0059 — effective attr value for `name` as the author WROTE it: for a
+   * reference the loader rewrote to its canonical spelling, the authored string;
+   * for every other attr, the value. For human-facing text (descriptions) only —
+   * code that binds a reference reads `attr()`.
+   */
+  authoredAttr(name: string): AttrValue | undefined {
+    assertNotStructuralKeyword(name, "authoredAttr");
+    const seen = new Set<MetaData>();
+    for (let n: MetaData | undefined = this; n !== undefined && !seen.has(n); n = n._superData) {
+      seen.add(n);
+      // ADR-0039: own — locating the layer that declares the attr, walking the super chain.
+      const node = n._attrNodes.get(name);
+      if (node !== undefined) return node.authoredValue ?? node.value;
+    }
+    return undefined;
+  }
+
   /** True if `name` resolves to an effective attr (own or inherited). */
   hasAttr(name: string): boolean {
     assertNotStructuralKeyword(name, "hasAttr");

package/src/shared/meta-root.ts

@@ -7,8 +7,18 @@ import { MetaData } from "./meta-data.js";
 import { TYPE_OBJECT, TYPE_FIELD } from "./base-types.js";
 import type { MetaObject } from "../core/object/meta-object.js";
 import type { MetaField } from "../core/field/meta-field.js";
+import { DEFAULT_PHYSICAL_NAMING, type PhysicalNaming } from "../naming.js";
+import { PACKAGE_SEPARATOR } from "./structural.js";
+import { lookupCanonical } from "../naming-refs.js";
 
 export class MetaRoot extends MetaData {
+  /**
+   * The project's physical-naming rules (`naming` in `.metaobjects/config.json`, ADR-0058).
+   * Set by the project-aware load (`loadMemory`, `resolveCollection`), read by every name
+   * resolver through `physicalNamingOf`. A tree loaded with no project has the default.
+   */
+  physicalNaming: PhysicalNaming = DEFAULT_PHYSICAL_NAMING;
+
   /** Object entities defined at this root level. */
   objects(): MetaObject[] {
     return this.cached("objects", () =>
@@ -26,9 +36,18 @@ export class MetaRoot extends MetaData {
     );
   }
 
-  /** Find an object by name. */
+  /**
+   * Find an object by name, or by a canonical reference (ADR-0059): a value with a
+   * package separator (`acme::Program`, `::Program`) binds the object whose resolution
+   * key matches exactly, so a reference the loader rewrote to canonical form still finds
+   * its target. A bare name matches a root-level child by name, as before.
+   */
   findObject(name: string): MetaObject | undefined {
     return this.cached(`findObject:${name}`, () => {
+      if (name.includes(PACKAGE_SEPARATOR)) {
+        const node = lookupCanonical(this, name, { ownerType: TYPE_OBJECT });
+        return node !== undefined && node.type === TYPE_OBJECT ? (node as MetaObject) : undefined;
+      }
       // ADR-0039: own — the metadata root has no super chain (it never `extends`).
       const child = this.ownChildByTypeAndName(TYPE_OBJECT, name);
       return child !== undefined ? (child as MetaObject) : undefined;