@metaobjectsdev/codegen-ts 0.20.9 → 0.20.10

package/src/naming/collision-names.ts

@@ -0,0 +1,87 @@
+// ADR-0044 collision-scoped naming — shared across every codegen tier that emits
+// declarations from a reference closure (payload records today; the entity +
+// extract/output-parser tiers per issue #228).
+//
+// `assignEmittedNames` is a PURE function of the closure: a bare short name
+// unique in the closure emits bare; a collision emits EVERY member under its
+// package-qualified derived name (PascalCase each package segment + short
+// name). A still-colliding derived name fails loud (ERR_PAYLOAD_NAME_COLLISION).
+
+import { type ErrorCode, type MetaData, PACKAGE_SEPARATOR } from "@metaobjectsdev/metadata";
+
+// ADR-0044 backstop error code — a codegen-time (not loader) error, peer of
+// @metaobjectsdev/render's ERR_VAR_NOT_ON_PAYLOAD. Already promoted to the shared
+// cross-language error-code ledger in 0.19.3 (packages/metadata/src/errors.ts's
+// ERROR_CODES, fixtures/conformance/ERROR-CODES.json, server/python/src/metaobjects/errors.py).
+// That ledger has no per-code named export (only the ERROR_CODES array + the ErrorCode
+// union type), so this stays a local literal — but `satisfies ErrorCode` binds it to the
+// shared ledger's type: a future rename/removal there fails this file's typecheck instead
+// of silently drifting.
+export const ERR_PAYLOAD_NAME_COLLISION = "ERR_PAYLOAD_NAME_COLLISION" satisfies ErrorCode;
+
+function pascalSegment(s: string): string {
+  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
+}
+
+/** ADR-0044 — package-qualified derived name for a collision member: PascalCase
+ *  each `::`-segment of the node's effective package, concatenated, then the
+ *  bare short name (`acme::alpha::Note` -> `AcmeAlphaNote`). A root-level
+ *  (no-package) node has nothing to qualify with and keeps its bare name — two
+ *  root-level VOs can never share a name (the loader's own-package uniqueness
+ *  already rejects that), so this can't silently under-qualify. */
+export function packageQualifiedName(pkg: string, shortName: string): string {
+  if (pkg === "") return shortName;
+  return (
+    pkg
+      .split(PACKAGE_SEPARATOR)
+      .map(pascalSegment)
+      .join("") + shortName
+  );
+}
+
+/**
+ * ADR-0044 pass 2 — assign the emitted TS name for every VO in the closure. A
+ * PURE function of the closure's (fqn, bareName, package) triples — never of
+ * traversal order: bare short name unique in the closure -> bare name; a
+ * collision -> EVERY member gets its package-qualified derived name. If two
+ * DISTINCT fqns still derive the same name after qualification, throws
+ * (ERR_PAYLOAD_NAME_COLLISION) — never silently wrong.
+ */
+export function assignEmittedNames(closure: ReadonlyMap<string, MetaData>): Map<string, string> {
+  const byShortName = new Map<string, string[]>();
+  for (const [fqn, node] of closure) {
+    const bucket = byShortName.get(node.name);
+    if (bucket) bucket.push(fqn);
+    else byShortName.set(node.name, [fqn]);
+  }
+
+  const nameMap = new Map<string, string>();
+  for (const [shortName, fqns] of byShortName) {
+    if (fqns.length === 1) {
+      nameMap.set(fqns[0]!, shortName);
+      continue;
+    }
+    for (const fqn of fqns) {
+      const node = closure.get(fqn)!;
+      const pkg = node.package ?? node.fileDefaultPackage ?? "";
+      nameMap.set(fqn, packageQualifiedName(pkg, shortName));
+    }
+  }
+
+  // Backstop — sorted by fqn so which pair the message names (and whether the
+  // set of colliding names is non-empty) is a pure function of the closure, not
+  // of Map insertion/traversal order.
+  const ownerOf = new Map<string, string>();
+  for (const fqn of [...nameMap.keys()].sort()) {
+    const emitted = nameMap.get(fqn)!;
+    const existing = ownerOf.get(emitted);
+    if (existing !== undefined && existing !== fqn) {
+      throw new Error(
+        `${ERR_PAYLOAD_NAME_COLLISION}: payload record name collision: "${emitted}" derives from both "${existing}" and "${fqn}" — rename one value-object or move it to a package that derives a distinct name`,
+      );
+    }
+    ownerOf.set(emitted, fqn);
+  }
+
+  return nameMap;
+}

