@metaobjectsdev/codegen-ts 0.20.9 → 0.20.10

package/src/templates/extract-delegate-emitter.ts

@@ -28,6 +28,7 @@ import {
   resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.js";
+import type { RenderContext } from "../render-context.js";
 
 // 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.
@@ -50,14 +51,20 @@ function isObjectField(field: MetaData): boolean {
   return field.subType === FIELD_SUBTYPE_OBJECT;
 }
 
-/** The extracted-mirror interface name for a value-object (`<Name>Extracted`). */
-export function mirrorName(vo: MetaData): string {
-  return `${vo.name}Extracted`;
+/** The extracted-mirror interface name for a value-object (`<Name>Extracted`). ADR-0044/#228:
+ *  `ctx` (optional) resolves the collision-scoped entity-domain emitted name (Task 3's
+ *  `valueObjectEmittedName`), so a cross-package short-name collision qualifies both the
+ *  entity module AND its extract mirror identically (`AcmeAlphaNoteExtracted`). Omitted →
+ *  the bare `vo.name` (bare template unit-test calls; byte-identical to pre-#228 output). */
+export function mirrorName(vo: MetaData, ctx?: RenderContext): string {
+  const name = ctx ? ctx.valueObjectEmittedName(vo) : vo.name;
+  return `${name}Extracted`;
 }
 
-/** The mapper function name for a value-object (`from<Name>Extracted`). */
-function mapperName(vo: MetaData): string {
-  return `from${vo.name}Extracted`;
+/** The mapper function name for a value-object (`from<Name>Extracted`). See {@link mirrorName}. */
+function mapperName(vo: MetaData, ctx?: RenderContext): string {
+  const name = ctx ? ctx.valueObjectEmittedName(vo) : vo.name;
+  return `from${name}Extracted`;
 }
 
 // =============================================================================
@@ -65,10 +72,10 @@ function mapperName(vo: MetaData): string {
 // =============================================================================
 
 /** The nullable mirror TS type for one field — nested-aware (recurses into nested mirror names). */
-function nestedMirrorType(field: MetaData, root: MetaData): string {
+function nestedMirrorType(field: MetaData, root: MetaData, ctx?: RenderContext): string {
   if (isObjectField(field)) {
     const target = refVo(field, root);
-    const base = target !== undefined ? mirrorName(target) : "unknown";
+    const base = target !== undefined ? mirrorName(target, ctx) : "unknown";
     const elem = `${base} | null`;
     return isArray(field) ? `(${elem})[] | null` : elem;
   }
@@ -92,10 +99,15 @@ function nestedMirrorType(field: MetaData, root: MetaData): string {
  * name (passed in) so the existing self-contained extract<Name>() and the delegating overload
  * share one mirror type. Returns the joined interface declarations in stable (BFS) order.
  */
-export function nestedMirrorInterfaces(vo: MetaData, root: MetaData, payloadMirror: string): string {
+export function nestedMirrorInterfaces(
+  vo: MetaData,
+  root: MetaData,
+  payloadMirror: string,
+  ctx?: RenderContext,
+): string {
   const out: string[] = [];
   const seen = new Set<string>();
-  emitMirror(vo, root, payloadMirror, seen, out);
+  emitMirror(vo, root, payloadMirror, seen, out, ctx);
   return out.join("\n\n");
 }
 
@@ -105,9 +117,14 @@ function emitMirror(
   interfaceName: string,
   seen: Set<string>,
   out: string[],
+  ctx?: RenderContext,
 ): void {
-  if (seen.has(vo.name)) return;
-  seen.add(vo.name);
+  // ADR-0044/#228: dedupe by resolutionKey(), NOT the bare name — two distinct value-objects
+  // sharing a bare short name across packages (the collision case) are DIFFERENT nodes with
+  // DIFFERENT resolutionKey()s; bare-name dedupe would treat the second as "already seen" and
+  // silently DROP its mirror interface (and every mapper reading it downstream).
+  if (seen.has(vo.resolutionKey())) return;
+  seen.add(vo.resolutionKey());
 
   const base = interfaceName.endsWith("Extracted")
     ? interfaceName.slice(0, -"Extracted".length)
@@ -118,7 +135,7 @@ function emitMirror(
   );
   lines.push(`export interface ${interfaceName} {`);
   for (const f of fields(vo)) {
-    lines.push(`  ${f.name}: ${nestedMirrorType(f, root)};`);
+    lines.push(`  ${f.name}: ${nestedMirrorType(f, root, ctx)};`);
   }
   lines.push("}");
   out.push(lines.join("\n"));
@@ -127,7 +144,7 @@ function emitMirror(
   for (const f of fields(vo)) {
     if (isObjectField(f)) {
       const target = refVo(f, root);
-      if (target !== undefined) emitMirror(target, root, mirrorName(target), seen, out);
+      if (target !== undefined) emitMirror(target, root, mirrorName(target, ctx), seen, out, ctx);
     }
   }
 }
@@ -149,10 +166,11 @@ export function nestedMappers(
   root: MetaData,
   rootMapperFn: string,
   rootMirror: string,
+  ctx?: RenderContext,
 ): string {
   const out: string[] = [];
   const seen = new Set<string>();
-  emitMapper(vo, root, seen, out, { fn: rootMapperFn, mirror: rootMirror });
+  emitMapper(vo, root, seen, out, { fn: rootMapperFn, mirror: rootMirror }, ctx);
   return out.join("\n\n");
 }
 
@@ -167,13 +185,17 @@ function emitMapper(
   seen: Set<string>,
   out: string[],
   override?: { fn: string; mirror: string },
+  ctx?: RenderContext,
 ): void {
-  if (seen.has(vo.name)) return;
-  seen.add(vo.name);
+  // ADR-0044/#228: dedupe by resolutionKey() — see emitMirror for why bare-name dedupe drops
+  // the second colliding VO's mapper (silently misdirecting its extraction to the FIRST
+  // colliding VO's mapper — the exact wrong-data bug closed by this fix).
+  if (seen.has(vo.resolutionKey())) return;
+  seen.add(vo.resolutionKey());
 
-  const fn = override?.fn ?? mapperName(vo);
-  const mir = override?.mirror ?? mirrorName(vo);
-  const assigns = fields(vo).map((f) => `    ${f.name}: ${mapperArg(f, root)},`);
+  const fn = override?.fn ?? mapperName(vo, ctx);
+  const mir = override?.mirror ?? mirrorName(vo, ctx);
+  const assigns = fields(vo).map((f) => `    ${f.name}: ${mapperArg(f, root, ctx)},`);
   const body = [
     `/** Map an assembled ValueObject graph into a typed \`${mir}\` mirror. Generated; null-tolerant. */`,
     `function ${fn}(o: unknown): ${mir} | null {`,
@@ -188,19 +210,19 @@ function emitMapper(
   for (const f of fields(vo)) {
     if (isObjectField(f)) {
       const target = refVo(f, root);
-      if (target !== undefined) emitMapper(target, root, seen, out);
+      if (target !== undefined) emitMapper(target, root, seen, out, undefined, ctx);
     }
   }
 }
 
 /** The mirror-field initializer expression that reads `field` from the assembled object `o`. */
-function mapperArg(field: MetaData, root: MetaData): string {
+function mapperArg(field: MetaData, root: MetaData, ctx?: RenderContext): string {
   const key = jsonStringLiteral(field.name);
 
   if (isObjectField(field)) {
     const target = refVo(field, root);
     if (target === undefined) return "null /* unresolved @objectRef */";
-    const fn = mapperName(target);
+    const fn = mapperName(target, ctx);
     if (isArray(field)) {
       return `mapObjectList(readProp(o, ${key}), ${fn})`;
     }
@@ -242,8 +264,10 @@ export function usedHelpers(vo: MetaData, root: MetaData): Set<string> {
   const stack = [vo];
   while (stack.length > 0) {
     const cur = stack.pop()!;
-    if (seen.has(cur.name)) continue;
-    seen.add(cur.name);
+    // ADR-0044/#228: dedupe by resolutionKey() — bare-name dedupe would skip walking the
+    // SECOND colliding VO's fields entirely, silently missing a helper only IT needs.
+    if (seen.has(cur.resolutionKey())) continue;
+    seen.add(cur.resolutionKey());
     for (const f of fields(cur)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);
@@ -285,8 +309,9 @@ export function hasNested(vo: MetaData, root: MetaData): boolean {
   const stack = [vo];
   while (stack.length > 0) {
     const cur = stack.pop()!;
-    if (seen.has(cur.name)) continue;
-    seen.add(cur.name);
+    // ADR-0044/#228: dedupe by resolutionKey() (see usedHelpers).
+    if (seen.has(cur.resolutionKey())) continue;
+    seen.add(cur.resolutionKey());
     for (const f of cur.children().filter((c) => c.type === TYPE_FIELD)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);

package/src/templates/extractor.ts

@@ -37,6 +37,7 @@ import { fields, isArray } from "./fr010-field-mapping.js";
 import { mirrorName } from "./extract-delegate-emitter.js";
 import { enumUnionAliasName } from "./inferred-types.js";
 import { enumValues } from "../enum-meta.js";
+import type { RenderContext } from "../render-context.js";
 
 // 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.
@@ -87,9 +88,13 @@ function isFieldRequired(field: MetaData): boolean {
   return field.attr(FIELD_ATTR_REQUIRED) === true;
 }
 
-/** The mirror→strict mapper name for a value-object (`toStrict<Name>`). */
-function mapperName(vo: MetaData): string {
-  return `toStrict${vo.name}`;
+/** The mirror→strict mapper name for a value-object (`toStrict<Name>`). ADR-0044/#228: `ctx`
+ *  (optional) resolves the collision-scoped entity-domain emitted name (matches Task 3's
+ *  entity module), so the mapper name agrees with the strict payload type it targets under a
+ *  cross-package short-name collision (`toStrictAcmeAlphaNote`). Omitted → bare `vo.name`. */
+function mapperName(vo: MetaData, ctx?: RenderContext): string {
+  const name = ctx ? ctx.valueObjectEmittedName(vo) : vo.name;
+  return `toStrict${name}`;
 }
 
 /**
@@ -99,7 +104,7 @@ function mapperName(vo: MetaData): string {
  * `f?: T` (= `T | undefined`, never `T | null`), so an absent optional maps to `undefined`.
  * Nested single/array objects recurse into their toStrict<Type> mapper, guarding when optional.
  */
-function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
+function strictArg(field: MetaData, root: MetaData, ownerName: string, ctx?: RenderContext): string {
   const name = field.name;
   const required = isFieldRequired(field);
 
@@ -109,7 +114,7 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
       // Unresolved @objectRef — the payload type would be `unknown`; pass through as-is.
       return required ? `m.${name}!` : `m.${name} ?? undefined`;
     }
-    const fn = mapperName(target);
+    const fn = mapperName(target, ctx);
     if (isArray(field)) {
       // Required array-of-objects: each element mapped; element nulls dropped at the type level
       // via the non-null assertion (extract never yields null elements for a present array).
@@ -164,10 +169,10 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
  * payload interface. The ROOT mapper reads the canonically-named root mirror (`<Template>Extracted`)
  * since the template name may differ from the payload VO name.
  */
-function emitMappers(payloadVo: MetaData, root: MetaData, rootMirror: string): string {
+function emitMappers(payloadVo: MetaData, root: MetaData, rootMirror: string, ctx?: RenderContext): string {
   const out: string[] = [];
   const seen = new Set<string>();
-  emitMapper(payloadVo, root, seen, out, rootMirror);
+  emitMapper(payloadVo, root, seen, out, rootMirror, ctx);
   return out.join("\n\n");
 }
 
@@ -177,14 +182,17 @@ function emitMapper(
   seen: Set<string>,
   out: string[],
   mirrorOverride?: string,
+  ctx?: RenderContext,
 ): void {
-  if (seen.has(vo.name)) return;
-  seen.add(vo.name);
+  // ADR-0044/#228: dedupe by resolutionKey() — see extract-delegate-emitter's emitMirror for why
+  // bare-name dedupe silently drops the second colliding VO's toStrict mapper.
+  if (seen.has(vo.resolutionKey())) return;
+  seen.add(vo.resolutionKey());
 
-  const fn = mapperName(vo);
-  const strict = vo.name;
-  const mir = mirrorOverride ?? mirrorName(vo);
-  const assigns = fields(vo).map((f) => `    ${f.name}: ${strictArg(f, root, vo.name)},`);
+  const fn = mapperName(vo, ctx);
+  const strict = ctx ? ctx.valueObjectEmittedName(vo) : vo.name;
+  const mir = mirrorOverride ?? mirrorName(vo, ctx);
+  const assigns = fields(vo).map((f) => `    ${f.name}: ${strictArg(f, root, strict, ctx)},`);
   out.push(
     [
       `/** Map the all-nullable \`${mir}\` mirror onto the strict \`${strict}\` payload. Generated. */`,
@@ -199,7 +207,7 @@ function emitMapper(
   for (const f of fields(vo)) {
     if (isObjectField(f)) {
       const target = refVo(f, root);
-      if (target !== undefined) emitMapper(target, root, seen, out);
+      if (target !== undefined) emitMapper(target, root, seen, out, undefined, ctx);
     }
   }
 }
@@ -224,23 +232,29 @@ interface PayloadImportGroup {
  * VO's interface AND the aliases for its own enum fields are imported from `./<VO>.js` — NOT from a
  * single `payloads.ts` (which no generator emits). Deduped, in discovery order, one group per VO.
  */
-function reachablePayloadGroups(vo: MetaData, root: MetaData): PayloadImportGroup[] {
+function reachablePayloadGroups(vo: MetaData, root: MetaData, ctx?: RenderContext): PayloadImportGroup[] {
   const groups: PayloadImportGroup[] = [];
   const seenVo = new Set<string>();
   const seenAlias = new Set<string>();
   const visit = (cur: MetaData) => {
-    if (seenVo.has(cur.name)) return;
-    seenVo.add(cur.name);
-    // The VO interface + its OWN enum aliases share the VO's entity module.
-    const types: string[] = [cur.name];
+    // ADR-0044/#228: dedupe by resolutionKey() — bare-name dedupe would treat a colliding
+    // second VO as "already seen" and drop its own import group entirely.
+    if (seenVo.has(cur.resolutionKey())) return;
+    seenVo.add(cur.resolutionKey());
+    // The VO interface + its OWN enum aliases share the VO's entity module. The module target
+    // is the ADR-0044/#228 entity-domain EMITTED name (Task 3's entityFile() writes `<emitted>.ts`),
+    // so a cross-package short-name collision imports from the SAME qualified module the entity
+    // tier emits (e.g. `AcmeAlphaNote` from `./AcmeAlphaNote.js`, never bare `Note`).
+    const emittedName = ctx ? ctx.valueObjectEmittedName(cur) : cur.name;
+    const types: string[] = [emittedName];
     for (const f of fields(cur)) {
-      const alias = enumAlias(f, cur.name);
+      const alias = enumAlias(f, emittedName);
       if (alias !== undefined && !seenAlias.has(alias)) {
         seenAlias.add(alias);
         types.push(alias);
       }
     }
-    groups.push({ module: cur.name, types });
+    groups.push({ module: emittedName, types });
     // Recurse into nested object refs (their interfaces live in their own modules).
     for (const f of fields(cur)) {
       if (isObjectField(f)) {
@@ -254,16 +268,16 @@ function reachablePayloadGroups(vo: MetaData, root: MetaData): PayloadImportGrou
 }
 
 /** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
-function reachableMirrorTypes(vo: MetaData, root: MetaData, rootMirror: string): string[] {
+function reachableMirrorTypes(vo: MetaData, root: MetaData, rootMirror: string, ctx?: RenderContext): string[] {
   const out: string[] = [rootMirror];
-  const seen = new Set<string>([vo.name]);
+  const seen = new Set<string>([vo.resolutionKey()]);
   const visit = (cur: MetaData) => {
     for (const f of fields(cur)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);
-        if (target !== undefined && !seen.has(target.name)) {
-          seen.add(target.name);
-          out.push(mirrorName(target));
+        if (target !== undefined && !seen.has(target.resolutionKey())) {
+          seen.add(target.resolutionKey());
+          out.push(mirrorName(target, ctx));
           visit(target);
         }
       }
@@ -279,7 +293,7 @@ function reachableMirrorTypes(vo: MetaData, root: MetaData, rootMirror: string):
  * or if the target format is not json/xml (the extract tier requires the extract<Name> API, which
  * only the json/xml output-parsers emit).
  */
-export function renderExtractor(root: MetaData, templateName: string): string {
+export function renderExtractor(root: MetaData, templateName: string, ctx?: RenderContext): string {
   const tmpl = findTemplate(root, templateName);
   if (!tmpl) {
     throw new Error(`template "${templateName}" not found in metadata root`);
@@ -305,16 +319,19 @@ export function renderExtractor(root: MetaData, templateName: string): string {
     );
   }
 
-  const strictType = vo.name; // the payload VO's interface name (payload-codegen emits the bare VO name)
+  // ADR-0044/#228: the strict payload TYPE name is the entity-domain EMITTED name (Task 3's
+  // `valueObjectEmittedName`) — the SAME name entityFile() declared the interface under, so a
+  // cross-package short-name collision emits e.g. `AcmeAlphaNote`, matching `./AcmeAlphaNote.js`.
+  const strictType = ctx ? ctx.valueObjectEmittedName(vo) : vo.name;
   const rootMirror = `${templateName}Extracted`;
   const extractLenientWithName = `extractLenient${templateName}WithLoader`; // the nested-capable lenient extract (output-parser)
   const extractLenientPublic = `extractLenient${templateName}`; // re-exposed never-throws lenient tier name
   const extractName = `extract${templateName}`;
-  const rootMapper = mapperName(vo);
+  const rootMapper = mapperName(vo, ctx);
 
-  const payloadGroups = reachablePayloadGroups(vo, root);
-  const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror);
-  const mappers = emitMappers(vo, root, rootMirror);
+  const payloadGroups = reachablePayloadGroups(vo, root, ctx);
+  const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror, ctx);
+  const mappers = emitMappers(vo, root, rootMirror, ctx);
 
   // One type-only import per VO entity module (the VO interface + its own enum
   // union-aliases co-located there). NOT a single non-existent `./payloads.js`.

package/src/templates/inferred-types.ts

@@ -40,7 +40,7 @@ import { enumValues } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { sharedEnumForField } from "../enum-shared.js";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "../enum-import.js";
-import type { RenderContext } from "../render-context.js";
+import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 
 /**
  * Emit Drizzle's InferSelectModel / InferInsertModel aliases for an entity.
@@ -132,6 +132,11 @@ export function renderEnumTypeAliases(entity: MetaObject, ctx?: RenderContext):
   // De-duplicate by type-alias name — multiple fields can extend the same abstract enum.
   const seen = new Set<string>();
   const lines: string[] = [];
+  // ADR-0044/#228 — an inline enum's alias is `<Owner><Field>`; `<Owner>` is this
+  // object's EMITTED name so a collision-qualified value object declares (and its
+  // interface references) `AcmeAlphaNoteStatus`, not a bare `NoteStatus`. Entities
+  // and non-colliding value objects keep their bare name (byte-identical).
+  const ownerName = ctx ? ctx.valueObjectEmittedName(entity) : entity.name;
 
   for (const field of entity.fields()) {
     if (field.subType !== FIELD_SUBTYPE_ENUM) continue;
@@ -139,7 +144,7 @@ export function renderEnumTypeAliases(entity: MetaObject, ctx?: RenderContext):
     const values = enumValues(field);
     if (values === undefined) continue;
 
-    const typeName = enumUnionAliasName(entity.name, field);
+    const typeName = enumUnionAliasName(ownerName, field);
     if (seen.has(typeName)) continue;
     seen.add(typeName);
 
@@ -214,6 +219,12 @@ export function fieldTsTypeString(ownerName: string, field: MetaField): string {
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
+      // #228: docs-tier bare name under collision — this is the deprecated `meta docs`
+      // TEXT-shape helper (no ctx/root in scope; callers api-field-shape run under
+      // api-model's `{ pkMap } as RenderContext` shim), so it can't resolve the ADR-0044
+      // emitted name. Byte-identical to codegen in every non-colliding model; on a
+      // cross-package collision it documents the bare `Note` while codegen emits
+      // `AcmeAlphaNote`. Threading a real RenderContext into api-docs is out of scope.
       const base = stripPackage(ref);
       return field.resolvedIsArray() ? `${base}[]` : base;
     }
@@ -241,6 +252,10 @@ export function fieldTsTypeString(ownerName: string, field: MetaField): string {
  * ts-poet `imp(...)` — matching how the Zod emitter hoists `<Ref>InsertSchema`.
  */
 function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: RenderContext): Code {
+  // ADR-0044/#228 — the owning value-object's EMITTED name (bare when unique in
+  // the run, package-qualified on a cross-package short-name collision). Drives
+  // the inline enum-union alias so it matches the alias declared for this object.
+  const ownerName = ctx ? ctx.valueObjectEmittedName(entity) : entity.name;
   // `@dbColumnType: jsonb` (open JSON bag) → `unknown`, in lock-step with
   // fieldTsTypeString above and the `z.unknown()` Zod emission.
   if (field.attr(FIELD_ATTR_DB_COLUMN_TYPE) === DB_COLUMN_TYPE_JSONB) {
@@ -252,16 +267,19 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare; the
-      // referenced interface is named by the BARE short name. The import MODULE is
-      // resolved through the shared layout/package/extStyle-aware helper (the SAME
-      // one the Zod schema + Drizzle .$type<> use) so all three agree. Without a
-      // ctx (bare unit-test calls) fall back to the flat same-dir specifier.
-      const base = stripPackage(ref);
+      // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare.
+      // ADR-0044/#228 — the referenced interface is named by its 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. The import MODULE is resolved through the shared
+      // layout/package/extStyle-aware helper (the SAME one the Zod schema +
+      // Drizzle .$type<> use) so all three agree. Without a ctx (bare unit-test
+      // calls) fall back to the bare name + flat same-dir specifier.
+      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entity.package)) : stripPackage(ref);
       const moduleSpec = ctx
-        ? valueObjectModuleSpecifier(base, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
-        : `./${base}.js`;
-      const refImp = imp(`${base}@${moduleSpec}`);
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
+        : `./${refName}.js`;
+      const refImp = imp(`${refName}@${moduleSpec}`);
       return field.resolvedIsArray() ? code`${refImp}[]` : code`${refImp}`;
     }
     return field.resolvedIsArray() ? code`unknown[]` : code`unknown`;
@@ -271,11 +289,11 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
   if (field.subType === FIELD_SUBTYPE_MAP) {
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const base = stripPackage(ref);
+      const refName = ctx ? ctx.resolveValueObjectName(ref, fieldDeclaringPackage(field, entity.package)) : stripPackage(ref);
       const moduleSpec = ctx
-        ? valueObjectModuleSpecifier(base, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
-        : `./${base}.js`;
-      const refImp = imp(`${base}@${moduleSpec}`);
+        ? valueObjectModuleSpecifier(refName, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
+        : `./${refName}.js`;
+      const refImp = imp(`${refName}@${moduleSpec}`);
       return code`Record<string, ${refImp}>`;
     }
     const vt = field.attr(FIELD_ATTR_VALUE_TYPE);
@@ -287,7 +305,7 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
   if (field.subType === FIELD_SUBTYPE_ENUM) {
     const values = enumValues(field);
     if (values !== undefined) {
-      const alias = enumUnionAliasName(entity.name, field);
+      const alias = enumUnionAliasName(ownerName, field);
       // FR-019: a shared/provided enum's type lives in another module (./enums or
       // the provided module). Use imp() so ts-poet hoists `import { type E }` —
       // the local interface can then reference E. Inline enums reference the
@@ -322,6 +340,10 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
 export function renderValueObjectInterface(entity: MetaObject, ctx?: RenderContext): Code {
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
+  // ADR-0044/#228 — the declared interface name is this value object's EMITTED
+  // name (bare when unique in the run, package-qualified on a cross-package
+  // short-name collision). Byte-identical (bare) when there is no collision.
+  const objName = ctx ? ctx.valueObjectEmittedName(entity) : entity.name;
 
   const lines: Code[] = [];
   for (const field of entity.fields()) {
@@ -333,7 +355,7 @@ export function renderValueObjectInterface(entity: MetaObject, ctx?: RenderConte
 
   // joinCode with "\n" interpolates each Code segment on its own line and
   // keeps the imp() registrations intact so ts-poet hoists the imports.
-  return code`${docsPrefix}export interface ${entity.name} {
+  return code`${docsPrefix}export interface ${objName} {
 ${joinCode(lines, { on: "\n" })}
 }
 `;

package/src/templates/output-parser.ts

@@ -28,6 +28,7 @@ import {
   usedHelpers,
   hasNested,
 } from "./extract-delegate-emitter.js";
+import type { RenderContext } from "../render-context.js";
 
 const SCALAR_ZOD: Record<string, string> = {
   string: "z.string()",
@@ -93,7 +94,7 @@ function renderObjectSchema(vo: MetaData, root: MetaData, seen: ReadonlySet<stri
  * Throws if the template isn't found, isn't a template.output, or its
  * @payloadRef doesn't resolve to an object.value.
  */
-export function renderOutputParser(root: MetaData, templateName: string): string {
+export function renderOutputParser(root: MetaData, templateName: string, ctx?: RenderContext): string {
   const tmpl = findTemplate(root, templateName);
   if (!tmpl) {
     throw new Error(`template "${templateName}" not found in metadata root`);
@@ -176,8 +177,10 @@ export function ${safeParseName}(
   // The nullable mirror is the return shape of the delegating extract. Use the nested-aware
   // emitter so the payload mirror's nested-object / array-of-object components are typed (not
   // `unknown`), and so a mirror interface is emitted for every reachable nested value-object.
-  // The payload mirror keeps the canonical `<Template>Extracted` name.
-  const mirrorDecls = nestedMirrorInterfaces(vo, root, extractedName);
+  // The payload mirror keeps the canonical `<Template>Extracted` name. ADR-0044/#228: `ctx`
+  // qualifies a nested mirror's name/dedupe when its VO's bare short name collides across
+  // packages, matching Task 3's entity-domain emitted name (e.g. `AcmeAlphaNoteExtracted`).
+  const mirrorDecls = nestedMirrorInterfaces(vo, root, extractedName, ctx);
 
   // Render-package imports the (single, loader-delegating) extract block needs. Kept minimal so
   // the file has no unused imports (tsc noUnusedLocals-safe).
@@ -190,19 +193,41 @@ export function ${safeParseName}(
   // graph is then mapped into the typed nullable mirror graph by the generated from<VO>Extracted
   // mappers. Codegen-wrapping-runtime (a generated DAO calling the dynamic-metadata runtime).
   //
-  // The baked PAYLOAD_NAME is the resolved payload VO's SIMPLE name (root.findObject matches on
-  // the object's `name`, not its FQN). The root mapper is named for the TEMPLATE (so it returns
-  // the canonically-named `<Template>Extracted` mirror); nested mappers use their VO names.
+  // The baked PAYLOAD_NAME is normally the resolved payload VO's SIMPLE name (root.findObject
+  // matches on the object's `name`, not its FQN). The root mapper is named for the TEMPLATE (so
+  // it returns the canonically-named `<Template>Extracted` mirror); nested mappers use their VO
+  // names (via the entity-domain name map, so they agree with the imported mirror types above).
+  //
+  // ADR-0044/#228 — `root.findObject()` (MetaRoot's public runtime API) is a BARE-name-only,
+  // first-match lookup with no package awareness. If THIS PAYLOAD's own bare name collides with
+  // a same-short-name value-object elsewhere in the run (the identical signal Option A already
+  // computes: `ctx.valueObjectEmittedName(vo)` diverges from the bare name), a bare lookup could
+  // silently resolve to the WRONG package's object at runtime (load-order-dependent — the exact
+  // hazard class ADR-0042 closed everywhere else). When it does collide, bake the FQN
+  // (`resolutionKey()`) instead and resolve it via the SAME canonical ADR-0042 `resolveObjectRef`
+  // this file's own build-time `findObject()` wraps (FQN-exact, load-order-independent). A
+  // non-colliding payload keeps the bare name + `root.findObject()` path — byte-identical to
+  // pre-#228 output.
   const payloadName = vo.name;
+  const emittedPayloadName = ctx ? ctx.valueObjectEmittedName(vo) : payloadName;
+  const payloadNameCollides = emittedPayloadName !== payloadName;
+  const bakedPayloadName = payloadNameCollides ? vo.resolutionKey() : payloadName;
   const rootMapper = rootMapperName(templateName);
   void hasNested;
+  const lookupExpr = payloadNameCollides
+    ? `resolveObjectRef(root, ${payloadFqnConst}, "").node`
+    : `root.findObject(${payloadFqnConst})`;
   const delegating = `
-/** Payload value-object name this parser extracts — resolved against a loaded MetaRoot at runtime. */
-export const ${payloadFqnConst} = ${JSON.stringify(payloadName)};
+/** Payload value-object name this parser extracts — resolved against a loaded MetaRoot at runtime.${
+    payloadNameCollides
+      ? " ADR-0042 FQN (this payload's bare name collides with a same-short-name value object elsewhere in the run)."
+      : ""
+  } */
+export const ${payloadFqnConst} = ${JSON.stringify(bakedPayloadName)};
 
 ${mirrorDecls}
 
-${nestedMappers(vo, root, rootMapper, extractedName)}
+${nestedMappers(vo, root, rootMapper, extractedName, ctx)}
 
 ${delegateHelpers(usedHelpers(vo, root))}
 
@@ -221,7 +246,7 @@ export function ${extractLenientWithName}(
   text: string,
   opts?: Partial<ExtractOptions> | null,
 ): ExtractionResult<${extractedName}> {
-  const mo = root.findObject(${payloadFqnConst});
+  const mo = ${lookupExpr};
   if (mo === undefined) {
     throw new Error(\`${extractLenientWithName}: payload "\${${payloadFqnConst}}" not found in the supplied MetaRoot\`);
   }
@@ -230,8 +255,11 @@ export function ${extractLenientWithName}(
 }
 `;
 
-  // The delegating overload needs runtime-ts (extractObject) + the MetaRoot type from metadata.
-  const metadataImport = `import type { MetaRoot } from "@metaobjectsdev/metadata";\n`;
+  // The delegating overload needs runtime-ts (extractObject) + the MetaRoot type from metadata
+  // (+ resolveObjectRef, ADR-0044/#228, only when this payload's own bare name collides).
+  const metadataImport = payloadNameCollides
+    ? `import type { MetaRoot } from "@metaobjectsdev/metadata";\nimport { resolveObjectRef } from "@metaobjectsdev/metadata";\n`
+    : `import type { MetaRoot } from "@metaobjectsdev/metadata";\n`;
   const runtimeImport = `import { extractObject } from "@metaobjectsdev/runtime-ts";\n`;
 
   return (

package/src/templates/projection-decl.ts

@@ -10,12 +10,13 @@
 import { code, imp, joinCode, type Code } from "ts-poet";
 import {
   MetaField, MetaObject, type MetaRoot,
+  FIELD_ATTR_OBJECT_REF, stripPackage,
 } from "@metaobjectsdev/metadata";
 import { projectionViewName } from "../projection/extract-view-spec.js";
 import { columnNameFromField, toSnakeCase, pluralize } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
-import type { RenderContext } from "../render-context.js";
+import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
 import { valueObjectModuleSpecifier } from "../import-path.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
@@ -92,13 +93,22 @@ export function renderProjectionDecl(
 ): string {
   const { dialect, columnNamingStrategy, apiPrefix = "", timestampMode = "string", allowlists = true, ctx, includeViewDecl = true } = opts;
 
-  // Resolve a value-object name → its import module. Layout/package/extStyle-aware
-  // when a render context is present (so the projection's VO imports match the
-  // entity's), else a flat same-dir import — identical to zodFieldExpr's fallback.
-  const voModule = (refBase: string): string =>
-    ctx
-      ? valueObjectModuleSpecifier(refBase, ctx.packageOf, projection.package, ctx.outputLayout, ctx.extStyle)
-      : `./${refBase}.js`;
+  // ADR-0044/#228 — resolve a projection field's `@objectRef` to the value object's
+  // EMITTED name + module TOGETHER (lock-step): bare when unique in the run,
+  // package-qualified on a cross-package short-name collision, so the projection's
+  // VO import matches the entity's. Layout/package/extStyle-aware when a render
+  // context is present, else a flat same-dir import (zodFieldExpr's fallback).
+  const voRef = (field: MetaField): { name: string; module: string } => {
+    const ref = field.attr(FIELD_ATTR_OBJECT_REF);
+    const rawRef = typeof ref === "string" ? ref : "";
+    const name = ctx
+      ? ctx.resolveValueObjectName(rawRef, fieldDeclaringPackage(field, projection.package))
+      : stripPackage(rawRef);
+    const module = ctx
+      ? valueObjectModuleSpecifier(name, ctx.packageOf, projection.package, ctx.outputLayout, ctx.extStyle)
+      : `./${name}.js`;
+    return { name, module };
+  };
 
   const z = imp("z@zod");
 
@@ -145,12 +155,12 @@ export function renderProjectionDecl(
   const sections: Code[] = [
     ...(includeViewDecl
       ? [renderExistingViewDecl(allFields, viewName, `${camelName}View`, {
-          dialect, columnNamingStrategy, timestampMode, voModule,
+          dialect, columnNamingStrategy, timestampMode, voRef,
         })]
       : []),
     code`
 export const ${projName}Schema = ${renderViewReadZodObject(allFields, {
-  dialect, columnNamingStrategy, timestampMode, voModule,
+  dialect, columnNamingStrategy, timestampMode, voRef,
 })};
 `,
     code`