@metaobjectsdev/codegen-ts 0.15.19-rc.1 → 0.15.20

package/src/generators/template-doc-builder.ts

@@ -114,10 +114,12 @@ export function buildTemplateDocData(
   const kind: "document" | "email" = isEmail ? TEMPLATE_KIND_EMAIL : TEMPLATE_KIND_DOCUMENT;
 
   const payloadRefRaw = template.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-  const payloadName =
-    typeof payloadRefRaw === "string" && payloadRefRaw.length > 0
-      ? stripPackage(payloadRefRaw)
-      : "unknown";
+  // ADR-0042: keep the FULL ref for RESOLUTION (an FQN @payloadRef to another
+  // package must resolve exactly — the old bare-tail fallback that used to find
+  // it is gone); strip to the bare name only for DISPLAY labels.
+  const payloadRefFull =
+    typeof payloadRefRaw === "string" && payloadRefRaw.length > 0 ? payloadRefRaw : "unknown";
+  const payloadName = payloadRefFull !== "unknown" ? stripPackage(payloadRefFull) : "unknown";
 
   const requiredTags = attrStringList(template.attr(TEMPLATE_ATTR_REQUIRED_TAGS));
   const maxChars = readMaxChars(template.attr(TEMPLATE_ATTR_MAX_CHARS));
@@ -188,6 +190,7 @@ export function buildTemplateDocData(
       layout,
       template,
       payloadName,
+      payloadRefFull,
       // Document: the single @textRef (unlabeled). Email: one labeled part each.
       refs:
         parts !== undefined
@@ -221,7 +224,11 @@ interface BuildSectionArgs {
   /** The `template.output` node whose page is being built — the FROM page for
    *  every relative href on this section. */
   template: MetaData;
+  /** Bare payload name — DISPLAY only (labels, owner names). */
   payloadName: string;
+  /** Full @payloadRef (FQN for a cross-package payload, bare for same-package) —
+   *  used for RESOLUTION so a cross-package payload tree still resolves (ADR-0042). */
+  payloadRefFull: string;
   refs: SourceRefSpec[];
 }
 
@@ -236,8 +243,15 @@ interface BuildSectionArgs {
  * resolved, so the caller omits the section entirely.
  */
 function buildTemplateSourceSection(args: BuildSectionArgs): string | undefined {
-  const { provider, root, layout, template, payloadName, refs } = args;
-  const tree: AnnotatePayloadField[] = buildEnrichedPayloadTree(root, payloadName);
+  const { provider, root, layout, template, payloadName, payloadRefFull, refs } = args;
+  // ADR-0042: resolve the payload tree from the FULL ref — an FQN cross-package
+  // @payloadRef resolves exactly; a bare same-package ref resolves in the
+  // template's package.
+  const tree: AnnotatePayloadField[] = buildEnrichedPayloadTree(
+    root,
+    payloadRefFull,
+    template.package ?? template.fileDefaultPackage ?? "",
+  );
   const fromNode = docPageNode(template);
 
   // Layout-aware field href: route through the SAME docPageHref the Payload

package/src/generators/template-payload-tree.ts

@@ -21,23 +21,21 @@
 import {
   type MetaObject,
   type MetaRoot,
-  TYPE_OBJECT,
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_OBJECT_REF,
   stripPackage,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import { isFieldRequired, neutralTypeStr } from "./docs-data-builder.js";
 import type { AnnotatePayloadField } from "./template-source-annotate.js";
 
-// ADR-0041: FQN-exact object resolution — a "::"-qualified @objectRef binds the exact
+// ADR-0041/0042: FQN-exact object resolution — a "::"-qualified @objectRef binds the exact
 // package (never a bare-tail fallback), so a same-named object.value in another package
-// can't be wrongly bound (which would attach the wrong owner/type/link to a doc node).
+// can't be wrongly bound (which would attach the wrong owner/type/link to a doc node); a
+// bare ref binds the referrer's package FIRST, else a root-level object.
 // Mirrors render-helper.ts's findObject + the CLI payload-field-tree resolver.
-function findObject(root: MetaRoot, ref: string): MetaObject | undefined {
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, ref)) as
-    | MetaObject
-    | undefined;
+function findObject(root: MetaRoot, ref: string, referrerPkg = ""): MetaObject | undefined {
+  return resolveObjectRef(root, ref, referrerPkg).node as MetaObject | undefined;
 }
 
 /**
@@ -54,12 +52,17 @@ function findObject(root: MetaRoot, ref: string): MetaObject | undefined {
 export function buildEnrichedPayloadTree(
   root: MetaRoot,
   voName: string,
+  referrerPkg = "",
   seen: ReadonlySet<string> = new Set(),
 ): AnnotatePayloadField[] {
   if (seen.has(voName)) return [];
-  const vo: MetaObject | undefined = findObject(root, voName);
+  const vo: MetaObject | undefined = findObject(root, voName, referrerPkg);
   if (vo === undefined) return [];
   const owner = stripPackage(vo.name);
+  // ADR-0042: a nested @objectRef resolves in the FIELD's own declaring package
+  // (fallback below), which differs from this VO's when the field is inherited via
+  // extends from an abstract VO in another package (the bare ref was authored there).
+  const voPkg = vo.package ?? vo.fileDefaultPackage ?? "";
   const nextSeen = new Set(seen).add(voName);
   const out: AnnotatePayloadField[] = [];
   for (const f of vo.fields()) {
@@ -74,8 +77,10 @@ export function buildEnrichedPayloadTree(
       if (typeof ref === "string" && ref.length > 0) {
         // Owner switches to the nested VO for its fields (the recursion below
         // re-derives `owner` from the resolved VO's own name). Pass the FULL ref
-        // (not stripPackage) so findObject resolves it FQN-exact (ADR-0041).
-        node.fields = buildEnrichedPayloadTree(root, ref, nextSeen);
+        // (not stripPackage), resolved package-locally against the FIELD's declaring
+        // package (ADR-0042 — the bare ref was authored there, not on the concrete VO).
+        const fieldPkg = f.parent?.package ?? f.parent?.fileDefaultPackage ?? voPkg;
+        node.fields = buildEnrichedPayloadTree(root, ref, fieldPkg, nextSeen);
       }
     }
     out.push(node);

package/src/generators/trace-helper-file.ts

@@ -122,8 +122,13 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
         : "Format.JSON";
 
       // Collect VO names for interface emission (dedupe via batch emitter).
-      // Both refs are guaranteed strings by the guards above.
-      const interfaces = generatePayloadInterfacesBatch(ctx.loadedRoot, [payloadRef, responseRef]);
+      // Both refs are guaranteed strings by the guards above. ADR-0042: a bare
+      // ref resolves in the prompt's package.
+      const interfaces = generatePayloadInterfacesBatch(
+        ctx.loadedRoot,
+        [payloadRef, responseRef],
+        prompt.package ?? prompt.fileDefaultPackage ?? "",
+      );
 
       const requestType = payloadRef;
 

package/src/payload-codegen.ts

@@ -13,7 +13,6 @@
 import {
   type MetaData,
   type MetaField,
-  TYPE_OBJECT,
   TYPE_FIELD,
   TYPE_TEMPLATE,
   FIELD_SUBTYPE_OBJECT,
@@ -23,7 +22,7 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
-  refMatchesObject,
+  resolveObjectRef,
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
@@ -47,10 +46,9 @@ const SCALAR_TS: Record<string, string> = {
 };
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  // FR-032 — @payloadRef/@responseRef are FQN after the desugar/sweep; match on
-  // the effective FQN resolution key (with bare back-compat).
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// 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 {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 /**
@@ -106,12 +104,18 @@ function isFieldRequired(field: MetaData): boolean {
 function emitInterface(
   root: MetaData,
   voRef: string,
+  referrerPkg: string,
   emitted: Set<string>,
   out: string[],
   enumAliases: Set<string>,
 ): void {
-  const vo = findObject(root, voRef);
+  const vo = findObject(root, voRef, referrerPkg);
   if (!vo) return;
+  // ADR-0042: a nested @objectRef resolves in the FIELD's OWN declaring package —
+  // which may differ from this resolved VO's package when the field is inherited
+  // via extends from an abstract VO in another package (the bare ref was authored
+  // there). Fall back to this VO's package when a field has no parent package.
+  const voPkg = vo.package ?? vo.fileDefaultPackage ?? "";
   // FR-032/ADR-0041 — voRef may arrive as an FQN (a nested @objectRef); the emitted
   // interface NAME must be the bare, TS-valid name. Dedupe on the bare name too, so a
   // VO reached once by bare name and once by FQN still emits exactly once.
@@ -120,7 +124,7 @@ function emitInterface(
   emitted.add(voName);
   const aliasLines: string[] = [];
   const lines: string[] = [`export interface ${voName} {`];
-  const refs: string[] = [];
+  const refs: { ref: string; pkg: string }[] = [];
   for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
     const { type, refVo, enumAlias } = fieldTsType(f, voName);
     // Hoist the enum union alias above the interface, deduped across the whole
@@ -138,18 +142,21 @@ function emitInterface(
     const tsType = isRequired ? type : `${type} | null`;
     const optional = isRequired ? "" : "?";
     lines.push(`  ${f.name}${optional}: ${tsType};`);
-    if (refVo) refs.push(refVo);
+    // The nested ref resolves in the FIELD's declaring package (ADR-0042), not the
+    // resolved VO's — they differ when `f` is inherited from an abstract VO elsewhere.
+    if (refVo) refs.push({ ref: refVo, pkg: f.parent?.package ?? f.parent?.fileDefaultPackage ?? voPkg });
   }
   lines.push("}");
   const block = aliasLines.length > 0 ? `${aliasLines.join("\n")}\n${lines.join("\n")}` : lines.join("\n");
   out.push(block);
-  for (const r of refs) emitInterface(root, r, emitted, out, enumAliases);
+  for (const r of refs) emitInterface(root, r.ref, r.pkg, emitted, out, enumAliases);
 }
 
-/** Emit the payload `interface` (+ nested element interfaces) for an object.value view-object. */
-export function generatePayloadInterfaces(root: MetaData, voName: string): string {
+/** Emit the payload `interface` (+ nested element interfaces) for an object.value view-object.
+ *  `referrerPkg` (ADR-0042) is the package a bare `voName` resolves in; pass an FQN and it is ignored. */
+export function generatePayloadInterfaces(root: MetaData, voName: string, referrerPkg = ""): string {
   const out: string[] = [];
-  emitInterface(root, voName, new Set<string>(), out, new Set<string>());
+  emitInterface(root, voName, referrerPkg, new Set<string>(), out, new Set<string>());
   return out.join("\n\n") + "\n";
 }
 
@@ -160,13 +167,17 @@ export function generatePayloadInterfaces(root: MetaData, voName: string): strin
  *
  * Returns the empty string when `voNames` is empty.
  */
-export function generatePayloadInterfacesBatch(root: MetaData, voNames: readonly string[]): string {
+export function generatePayloadInterfacesBatch(
+  root: MetaData,
+  voNames: readonly string[],
+  referrerPkg = "",
+): string {
   if (voNames.length === 0) return "";
   const out: string[] = [];
   const emitted = new Set<string>();
   const enumAliases = new Set<string>();
   for (const name of voNames) {
-    emitInterface(root, name, emitted, out, enumAliases);
+    emitInterface(root, name, referrerPkg, emitted, out, enumAliases);
   }
   return out.length === 0 ? "" : out.join("\n\n") + "\n";
 }

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

@@ -21,30 +21,27 @@
 
 import {
   type MetaData,
-  TYPE_OBJECT,
   TYPE_FIELD,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
-  PACKAGE_SEPARATOR,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.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.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// 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 {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
   const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
-  const direct = findObject(root, ref);
-  if (direct !== undefined) return direct;
-  const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
-  if (sep >= 0) return findObject(root, ref.slice(sep + PACKAGE_SEPARATOR.length));
-  return undefined;
+  // ADR-0042: resolve as authored — a bare ref binds the declaring VO's package,
+  // an FQN exactly; NO bare-tail fallback (never bind a same-named VO elsewhere).
+  return findObject(root, ref, field.parent?.package ?? field.parent?.fileDefaultPackage ?? "");
 }
 
 /** True iff the field is a nested object reference (field.object — distinct from the

package/src/templates/extractor.ts

@@ -23,7 +23,6 @@
 import {
   type MetaData,
   type MetaField,
-  TYPE_OBJECT,
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_OUTPUT,
   FIELD_SUBTYPE_OBJECT,
@@ -32,8 +31,7 @@ import {
   FIELD_ATTR_REQUIRED,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
-  PACKAGE_SEPARATOR,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray } from "./fr010-field-mapping.js";
 import { mirrorName } from "./extract-delegate-emitter.js";
@@ -41,8 +39,9 @@ import { enumUnionAliasName } from "./inferred-types.js";
 import { enumValues } from "../enum-meta.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.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// 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 {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
@@ -54,11 +53,9 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
   const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
-  const direct = findObject(root, ref);
-  if (direct !== undefined) return direct;
-  const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
-  if (sep >= 0) return findObject(root, ref.slice(sep + PACKAGE_SEPARATOR.length));
-  return undefined;
+  // ADR-0042: resolve as authored — a bare ref binds the declaring VO's package,
+  // an FQN exactly; NO bare-tail fallback (never bind a same-named VO elsewhere).
+  return findObject(root, ref, field.parent?.package ?? field.parent?.fileDefaultPackage ?? "");
 }
 
 function isObjectField(field: MetaData): boolean {
@@ -295,7 +292,8 @@ export function renderExtractor(root: MetaData, templateName: string): string {
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
-  const vo = findObject(root, payloadRef);
+  // ADR-0042: a bare @payloadRef resolves in the template's package.
+  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
   if (!vo) {
     throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
   }

package/src/templates/output-parser.ts

@@ -11,7 +11,6 @@
 
 import {
   type MetaData,
-  TYPE_OBJECT,
   TYPE_FIELD,
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_OUTPUT,
@@ -19,7 +18,7 @@ import {
   FIELD_ATTR_OBJECT_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import {
   nestedMirrorInterfaces,
@@ -43,10 +42,9 @@ const SCALAR_ZOD: Record<string, string> = {
 };
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  // FR-032 — @payloadRef is FQN after the desugar/sweep; match on the effective
-  // FQN resolution key (with bare back-compat).
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// 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 {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
@@ -67,7 +65,8 @@ function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, de
       // Cycle guard — emit unknown for self-references (rare; lazy schemas not in scope for v1).
       base = "z.unknown()";
     } else {
-      const inner = findObject(root, refName);
+      // ADR-0042: a bare nested @objectRef resolves in the declaring VO's package.
+      const inner = findObject(root, refName, field.parent?.package ?? field.parent?.fileDefaultPackage ?? "");
       base = inner ? renderObjectSchema(inner, root, new Set(seen).add(refName), depth + 1) : "z.unknown()";
     }
   } else {
@@ -107,7 +106,8 @@ export function renderOutputParser(root: MetaData, templateName: string): string
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
-  const vo = findObject(root, payloadRef);
+  // ADR-0042: a bare @payloadRef resolves in the template's package.
+  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
   if (!vo) {
     throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
   }

package/src/templates/output-prompt.ts

@@ -12,18 +12,18 @@
 
 import {
   type MetaData,
-  TYPE_OBJECT,
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import { specLiteral } from "./output-format-spec-emitter.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.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// 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 {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
@@ -59,7 +59,8 @@ export function renderOutputPrompt(root: MetaData, templateName: string): string
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
-  const vo = findObject(root, payloadRef);
+  // ADR-0042: a bare @payloadRef resolves in the template's package.
+  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
   if (!vo) {
     throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
   }

package/src/templates/render-helper.ts

@@ -27,7 +27,6 @@
 
 import {
   type MetaData,
-  TYPE_OBJECT,
   TYPE_FIELD,
   TYPE_TEMPLATE,
   FIELD_SUBTYPE_OBJECT,
@@ -43,7 +42,7 @@ import {
   TEMPLATE_ATTR_SUBJECT_REF,
   TEMPLATE_ATTR_HTML_BODY_REF,
   TEMPLATE_ATTR_TEXT_BODY_REF,
-  refMatchesObject,
+  resolveObjectRef,
 } from "@metaobjectsdev/metadata";
 import {
   verify,
@@ -54,8 +53,9 @@ import {
 } from "@metaobjectsdev/render";
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
-function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+// ADR-0042: package-local — resolveObjectRef binds a bare @objectRef in `referrerPkg` first (else root-level), an FQN exactly.
+function findObject(root: MetaData, name: string, referrerPkg: string): MetaData | undefined {
+  return resolveObjectRef(root, name, referrerPkg).node;
 }
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
@@ -74,18 +74,24 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
 function derivePayloadFieldTree(
   root: MetaData,
   voName: string,
+  referrerPkg: string,
   seen: ReadonlySet<string> = new Set(),
 ): PayloadField[] {
   if (seen.has(voName)) return [];
-  const vo = findObject(root, voName);
+  const vo = findObject(root, voName, referrerPkg);
   if (!vo) return [];
+  // ADR-0042: a nested @objectRef resolves in the FIELD's own declaring package
+  // (fallback below), which differs from this VO's when the field is inherited via
+  // extends from an abstract VO elsewhere.
+  const voPkg = vo.package ?? vo.fileDefaultPackage ?? "";
   const nextSeen = new Set(seen).add(voName);
   const fields: PayloadField[] = [];
   for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
     if (f.subType === FIELD_SUBTYPE_OBJECT) {
       const ref = f.attr(FIELD_ATTR_OBJECT_REF);
       if (typeof ref === "string") {
-        fields.push({ name: f.name, fields: derivePayloadFieldTree(root, ref, nextSeen) });
+        const fieldPkg = f.parent?.package ?? f.parent?.fileDefaultPackage ?? voPkg;
+        fields.push({ name: f.name, fields: derivePayloadFieldTree(root, ref, fieldPkg, nextSeen) });
         continue;
       }
     }
@@ -157,14 +163,16 @@ export function renderRenderHelper(
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
-  const vo = findObject(root, payloadRef);
+  // ADR-0042: a bare @payloadRef resolves in the template's package.
+  const tmplPkg = tmpl.package ?? tmpl.fileDefaultPackage ?? "";
+  const vo = findObject(root, payloadRef, tmplPkg);
   if (!vo) {
     throw new Error(
       `template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`,
     );
   }
 
-  const fields = derivePayloadFieldTree(root, payloadRef);
+  const fields = derivePayloadFieldTree(root, payloadRef, tmplPkg);
   const ft = fieldTreeLiteral(fields);
   const fnName = `render${templateName}`;