package/src/payload-codegen.ts

@@ -19,7 +19,9 @@
 //                           unique in the closure emits bare; a collision emits
 //                           EVERY member under its package-qualified derived
 //                           name (PascalCase each package segment + short name).
-//                           A still-colliding derived name fails loud.
+//                           A still-colliding derived name fails loud. Lives in
+//                           ./naming/collision-names.js — shared with the
+//                           entity + extract/output-parser tiers (#228).
 //   3. emitClosureDeclarations — emit each declaration + every reference through
 //                           the name map.
 
@@ -35,12 +37,12 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
-  PACKAGE_SEPARATOR,
   resolveObjectRef,
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
 import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
+import { assignEmittedNames } from "./naming/collision-names.js";
 
 const SCALAR_TS: Record<string, string> = {
   string: "string",
@@ -59,16 +61,6 @@ const SCALAR_TS: Record<string, string> = {
   timestamp: "string",
 };
 
-// ADR-0044 backstop error code — a codegen-time (not loader) error, peer of
-// @metaobjectsdev/render's ERR_VAR_NOT_ON_PAYLOAD. Declared LOCALLY rather than
-// added to packages/metadata/src/errors.ts's ERROR_CODES ledger: that ledger is
-// checked for FULL cross-port agreement against fixtures/conformance/ERROR-CODES.json
-// (packages/metadata/test/errors.test.ts) and, on the Python side, for corpus-code
-// coverage — registering it there before every port implements the ADR-0044 fix
-// would turn those OTHER ports' tests red. It moves into the shared ledger once the
-// Java/Kotlin/Python follow-up (ADR-0044 §4, items 3-4) lands alongside this code.
-const ERR_PAYLOAD_NAME_COLLISION = "ERR_PAYLOAD_NAME_COLLISION";
-
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 // ADR-0042: resolveObjectRef gives package-local-before-root-level precedence for a bare ref, FQN-exact otherwise.
 function findObject(root: MetaData, name: string, referrerPkg = ""): MetaData | undefined {
@@ -108,73 +100,6 @@ function collectClosure(
   }
 }
 
-function pascalSegment(s: string): string {
-  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
-}
-
-/** ADR-0044 — package-qualified derived name for a collision member: PascalCase
- *  each `::`-segment of the node's effective package, concatenated, then the
- *  bare short name (`acme::alpha::Note` -> `AcmeAlphaNote`). A root-level
- *  (no-package) node has nothing to qualify with and keeps its bare name — two
- *  root-level VOs can never share a name (the loader's own-package uniqueness
- *  already rejects that), so this can't silently under-qualify. */
-function packageQualifiedName(pkg: string, shortName: string): string {
-  if (pkg === "") return shortName;
-  return (
-    pkg
-      .split(PACKAGE_SEPARATOR)
-      .map(pascalSegment)
-      .join("") + shortName
-  );
-}
-
-/**
- * ADR-0044 pass 2 — assign the emitted TS name for every VO in the closure. A
- * PURE function of the closure's (fqn, bareName, package) triples — never of
- * traversal order: bare short name unique in the closure -> bare name; a
- * collision -> EVERY member gets its package-qualified derived name. If two
- * DISTINCT fqns still derive the same name after qualification, throws
- * (ERR_PAYLOAD_NAME_COLLISION) — never silently wrong.
- */
-function assignEmittedNames(closure: ReadonlyMap<string, MetaData>): Map<string, string> {
-  const byShortName = new Map<string, string[]>();
-  for (const [fqn, node] of closure) {
-    const bucket = byShortName.get(node.name);
-    if (bucket) bucket.push(fqn);
-    else byShortName.set(node.name, [fqn]);
-  }
-
-  const nameMap = new Map<string, string>();
-  for (const [shortName, fqns] of byShortName) {
-    if (fqns.length === 1) {
-      nameMap.set(fqns[0]!, shortName);
-      continue;
-    }
-    for (const fqn of fqns) {
-      const node = closure.get(fqn)!;
-      const pkg = node.package ?? node.fileDefaultPackage ?? "";
-      nameMap.set(fqn, packageQualifiedName(pkg, shortName));
-    }
-  }
-
-  // Backstop — sorted by fqn so which pair the message names (and whether the
-  // set of colliding names is non-empty) is a pure function of the closure, not
-  // of Map insertion/traversal order.
-  const ownerOf = new Map<string, string>();
-  for (const fqn of [...nameMap.keys()].sort()) {
-    const emitted = nameMap.get(fqn)!;
-    const existing = ownerOf.get(emitted);
-    if (existing !== undefined && existing !== fqn) {
-      throw new Error(
-        `${ERR_PAYLOAD_NAME_COLLISION}: payload record name collision: "${emitted}" derives from both "${existing}" and "${fqn}" — rename one value-object or move it to a package that derives a distinct name`,
-      );
-    }
-    ownerOf.set(emitted, fqn);
-  }
-
-  return nameMap;
-}
-
 /** Resolve `ref`'s emitted TS interface name under the ADR-0044 naming rule,
  *  scoped to `ref`'s OWN reference closure (the same closure
  *  `generatePayloadInterfaces(root, ref, referrerPkg)` would emit). Returns

package/src/reference/barrel.ts

@@ -51,7 +51,7 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator {
       path: "index.ts",
       content: await formatTs(
         renderBarrel(
-          entities.map((e) => ({ name: e.name, package: e.package })),
+          entities.map((e) => ({ name: ctx.renderContext!.valueObjectEmittedName(e), package: e.package })),
           ctx.renderContext!.extStyle,
           ctx.renderContext!.selfTarget,
           ctx.renderContext!.entityModuleTarget,

package/src/reference/queries.ts

@@ -4,7 +4,9 @@
 //
 // use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
 //                over Drizzle. Drop it if you hand-write your data access.
-// emits:         <target>/<Entity>.queries.ts per write-through entity.
+// emits:         <target>/<Entity>.queries.ts per source-backed object (any source.rdb kind,
+//                incl. read-only projections) — skipped for sourceless objects (incl. every
+//                object.value, source-less by value purity) and TPH subtypes (#248 R2).
 // customize:     the vanilla CRUD assembly below is OWNED — reorder, drop verbs (e.g. no delete),
 //                change the Db type alias, add your own finders. The render<Verb>Fn primitives emit
 //                each block; call your own instead to change a verb's body.
@@ -15,7 +17,7 @@
 // out of the package source. The vanilla path here is byte-identical to the built-in.
 
 import { code, joinCode, type Code } from "ts-poet";
-import { OBJECT_SUBTYPE_VALUE, type MetaObject } from "@metaobjectsdev/metadata";
+import type { MetaObject } from "@metaobjectsdev/metadata";
 import {
   perEntity,
   type Generator,
@@ -33,6 +35,7 @@ import {
   isProjection,
   isWriteThrough,
   isTphSubtype,
+  hasAnyRdbSource,
   renderQueriesFile, // engine composer — used for the delegated variants
   formatTs,
   entityOutputPath,
@@ -105,10 +108,15 @@ export interface QueriesFileOpts {
   target?: string;
 }
 
-// value objects have no identity (findById/updateById would target a non-existent column),
-// and TPH subtypes emit no standalone queries file — both are skipped unconditionally.
-const skipNonQueryable = (e: MetaObject): boolean =>
-  e.subType !== OBJECT_SUBTYPE_VALUE && !isTphSubtype(e);
+// #248 R2: persistability derives from declared/inherited source, never subtype.
+// An object with no source.rdb (of ANY kind) isn't backed by any store — the
+// rendered queries module would emit findById/updateById/deleteById against
+// Drizzle table/schema exports the entity file never emits for it (value
+// objects are subsumed here too: value purity bans sources on them, so no
+// loadable value ever has hasAnyRdbSource === true). TPH subtypes emit no
+// standalone queries file either — their per-subtype CRUD helpers live in the
+// discriminator base's queries file (which targets the single shared table).
+const skipNonQueryable = (e: MetaObject): boolean => hasAnyRdbSource(e) && !isTphSubtype(e);
 
 export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
   const userFilter = opts?.filter;

package/src/reference/routes.ts

@@ -6,6 +6,9 @@
 //                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
 // emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only
 //                (GET list + GET :id) for projections, polymorphic + per-subtype for TPH bases.
+//                Skipped for any sourceless object (incl. every object.value, source-less by
+//                value purity) and for TPH subtypes — no source.rdb means no table/allowlist
+//                for a routes file to import (#248 R2).
 // customize:     this generator (filter, output path, per-entity @emitRoutes opt-out, target) is
 //                YOURS — edit it freely. The route *composition* itself is richer than the others
 //                (M:N junction traversal, TPH per-subtype route sets), so it stays in the engine via
@@ -23,6 +26,7 @@ import {
   type GeneratorFactory,
   renderRoutesFile,
   isTphSubtype,
+  hasAnyRdbSource,
   formatTs,
   entityOutputPath,
   CODEGEN_ATTR_EMIT_ROUTES,
@@ -39,9 +43,12 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     name: "routes-file",
     // per-entity opt-out via `@emitRoutes: false`; TPH subtypes get no standalone routes
     // file (their routes live in the discriminator base's); AND-composed with your filter.
+    // #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
+    // backed by any store — routes against it would import Drizzle table/allowlist
+    // exports the entity file never emits. Gated by hasAnyRdbSource.
     filter: (e: MetaObject) =>
       // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
-      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false && !isTphSubtype(e) && userFilter(e),
+      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false && hasAnyRdbSource(e) && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");

package/src/render-context.ts

@@ -1,6 +1,7 @@
 // RenderContext — cross-cutting state passed to every template.
 
-import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { MetaRoot, MetaData, MetaField } from "@metaobjectsdev/metadata";
+import { resolveObjectRef, stripPackage } from "@metaobjectsdev/metadata";
 import type { Dialect } from "./column-mapper.js";
 import type { PkInfo } from "./pk-resolver.js";
 import type { RelationMap } from "./relation-resolver.js";
@@ -67,8 +68,28 @@ export interface RenderContext {
   pkMap: Map<string, PkInfo>;
   /** Pre-pass relation map for FK + relations() block emission. */
   relationMap: RelationMap;
-  /** Entity name → its metadata package (undefined if the entity has no package). Built once per run. */
+  /** Object name → its metadata package (undefined if the object has no package).
+   *  Built once per run. Value objects are keyed by their ADR-0044 EMITTED name
+   *  (bare when unique, package-qualified on a cross-package short-name collision;
+   *  #228) so `valueObjectModuleSpecifier` resolves the right module; entities and
+   *  other objects are keyed by their bare name. */
   packageOf: Map<string, string | undefined>;
+  /** ADR-0044/#228 — `resolutionKey()` → emitted TS name for every emitted
+   *  `object.value` in the run. A PURE function of the run's value-object set
+   *  (collision-scoped): a bare short name unique in the set stays bare; a
+   *  cross-package short-name collision qualifies EVERY member. Empty by default
+   *  (bare names — byte-identical to pre-#228 output). */
+  valueObjectNames: ReadonlyMap<string, string>;
+  /** The ADR-0044 emitted name for a value object being DECLARED (its interface,
+   *  Zod schema, and module filename). Non-value objects (entities) are never in
+   *  the collision set, so this returns their bare `name`. */
+  valueObjectEmittedName: (obj: MetaData) => string;
+  /** The ADR-0044 emitted name for a REFERENCE to a value object (`@objectRef`,
+   *  bare or FQN), resolved package-locally (ADR-0042) from `referrerPkg`. Falls
+   *  back to the bare (package-stripped) ref when it resolves to no emitted value
+   *  object — which is also the byte-identical result whenever there is no
+   *  collision. */
+  resolveValueObjectName: (ref: string, referrerPkg: string | undefined) => string;
   /** FR-019: module specifier to import externally-PROVIDED shared enums from
    *  (`@provided: true` declarations). Undefined when unset — referencing a
    *  provided enum without it is a codegen-time error. */
@@ -76,7 +97,7 @@ export interface RenderContext {
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). `collectionName` is built from `pluralizeCollections` + `collectionNameOverrides` (both default to always-pluralize). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "valueObjectNames" | "valueObjectEmittedName" | "resolveValueObjectName" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
@@ -85,6 +106,10 @@ export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "
   emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
+  /** ADR-0044/#228 value-object emitted-name map (resolutionKey → emitted name).
+   *  Defaults to an empty Map — bare names, byte-identical to pre-#228 output.
+   *  `runGen` always provides the real map. */
+  valueObjectNames?: ReadonlyMap<string, string>;
   selfTarget?: ResolvedTarget;
   entityModuleTarget?: ResolvedTarget;
   /** Auto-pluralize collection (table) variable names. Default true. */
@@ -93,6 +118,17 @@ export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "
   collectionNameOverrides?: Record<string, string>;
 };
 
