@metaobjectsdev/metadata 1.0.13 → 1.1.1-rc.1

package/src/naming-refs.ts

@@ -1,30 +1,25 @@
-// FR-032 (ADR-0032) — canonical reference expansion.
+// References: the one resolver every reference form goes through (ADR-0059).
 //
-// `expandRef(raw, packageContext)` is the SINGLE ref-expansion primitive. It
-// lowers an authored metadata reference to its fully-qualified canonical form
-// per ADR-0032 §2.1 — deterministically, with NO root fallback:
+// Sources do not interpret references: YAML, canonical JSON and any future source
+// build the tree with every reference string exactly as authored. This module
+// gives each form its meaning, once, against the built tree:
 //
-//   bare `Name` (no `::`, no leading `.`)  → `<P>::Name` (current package only;
-//                                            stays bare when P is empty/root).
-//   qualified `pkg::Name` (contains `::`,  → unchanged (absolute from root).
-//     NOT leading `::`)
-//   `::Rest` (leading `::`)                → strip the leading `::`; the
-//                                            remainder is absolute from root
-//                                            (so `::a::b::C` ≡ `a::b::C`,
-//                                            `::Apple` = root-level Apple).
-//   `..::Rest` (one or more leading `..::`) → drop one package segment from P
-//                                            per `..::`, then resolve Rest
-//                                            (itself bare/qualified) against the
-//                                            reduced package. Over-drop (more
-//                                            `..::` than P has segments) throws.
+//   `::Rest`      root-absolute — the node whose resolution key is exactly `Rest`
+//                 (`::Apple` is the root-level Apple; `::a::b::C` is `a::b::C`).
+//   `..::Rest`    parent-relative — drop one segment of the referrer's package per
+//                 `..::`, then the exact key `<remaining>::Rest`. More `..::` than
+//                 the package has segments is ERR_BAD_ATTR_VALUE.
+//   `pkg::Name`   exact.
+//   `Name`        the referrer's own package (`<referrerPkg>::Name`), else the
+//                 root-level `Name` (ADR-0042 §2). Never another package.
 //
-// The trailing FR-024 DOTTED CHILD suffix (`.child` / `.child.grandchild`) is
-// PRESERVED verbatim: only the OWNER part (everything before the first `.` in
-// the final `::`-segment) is expanded; the `.child...` tail is reattached.
+// No form falls back to another: `::Apple` never binds a local `acme::Apple`.
+// A FR-024 dotted child tail (`Owner.child.grand`) starts at the first `.` after the
+// last `::`; only the owner part is resolved by form, and the tail is kept as written.
 //
-// The desugar runs this on every ref-bearing attr so canonical JSON is FQN-only
-// (ADR-0032 §2.2/§2.3); the resolution layer then does pure FQN matching. The
-// `package` attribute is NEVER expanded — it is the node's identity.
+// `spellRef` is the inverse: the one canonical spelling of a resolved target that
+// resolves to the same node with or without a referrer. The `resolveReferences`
+// loader pass rewrites every reference to it, so consumers read canonical values.
 
 import type { MetaData } from "./shared/meta-data.js";
 import { PACKAGE_SEPARATOR, PACKAGE_PARENT, CHILD_REF_SEPARATOR } from "./shared/structural.js";
@@ -39,22 +34,20 @@ import {
   ORIGIN_AGGREGATE_ATTR_VIA,
 } from "./persistence/origin/origin-constants.js";
 import { SOURCE_ATTR_PARAMETER_REF } from "./persistence/source/source-constants.js";
+import { OBJECT_REPORT_ATTR_FROM, OBJECT_REPORT_ATTR_SPINE } from "./core/object/object-constants.js";
 import { TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF } from "./template/template-constants.js";
 
 const PARENT_PREFIX = PACKAGE_PARENT + PACKAGE_SEPARATOR; // "..::"
 
 /**
- * The inline (`@`-prefixed) attribute names whose VALUE is a metadata reference
- * subject to FR-032 expansion/guarding (ADR-0032 §3). The structural `extends`
- * key is handled separately (it is not `@`-prefixed). `@objectRef`/`@references`
- * are pure object refs; `@from`/`@of`/`@via` carry an entity HEAD (possibly with
- * 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. `@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.
+ * The inline (`@`-prefixed) attribute names whose VALUE is a metadata object
+ * reference (ADR-0059 R4). The structural `extends` key is handled separately (it is
+ * not `@`-prefixed). `@objectRef`/`@references`/`@through` are pure object refs;
+ * `@from`/`@of`/`@via`/`@spine` carry an entity HEAD with a dotted
+ * relationship/field tail; `@parameterRef`/`@payloadRef`/`@responseRef` name
+ * value-objects. The same set is used in every port. `@sourceRefField` (a FK FIELD
+ * name) and `@implementedBy` (which may name a template as well as an object) are
+ * 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")
@@ -68,13 +61,11 @@ export const REF_BEARING_ATTR_NAMES: ReadonlySet<string> = new Set<string>([
   SOURCE_ATTR_PARAMETER_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_RESPONSE_REF,
+  OBJECT_REPORT_ATTR_FROM, // = ORIGIN_PASSTHROUGH_ATTR_FROM ("from")
+  OBJECT_REPORT_ATTR_SPINE,
 ]);
 
-/**
- * True when `raw` is a relative reference form (`::Rest` or `..::Rest`) that the
- * YAML desugar must expand before canonical JSON. Canonical JSON must be FQN; a
- * relative ref surviving into it is `ERR_RELATIVE_REF_IN_CANONICAL`.
- */
+/** True when `raw` is a relative reference form (`::Rest` or `..::Rest`). */
 export function isRelativeRef(raw: string): boolean {
   return raw.startsWith(PACKAGE_SEPARATOR) || raw.startsWith(PARENT_PREFIX);
 }