+/** ADR-0042/#228 — the package a field's `@objectRef` resolves in: the FIELD's OWN
+ *  declaring package (which differs from the referring object's when the field is
+ *  inherited via `extends` from an abstract node in another package), falling back
+ *  to `fallbackPkg` (the referring object's package). THE single source of truth for
+ *  the referrer package passed to `RenderContext.resolveValueObjectName`, so every
+ *  value-object reference site resolves a cross-package short-name collision
+ *  identically (they cannot drift). Mirrors payload-codegen's `collectClosure`. */
+export function fieldDeclaringPackage(field: MetaField, fallbackPkg: string | undefined): string | undefined {
+  return field.parent?.package ?? field.parent?.fileDefaultPackage ?? fallbackPkg;
+}
+
 /** Append the configured extension to a cross-entity module specifier (which is
  *  always a bare, extension-less relative path like `./Foo`). */
 export function withExt(spec: string, style: ExtStyle): string {
@@ -129,6 +165,11 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     pluralize: opts.pluralizeCollections ?? true,
     overrides: opts.collectionNameOverrides ?? {},
   };
+  // ADR-0044/#228 — the value-object emitted-name map + its two accessors. When
+  // absent (bare template unit-tests), the map is empty, so both accessors return
+  // bare names and every consumer is byte-identical to pre-#228 output.
+  const valueObjectNames = opts.valueObjectNames ?? new Map<string, string>();
+  const loadedRoot = opts.loadedRoot;
   return {
     ...opts,
     extStyle: opts.extStyle ?? "js",
@@ -139,6 +180,13 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
+    valueObjectNames,
+    valueObjectEmittedName: (obj: MetaData) => valueObjectNames.get(obj.resolutionKey()) ?? obj.name,
+    resolveValueObjectName: (ref: string, referrerPkg: string | undefined) => {
+      const { node } = resolveObjectRef(loadedRoot, ref, referrerPkg ?? "");
+      const emitted = node !== undefined ? valueObjectNames.get(node.resolutionKey()) : undefined;
+      return emitted ?? stripPackage(ref);
+    },
     selfTarget: defaultTarget,
     entityModuleTarget: opts.entityModuleTarget ?? defaultTarget,
     collectionName: (entityName: string) => variableNameFromEntity(entityName, collectionNameOpts),

package/src/runner.ts

@@ -1,7 +1,9 @@
 import { join, relative, resolve, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
-import { MetaRoot } from "@metaobjectsdev/metadata";
+import { MetaRoot, OBJECT_SUBTYPE_VALUE } from "@metaobjectsdev/metadata";
+import { assignEmittedNames } from "./naming/collision-names.js";
+import { isAbstract } from "./instance-artifacts.js";
 import type { Generator, GenContext, EmittedFile } from "./generator.js";
 import type { MetaobjectsGenConfig } from "./metaobjects-config.js";
 import { normalizeConfig, DEFAULT_TARGET_NAME } from "./metaobjects-config.js";
@@ -143,9 +145,38 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // 3. Build shared render state once.
   const pkMap = buildPkMap(root);
   const relationMap = buildRelationMap(root);
-  const packageOf = new Map<string, string | undefined>(
-    root.objects().map((o) => [o.name, o.package]),
-  );
+  // ADR-0044/#228 — the ENTITY-tier collision domain is the run's EMITTED
+  // `object.value` SET (NOT any per-payload closure): value-object module
+  // filenames + `packageOf` are per-run/global, so the emitted-name map is built
+  // ONCE over every top-level `object.value` that actually produces a file, keyed
+  // by `resolutionKey()`. A bare short name unique across the set stays bare
+  // (byte-identical to pre-#228 output); a cross-package short-name collision
+  // qualifies every member (`AcmeAlphaNote`), and a still-colliding derived name
+  // fails loud (ERR_PAYLOAD_NAME_COLLISION, thrown by assignEmittedNames). A
+  // NON-emitted abstract value object (abstract + emitAbstractShapes off) produces
+  // no file/reference and is excluded — the entity-file generator's own emit gate
+  // (`isAbstract && !emitAbstractShapes` ⇒ skip) — so it can't over-qualify a
+  // concrete value object that merely shares its bare name in another package.
+  const isEmittedValueObject = (o: MetaObject): boolean =>
+    o.subType === OBJECT_SUBTYPE_VALUE && (!isAbstract(o) || config.emitAbstractShapes);
+  const valueObjectClosure = new Map<string, MetaData>();
+  for (const o of root.objects()) {
+    if (isEmittedValueObject(o)) valueObjectClosure.set(o.resolutionKey(), o);
+  }
+  const valueObjectNames = assignEmittedNames(valueObjectClosure);
+  // `packageOf` keys value objects by their EMITTED name (unique by construction
+  // via the backstop) so `valueObjectModuleSpecifier` resolves the right module
+  // even when two same-bare-named value objects live in different packages (the
+  // #244 misbinding disease). Non-value objects keep their bare name. With no
+  // collision, every emitted name equals its bare name, so this map is
+  // byte-identical to the pre-#228 `[o.name, o.package]` map.
+  const packageOf = new Map<string, string | undefined>();
+  for (const o of root.objects()) {
+    const key = o.subType === OBJECT_SUBTYPE_VALUE
+      ? (valueObjectNames.get(o.resolutionKey()) ?? o.name)
+      : o.name;
+    packageOf.set(key, o.package);
+  }
 
   // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
   // surface it on every generator's ctx.config so api-docs documents the Hono
@@ -192,6 +223,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       pkMap,
       relationMap,
       packageOf,
+      valueObjectNames,
       selfTarget,
       entityModuleTarget,
       ...(config.providedEnumModule !== undefined && { providedEnumModule: config.providedEnumModule }),

package/src/source-detect.ts

@@ -29,3 +29,23 @@ export function hasWritableRdbSource(entity: MetaObject): boolean {
   }
   return false;
 }
+
+/**
+ * True when the object declares (or inherits via extends — ADR-0039 resolving)
+ * at least one source.rdb child of ANY kind (writable OR read-only). Zero
+ * sources means "not backed by any store" (loader contract,
+ * validate-source-roles: zero sources is allowed, means not persisted) — the
+ * DB-artifact tier (queries/routes/api-model) must emit nothing for it, exactly
+ * as the table tier already refuses to emit a Drizzle table for it
+ * (hasWritableRdbSource, above — this is its any-kind sibling).
+ */
+export function hasAnyRdbSource(entity: MetaObject): boolean {
+  // ADR-0039: resolving — same rationale as hasWritableRdbSource.
+  for (const child of entity.children()) {
+    if (child.type !== TYPE_SOURCE) continue;
+    if (child.subType !== SOURCE_SUBTYPE_RDB) continue;
+    if (!(child instanceof MetaSource)) continue;
+    return true;
+  }
+  return false;
+}

package/src/templates/drizzle-schema.ts

@@ -9,8 +9,9 @@ import {
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   GENERATION_INCREMENT, GENERATION_UUID,
   FIELD_ATTR_AUTO_SET,
+  FIELD_ATTR_OBJECT_REF,
 } from "@metaobjectsdev/metadata";
-import { type RenderContext } from "../render-context.js";
+import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier, valueObjectModuleSpecifier } from "../import-path.js";
 import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
 import { tableNameFromEntity, columnNameFromField } from "../naming.js";
@@ -386,8 +387,18 @@ function renderColumn(
   // first."
   // Resolve a VO name → an imported type symbol (shared layout/package/extStyle-aware
   // helper, so the .$type<VO> import matches the field's TS type + Zod schema).
-  const voSym = (name: string) =>
-    imp(`${name}@${valueObjectModuleSpecifier(name, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle)}`);
+  // ADR-0044/#228 — resolve the field's @objectRef to the value object's EMITTED
+  // name (bare when unique in the run, package-qualified on a cross-package
+  // short-name collision), resolved package-locally from the FIELD's declaring
+  // package. `name` (the bare dollarTypeRef name) is the byte-identical fallback
+  // when the ref doesn't resolve to an emitted value object.
+  const voSym = (name: string) => {
+    const refRaw = field.attr(FIELD_ATTR_OBJECT_REF);
+    const emitted = typeof refRaw === "string"
+      ? ctx.resolveValueObjectName(refRaw, fieldDeclaringPackage(field, entityPackage))
+      : name;
+    return imp(`${emitted}@${valueObjectModuleSpecifier(emitted, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle)}`);
+  };
 
   let dollarTypeSegment: Code | string = "";
   if (spec.dollarTypeRef !== undefined) {

package/src/templates/entity-file.ts

@@ -7,8 +7,9 @@
 //   vanilla / write-through entity     → Drizzle table path
 
 import { code, imp, joinCode, type Code } from "ts-poet";
-import type { MetaObject } from "@metaobjectsdev/metadata";
-import type { RenderContext } from "../render-context.js";
+import type { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_OBJECT_REF } from "@metaobjectsdev/metadata";
+import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { renderDrizzleSchema } from "./drizzle-schema.js";
 import { renderInferredTypes, renderEnumTypeAliases } from "./inferred-types.js";
 import { renderZodValidators, isTphSubtype } from "./zod-validators.js";
@@ -23,7 +24,6 @@ import { projectionViewName } from "../projection/extract-view-spec.js";
 import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
-import { stripPackage } from "@metaobjectsdev/metadata";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { renderValueObjectFile } from "./value-object-file.js";
 import { isAbstract } from "../instance-artifacts.js";
@@ -131,10 +131,18 @@ export function renderEntityFile(
   if (writeThrough) {
     const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1);
     const fields = entity.fields();
-    const voModule = (refBase: string): string =>
-      valueObjectModuleSpecifier(stripPackage(refBase), ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle);
+    // ADR-0044/#228 — resolve a view column's `@objectRef` to the value object's
+    // EMITTED name + module TOGETHER (lock-step), so the read-view artifact imports
+    // `AcmeAlphaNote` from `./AcmeAlphaNote.js` (not a bare `Note` → `./Note.js`)
+    // under a cross-package short-name collision.
+    const voRef = (field: MetaField): { name: string; module: string } => {
+      const ref = field.attr(FIELD_ATTR_OBJECT_REF);
+      const name = ctx.resolveValueObjectName(typeof ref === "string" ? ref : "", fieldDeclaringPackage(field, entity.package));
+      const module = valueObjectModuleSpecifier(name, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle);
+      return { name, module };
+    };
     const viewOpts = {
-      dialect: ctx.dialect, columnNamingStrategy: ctx.columnNamingStrategy, timestampMode: ctx.timestampMode, voModule,
+      dialect: ctx.dialect, columnNamingStrategy: ctx.columnNamingStrategy, timestampMode: ctx.timestampMode, voRef,
     };
     const z = imp("z@zod");
     const docs = renderDocsFor(entity);