@@ -86,7 +77,7 @@ export function isRelativeRef(raw: string): boolean {
  * at the first `.` AFTER the last `::`. Returns `{ owner, tail }` where `tail`
  * includes the leading `.` (or is "" when there is no child suffix).
  */
-function splitChildTail(raw: string): { owner: string; tail: string } {
+export function splitChildTail(raw: string): { owner: string; tail: string } {
   const lastSep = raw.lastIndexOf(PACKAGE_SEPARATOR);
   const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
   const dotInSeg = raw.indexOf(CHILD_REF_SEPARATOR, segStart);
@@ -95,8 +86,11 @@ function splitChildTail(raw: string): { owner: string; tail: string } {
 }
 
 /**
- * Expand an authored reference's OWNER part (no child tail) to its FQN per
- * ADR-0032 §2.1. Throws on parent-relative over-drop.
+ * Expand an authored reference's OWNER part (no child tail) against a package
+ * context: `::Rest` → `Rest`, `..::Rest` → the reduced package `::Rest`,
+ * `pkg::Name` unchanged, bare `Name` → `<P>::Name`. Throws on parent-relative
+ * over-drop. The resolver uses it for the two relative forms only; a bare name is
+ * resolved own-package-then-root (see `ownerCandidateKeys`).
  */
 function expandOwner(owner: string, packageContext: string): string {
   // root-absolute: leading "::" → strip; the remainder is absolute from root.
@@ -136,73 +130,176 @@ function expandOwner(owner: string, packageContext: string): string {
 }
 
 /**
- * Expand an authored reference to its fully-qualified canonical form per
- * ADR-0032 §2.1, preserving any FR-024 dotted child suffix. The package context
- * `P` is the declaring node's effective package (its own `package` or the
- * file-default). Throws on parent-relative over-drop — the caller emits an error.
+ * Expand an authored reference against a package context, preserving any FR-024
+ * dotted child suffix. Throws on parent-relative over-drop — the caller emits an
+ * error.
  */
 export function expandRef(raw: string, packageContext: string): string {
   const { owner, tail } = splitChildTail(raw);
   return expandOwner(owner, packageContext) + tail;
 }
 
+/** A parent-relative reference with more `..::` than its referrer's package has segments. */
+export class RefOverDropError extends Error {
+  readonly code = "ERR_BAD_ATTR_VALUE" as const;
+}
+
 /**
- * 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.
- *
- * 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.
+ * The resolution keys an OWNER reference (no child tail) may bind, in the order to
+ * try them (ADR-0059 R2). Every form but bare is one exact key; bare is the
+ * referrer's own package, then root-level. Throws RefOverDropError on over-drop.
  */
-export function refMatchesObject(node: MetaData, ref: string, referrerPkg = ""): boolean {
-  const key = node.resolutionKey();
-  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
+export function ownerCandidateKeys(owner: string, referrerPkg: string): readonly string[] {
+  if (owner.startsWith(PACKAGE_SEPARATOR)) return [owner.slice(PACKAGE_SEPARATOR.length)];
+  if (owner.startsWith(PARENT_PREFIX)) {
+    try {
+      return [expandOwner(owner, referrerPkg)];
+    } catch (err) {
+      throw new RefOverDropError((err as Error).message);
+    }
+  }
+  if (owner.includes(PACKAGE_SEPARATOR)) return [owner];
+  return referrerPkg !== "" ? [`${referrerPkg}${PACKAGE_SEPARATOR}${owner}`, owner] : [owner];
 }
 
 /**
- * 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.
+ * Does root-level object `node` satisfy object reference `ref` (no child tail),
+ * declared by a node whose effective package is `referrerPkg`? True when the node's
+ * resolution key is the FIRST candidate key that any object could bind — so it
+ * agrees with `resolveObjectRef`. Never matches on a short name.
+ */
+export function refMatchesObject(node: MetaData, ref: string, referrerPkg: string): boolean {
+  const resolved = resolveObjectRef(node.parent ?? node, ref, referrerPkg).node;
+  if (resolved !== undefined) return resolved === node;
+  return false;
+}
+
+/** The root's direct children of `type` (ADR-0039: root has no super). */
+function topLevelOfType(root: MetaData, type: string | undefined): readonly MetaData[] {
+  const all = root.children();
+  return type === undefined ? all : all.filter((c) => c.type === type);
+}
+
+/** Bind an owner reference among `candidates` by exact resolution key (R2). */
+function bindOwner(
+  candidates: readonly MetaData[],
+  owner: string,
+  referrerPkg: string,
+): { node?: MetaData | undefined; error?: string | undefined } {
+  let keys: readonly string[];
+  try {
+    keys = ownerCandidateKeys(owner, referrerPkg);
+  } catch (err) {
+    return { error: (err as Error).message };
+  }
+  for (const key of keys) {
+    const node = candidates.find((c) => c.resolutionKey() === key);
+    if (node !== undefined) return { node };
+  }
+  return {};
+}
+
+/**
+ * Resolve a metadata OBJECT reference (no child tail) under ADR-0059 R2.
+ * `referrerPkg` is the referrer's package (R3). Returns `{ node }` on resolution,
+ * `{ error }` for a parent-relative over-drop, or `{}` when nothing matches. The
+ * single object resolver every object-ref site shares.
  */
 export function resolveObjectRef(
   root: MetaData,
   ref: string,
   referrerPkg: string,
-): { 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) };
+): { node?: MetaData | undefined; error?: string | undefined } {
+  return bindOwner(topLevelOfType(root, TYPE_OBJECT), ref, referrerPkg);
+}
+
+/**
+ * Resolve a reference that may carry a dotted child tail (ADR-0059 R2): bind the
+ * owner among the root's top-level nodes (of `ownerType` when given), then walk the
+ * tail by child name. Intermediate segments must be unique among the current node's
+ * effective children; the last segment is scoped to `lastType` when given. Returns
+ * the owner as well as the target, so a caller can spell the owner and keep the tail.
+ */
+export function resolveRef(
+  root: MetaData,
+  ref: string,
+  referrerPkg: string,
+  opts?: { ownerType?: string; lastType?: string },
+): { node?: MetaData | undefined; owner?: MetaData | undefined; error?: string | undefined } {
+  const { owner, tail } = splitChildTail(ref);
+  const bound = bindOwner(topLevelOfType(root, opts?.ownerType), owner, referrerPkg);
+  if (bound.node === undefined) return bound;
+  if (tail === "") return { node: bound.node, owner: bound.node };
+  const path = tail.slice(CHILD_REF_SEPARATOR.length).split(CHILD_REF_SEPARATOR);
+  if (path.some((p) => p === "")) return {};
+  let current: MetaData = bound.node;
+  for (let i = 0; i < path.length - 1; i++) {
+    const matches = current.children().filter((c) => c.name === path[i]);
+    if (matches.length !== 1) return { owner: bound.node };
+    current = matches[0]!;
   }
-  // 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 { node: localKey !== ref ? objects.find((c) => c.resolutionKey() === ref) : undefined };
+  const last = path[path.length - 1]!;
+  const target = current
+    .children()
+    .find((c) => c.name === last && (opts?.lastType === undefined || c.type === opts.lastType));
+  return { node: target, owner: bound.node };
+}
+
+/**
+ * ADR-0059 R7 — resolve a CANONICAL reference with no referrer: strip one leading
+ * `::`, match a top-level node's resolution key exactly, then walk any dotted tail.
+ * For consumers that hold a resolved model and no referrer context. Never matches
+ * on a short name.
+ */
+export function lookupCanonical(
+  root: MetaData,
+  value: string,
+  opts?: { ownerType?: string; lastType?: string },
+): MetaData | undefined {
+  const { owner, tail } = splitChildTail(value);
+  const exact = owner.startsWith(PACKAGE_SEPARATOR) ? owner : `${PACKAGE_SEPARATOR}${owner}`;
+  return resolveRef(root, exact + tail, "", opts).node;
+}
+
+/**
+ * ADR-0059 R6 — the canonical spelling of a resolved owner, as written from a
+ * referrer in package `referrerPkg`: `pkg::Name` for a packaged target, `::Name` for
+ * a root-level target from a packaged referrer, `Name` from a root-level referrer.
+ * Every spelling resolves to the same node with or without a referrer.
+ */
+export function spellRef(target: MetaData, referrerPkg: string, tail = ""): string {
+  const key = target.resolutionKey();
+  const rootLevel = !key.includes(PACKAGE_SEPARATOR);
+  return (rootLevel && referrerPkg !== "" ? `${PACKAGE_SEPARATOR}${key}` : key) + tail;
+}
+
+/** Effective package of a node: its own `package`, else its file's (ADR-0059 R10). */
+export function effectivePackageOf(node: MetaData): string {
+  return node.package ?? node.fileDefaultPackage ?? "";
+}
+
+/** The top-level node (a direct child of the root) that physically contains `node`. */
+export function topLevelNodeOf(node: MetaData): MetaData {
+  let current = node;
+  while (current.parent !== undefined && current.parent.parent !== undefined) current = current.parent;
+  return current;
+}
+
+/**
+ * ADR-0059 R3 default — the package a reference attribute resolves in: the effective
+ * package of the top-level node that PHYSICALLY declares the attribute. For an
+ * attribute `node` inherits through `extends`, that is the ancestor that wrote it,
+ * so an inherited reference means what it meant where it was written.
+ */
+export function referrerPackageFor(node: MetaData, attrName: string): string {
+  let declarer: MetaData | undefined = node;
+  const seen = new Set<MetaData>();
+  // ADR-0039: own — locating the layer that physically declares the attr.
+  while (declarer !== undefined && !declarer.ownHasAttr(attrName) && !seen.has(declarer)) {
+    seen.add(declarer);
+    declarer = declarer.superResolved;
+  }
+  return effectivePackageOf(topLevelNodeOf(declarer ?? node));
 }
 
 /**
@@ -213,6 +310,27 @@ export function resolveObjectRef(
  * suggest). Appended to the per-attr unresolved-ref error message.
  */
 export function didYouMeanHint(root: MetaData, ref: string): string {
+  const found = sameNamedObjects(root, ref);
+  if (found === undefined) return "";
+  return ` An object named "${found.shortName}" exists in: ${found.candidates.join(", ")}. Qualify it with its package (FQN).`;
+}
+
+/**
+ * The did-you-mean suffix for an UNRESOLVED `extends` ref: the same candidate list
+ * as {@link didYouMeanHint}, plus the exact spelling to write. A bare `extends`
+ * resolves in the referrer's own package (ADR-0042/0059), so a base declared in
+ * another package must be named by its FQN. Returns "" when nothing is named alike.
+ */
+export function didYouMeanSuperHint(root: MetaData, ref: string): string {
+  const found = sameNamedObjects(root, ref);
+  if (found === undefined) return "";
+  return ` An object named "${found.shortName}" exists in: ${found.candidates.join(", ")}. Qualify it with its package (FQN): write extends: "${found.candidates[0]}".`;
+}
+
+function sameNamedObjects(
+  root: MetaData,
+  ref: string,
+): { shortName: string; candidates: string[] } | undefined {
   const { owner } = splitChildTail(ref);
   const sep = owner.lastIndexOf(PACKAGE_SEPARATOR);
   const shortName = sep === -1 ? owner : owner.slice(sep + PACKAGE_SEPARATOR.length);
@@ -220,6 +338,31 @@ export function didYouMeanHint(root: MetaData, ref: string): string {
     .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).`;
+  return candidates.length === 0 ? undefined : { shortName, candidates };
+}
+
+/**
+ * ADR-0059 R7 — the object a reference attribute on `node` names: the owner the loader
+ * bound once (`MetaAttr.resolvedTarget`), read RESOLVING so an inherited attribute
+ * works (ADR-0039). For a dotted ref (`Week.id`, `Program.weeks`) it is the owner
+ * object, not the tail. A tree built without the loader has no recorded target, so the
+ * value is resolved here from the package of the node that declared it. Undefined when
+ * the attribute is absent, is a list, or names nothing. Consumers use this instead of
+ * comparing a reference value to a short name.
+ */
+export function refTarget(node: MetaData, attrName: string): MetaData | undefined {
+  const seen = new Set<MetaData>();
+  for (let n: MetaData | undefined = node; n !== undefined && !seen.has(n); n = n.superResolved) {
+    seen.add(n);
+    // ADR-0039: own — locating the layer that declares the attr, walking the super chain.
+    const attr = n.ownMetaAttr(attrName);
+    if (attr === undefined) continue;
+    const recorded = attr.resolvedTarget;
+    if (recorded !== undefined) return Array.isArray(recorded) ? undefined : (recorded as MetaData);
+    const value = attr.value;
+    if (typeof value !== "string" || value === "") return undefined;
+    const { owner } = splitChildTail(value);
+    return resolveObjectRef(node.root(), owner, effectivePackageOf(topLevelNodeOf(n))).node;
+  }
+  return undefined;
 }

package/src/naming.ts

@@ -1,3 +1,4 @@
+import { docsBlobUrl } from "./docs-ref.js";
 import type { MetaData } from "./shared/meta-data.js";
 import { TYPE_FIELD } from "./shared/base-types.js";
 import { PACKAGE_SEPARATOR } from "./shared/structural.js";
@@ -53,18 +54,81 @@ export function toKebabCase(s: string): string {
 }
 
 /**
- * Column-naming strategy applied by the persistence layer to fields with no
- * explicit `@column` override. Persistence-layer config (set on
- * ObjectManager / buildExpectedSchema / codegen config), not a metadata attr —
- * the same metadata can drive snake_case (PG convention) or literal (EF
- * convention) consumers. TS port defaults to snake_case; C# port defaults to
- * literal.
+ * How a field with no `@column` becomes a column name. One project setting,
+ * `naming.columns` in `.metaobjects/config.json`, read by every port (ADR-0058): the
+ * loaded root carries it ({@link physicalNamingOf}), so codegen, migrate, the runtime
+ * and verify resolve the same name. Not a metadata attr: `@column` is the per-field
+ * override, this is the rule for the rest.
  */
 export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
 
-/** Single source of truth for the TS-port default. */
+/** Every column-naming rule, in the order the conformance corpus lists them. */
+export const COLUMN_NAMING_STRATEGIES: readonly ColumnNamingStrategy[] = ["snake_case", "literal", "kebab-case"];
+
+/** The default in EVERY port: what `meta migrate` has always created. */
 export const DEFAULT_COLUMN_NAMING_STRATEGY: ColumnNamingStrategy = "snake_case";
 
+/**
+ * How an object with no physical-name attribute (`@table`, `@view`, ...) and no source name
+ * gets its table name: the entity (or source) name cased by this rule. The entity-name
+ * fallback keeps the frozen legacy pluralizer under every rule ({@link pluralizeTableNameLegacy}).
+ */
+export type TableNamingRule = "snake_case" | "literal";
+
+/** Every table-naming rule. */
+export const TABLE_NAMING_RULES: readonly TableNamingRule[] = ["snake_case", "literal"];
+
+/** The project's physical-naming rules: `naming` in `.metaobjects/config.json` (ADR-0058). */
+export interface PhysicalNaming {
+  readonly columns: ColumnNamingStrategy;
+  readonly tables: TableNamingRule;
+}
+
+/** The default in every port, equal to what `meta migrate` has always created. */
+export const DEFAULT_PHYSICAL_NAMING: PhysicalNaming = Object.freeze({
+  columns: DEFAULT_COLUMN_NAMING_STRATEGY,
+  tables: "snake_case",
+});
+
+/**
+ * The physical-naming rules for the tree `node` belongs to: what its root carries, set by the
+ * project-aware load from `.metaobjects/config.json`, else {@link DEFAULT_PHYSICAL_NAMING}.
+ * Read through the root, not passed around, so every consumer of one loaded model resolves
+ * the same physical names.
+ */
+export function physicalNamingOf(node: MetaData): PhysicalNaming {
+  const naming = (node.root() as { physicalNaming?: PhysicalNaming }).physicalNaming;
+  return naming ?? DEFAULT_PHYSICAL_NAMING;
+}
+
+/** The migration guide every refusal of a former naming source names (ADR-0058). */
+export const PHYSICAL_NAMING_MIGRATION_GUIDE_PATH = "docs/features/migrations/physical-naming.md";
+
+/** The guide on `main`: the default when a caller has no release to pin to. */
+export const PHYSICAL_NAMING_MIGRATION_GUIDE = docsBlobUrl(PHYSICAL_NAMING_MIGRATION_GUIDE_PATH);
+
+/**
+ * What a former column-naming source prints when it is still used (ADR-0058): the one
+ * setting, where it goes, and the guide. Same words in every port. `what` names the source
+ * exactly; `value` is the rule it gave, carried into the example so the move is mechanical.
+ */
+export function physicalNamingRemovedMessage(
+  what: string,
+  value: string = "literal",
+  guide: string = PHYSICAL_NAMING_MIGRATION_GUIDE,
+): string {
+  return (
+    `${what} was removed in 1.1.0. Column and table naming is one project setting now, read by ` +
+    `every port: "naming" in .metaobjects/config.json, for example "naming": { "columns": "${value}" }. ` +
+    `Move it there and delete ${what}. See ${guide}`
+  );
+}
+
+/** `name` cased by the table rule. */
+export function applyTableNamingRule(name: string, rule: TableNamingRule): string {
+  return rule === "literal" ? name : toSnakeCase(name);
+}
+
 export function applyColumnNamingStrategy(name: string, strategy: ColumnNamingStrategy): string {
   switch (strategy) {
     case "literal":     return name;
@@ -238,13 +302,13 @@ export function resolveTableName(entity: MetaData): string {
   const source = primaryRdbSource(entity);
   if (source !== undefined) return source.physicalName;
   // Frozen: this is a DEFAULT PHYSICAL name, not an API-surface name. See
-  // pluralizeTableNameLegacy's doc.
-  return pluralizeTableNameLegacy(toSnakeCase(entity.name));
+  // pluralizeTableNameLegacy's doc. Cased by the project's table rule (ADR-0058).
+  return pluralizeTableNameLegacy(applyTableNamingRule(entity.name, physicalNamingOf(entity).tables));
 }
 
 export function resolveColumnName(
   field: MetaData,
-  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  strategy: ColumnNamingStrategy = physicalNamingOf(field).columns,
 ): string {
   // ADR-0039: resolving — a concrete field may inherit @column via extends.
   const col = field.attr(FIELD_ATTR_COLUMN);
@@ -335,7 +399,7 @@ export interface EntityNameMap {
 
 export function buildNameMap(
   entity: MetaData,
-  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  strategy: ColumnNamingStrategy = physicalNamingOf(entity).columns,
 ): EntityNameMap {
   const jsToDb = new Map<string, string>();
   const dbToJs = new Map<string, string>();

package/src/object-serializer.ts

@@ -20,6 +20,7 @@ import {
   DATA_TYPE_OBJECT,
 } from "./data-type.js";
 import { TYPE_OBJECT } from "./shared/base-types.js";
+import { lookupCanonical } from "./naming-refs.js";
 
 const TYPE_DISCRIMINATOR = "@type";
 
@@ -142,16 +143,13 @@ function coerceNumeric(raw: unknown): unknown {
   return raw;
 }
 
-/** Resolve an object-typed field's `@objectRef` to its target MetaObject by
- *  walking to the tree root and looking up the named object child. Returns
- *  undefined when there is no ref or it does not resolve (caller passes the
- *  raw value through — best-effort). */
+/** Resolve an object-typed field's `@objectRef` to its target MetaObject. The loader
+ *  has already rewritten the ref to its canonical spelling (ADR-0059 R5), so it is
+ *  looked up exactly, with no referrer (R7). Returns undefined when there is no ref
+ *  or it does not resolve (caller passes the raw value through — best-effort). */
 function resolveObjectRef(field: MetaField, mo: MetaObject): MetaObject | undefined {
   const ref = field.objectRef;
   if (ref === undefined) return undefined;
-  // ADR-0039: own — lookup is on the tree ROOT, which has no super chain
-  // (it never `extends`), so its own children ARE its effective children.
-  const found: MetaData | undefined = mo.root().ownChildByTypeAndName(TYPE_OBJECT, ref);
-  if (found === undefined) return undefined;
-  return found as MetaObject;
+  const found: MetaData | undefined = lookupCanonical(mo.root(), ref, { ownerType: TYPE_OBJECT });
+  return found as MetaObject | undefined;
 }