fix(codegen-ts): extractor/render-helper import the payload VO from its real module (not the non-existent ./payloads.js)

The standalone extractor() + renderHelper() generators emitted
`import type { <PayloadVO(s)> } from "./payloads.js"`, but NO TS generator
emits payloads.ts — so a real `meta gen` run produced *.extractor.ts /
*.render.ts that failed to compile (TS2307). The payload VO interface and its
enum union-aliases actually live in the VO's OWN generated entity module
(entityFile emits <VO>.ts exporting `interface <VO>` + `type <Owner><Field>`),
which is exactly where api-docs already documents the type.

Fix:
- render-helper: import the payload interface from `./<payloadRef>.js`.
- extractor: group the reachable payload types BY the entity module that
  exports them (VO interface + its own enum aliases → `./<VO>.js`; each nested
  VO → its own module), replacing the single dangling `./payloads.js` import.
- Reconcile the mirror→strict mapper to the entity-module interface's optional
  shape: optional fields are `f?: T` (= T | undefined, never T | null) there,
  so an absent optional now maps to `?? undefined` (was `?? null`, which
  matched payload-codegen's `T | null` shape and was TS2322 against the real
  module). This was a latent skew the dead import had masked.

Proof: new golden/extractor-render-payload-imports.test.ts runs the REAL
generators (entityFile + outputParser + extractor + renderHelper) into a temp
dir and tsc-compiles the emitted files against the REAL VO modules — the
payload import resolves (no TS2307) and the types are found. The existing
extractor compile gate now compiles against the real per-VO modules instead of
a hand-written payloads.ts. promptRender's self-contained inline-interface flow
(which strips the import) is unchanged. Full codegen-ts suite green (696 pass).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/codegen-ts/src/templates/extractor.ts

@@ -64,9 +64,9 @@ function isObjectField(field: MetaData): boolean {
 
 /**
  * The union-alias type name for a `field.enum` with effective `@values`, or undefined when the
- * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the payload
- * emitter (`payload-codegen.ts`) types the field as — so the cast target resolves to the exact
- * alias exported from `payloads.ts`. `ownerName` is the owning value-object's interface name.
+ * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the entity
+ * inferred-types emitter types the field as — so the cast target resolves to the exact alias
+ * exported from the owning VO's entity module. `ownerName` is the owning value-object's interface name.
  */
 function enumAlias(field: MetaData, ownerName: string): string | undefined {
   if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
@@ -76,11 +76,12 @@ function enumAlias(field: MetaData, ownerName: string): string | undefined {
 }
 
 /**
- * True iff the field is required IN THE STRICT PAYLOAD TYPE. This MUST match
- * payload-codegen.ts's `isFieldRequired` predicate EXACTLY (boolean `true` only) — the payload
- * interface decides `T` vs `T | null` by that predicate, and the mapper's optionality assumption
- * (`m.f!` vs `m.f ?? null`) has to agree with the type it is constructing. A `@required:"true"`
- * string field is therefore `T | null` in the payload AND optional here (no skew).
+ * True iff the field is required IN THE STRICT PAYLOAD TYPE. The strict payload IS the VO's own
+ * generated entity-module interface (`renderValueObjectInterface`), which types a required field
+ * `f: T` and an optional one `f?: T` (i.e. `T | undefined` — NOT `T | null`). So the mapper's
+ * optionality assumption (`m.f!` vs `m.f ?? undefined`) has to agree with THAT interface, and an
+ * absent optional maps to `undefined`, never `null`. This predicate matches the interface's
+ * required test (boolean `true` only) so the two never skew.
  */
 function isFieldRequired(field: MetaData): boolean {
   return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
@@ -93,8 +94,10 @@ function mapperName(vo: MetaData): string {
 
 /**
  * The mapper-body initializer expression for one field, reading mirror member `m.<name>` and
- * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? null`).
- * Nested single/array objects recurse into their toStrict<Type> mapper, guarding null when optional.
+ * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? undefined`).
+ * The strict payload is the VO's generated entity-module interface, whose optional fields are
+ * `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 {
   const name = field.name;
@@ -104,25 +107,25 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
     const target = refVo(field, root);
     if (target === undefined) {
       // Unresolved @objectRef — the payload type would be `unknown`; pass through as-is.
-      return required ? `m.${name}!` : `m.${name} ?? null`;
+      return required ? `m.${name}!` : `m.${name} ?? undefined`;
     }
     const fn = mapperName(target);
     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).
       if (required) return `m.${name}!.map((e) => ${fn}(e!))`;
-      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : null`;
+      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : undefined`;
     }
     // Single nested object.
     if (required) return `${fn}(m.${name}!)`;
-    return `m.${name} ? ${fn}(m.${name}) : null`;
+    return `m.${name} ? ${fn}(m.${name}) : undefined`;
   }
 
   // Scalar ARRAY (e.g. `field.string` with isArray): the mirror types it `(T | null)[] | null`
-  // but the strict payload types it `T[]` (required) / `T[] | null` (optional). A bare `m.f!`
+  // but the strict payload types it `T[]` (required) / `T[]?` (optional). A bare `m.f!`
   // would leave the element type `T | null`, a `tsc --strict` TS2322 error. Filter out null
   // elements so the element type narrows to non-null (consistent with the lost-element DROP policy
-  // already used for required arrays-of-objects above).
+  // already used for required arrays-of-objects above). An absent optional array maps to `undefined`.
   //
   // ENUM arrays: the mirror element is a plain `string`, but the strict payload types it as the
   // closed `<Alias>[]` union. The null-filter alone narrows to `string[]`, not `<Alias>[]` — a
@@ -136,23 +139,23 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
       return alias !== undefined ? `(${filtered}) as ${alias}[]` : filtered;
     }
     const filtered = `m.${name}.filter((x): x is NonNullable<typeof x> => x != null)`;
-    const guarded = `m.${name} == null ? null : ${filtered}`;
+    const guarded = `m.${name} == null ? undefined : ${filtered}`;
     return alias !== undefined
-      ? `m.${name} == null ? null : (${filtered}) as ${alias}[]`
+      ? `m.${name} == null ? undefined : (${filtered}) as ${alias}[]`
       : guarded;
   }
 
   // Scalar / enum (single): the strict payload's optionality decides the shape.
-  // Required → non-null assertion; optional → `?? null` (matches the payload's `f?: T | null`).
+  // Required → non-null assertion; optional → `?? undefined` (matches the entity-module `f?: T`).
   //
   // ENUM scalar: the mirror member is a plain `string`, but the strict payload types it as the
   // closed `<Alias>` union — assigning `string` into `<Alias>` is a `tsc --strict` TS2322 error.
   // So the value is CAST to `<Alias>`. Sound for the same reason as enum arrays above: the engine
   // already validated membership (or extract throws on a lost required field).
   if (alias !== undefined) {
-    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? null) as ${alias} | null`;
+    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? undefined) as ${alias} | undefined`;
   }
-  return required ? `m.${name}!` : `m.${name} ?? null`;
+  return required ? `m.${name}!` : `m.${name} ?? undefined`;
 }
 
 /**
@@ -202,32 +205,52 @@ function emitMapper(
 }
 
 /**
- * Collect the strict payload-interface names reachable from `vo` (for the type-only import),
- * PLUS every enum union-alias reachable from those VOs. Both are exported from `payloads.ts`
- * (the alias is hoisted above the interface there), so the extractor's `as <Alias>` casts need
- * the alias names imported alongside the interface names. Deduped, in discovery order.
+ * One payload-type import group: the strict types (VO interface + its own enum
+ * union-aliases) imported from a single VO entity module.
  */
-function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
-  const order: string[] = [];
-  const seen = new Set<string>();
+interface PayloadImportGroup {
+  /** The VO whose entity module exports these types (`./<module>.js`). */
+  module: string;
+  /** The strict type names exported by that module, in discovery order. */
+  types: string[];
+}
+
+/**
+ * Group the strict payload types reachable from `vo` BY THE ENTITY MODULE THAT EXPORTS THEM.
+ *
+ * Each value-object gets its own generated entity module (`entityFile()` emits `<VO>.ts` exporting
+ * `export interface <VO>`), and `renderEnumTypeAliases` hoists every `field.enum` union-alias INTO
+ * the OWNING VO's module (`export type <Owner><Field> = ...` co-located with the interface). So a
+ * 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[] {
+  const groups: PayloadImportGroup[] = [];
+  const seenVo = new Set<string>();
+  const seenAlias = new Set<string>();
   const visit = (cur: MetaData) => {
-    if (seen.has(cur.name)) return;
-    seen.add(cur.name);
-    order.push(cur.name);
+    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];
     for (const f of fields(cur)) {
       const alias = enumAlias(f, cur.name);
-      if (alias !== undefined && !seen.has(alias)) {
-        seen.add(alias);
-        order.push(alias);
+      if (alias !== undefined && !seenAlias.has(alias)) {
+        seenAlias.add(alias);
+        types.push(alias);
       }
+    }
+    groups.push({ module: cur.name, types });
+    // Recurse into nested object refs (their interfaces live in their own modules).
+    for (const f of fields(cur)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);
         if (target !== undefined) visit(target);
       }
     }
   };
   visit(vo);
-  return order;
+  return groups;
 }
 
 /** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
@@ -286,10 +309,16 @@ export function renderExtractor(root: MetaData, templateName: string): string {
   const extractName = `extract${templateName}`;
   const rootMapper = mapperName(vo);
 
-  const payloadTypes = reachablePayloadTypes(vo, root);
+  const payloadGroups = reachablePayloadGroups(vo, root);
   const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror);
   const mappers = emitMappers(vo, root, rootMirror);
 
+  // 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`.
+  const payloadImports = payloadGroups
+    .map((g) => `import type { ${g.types.join(", ")} } from "./${g.module}.js";`)
+    .join("\n");
+
   const lostMsg =
     `${extractName}: lost required field(s): `;
 
@@ -301,7 +330,7 @@ export function renderExtractor(root: MetaData, templateName: string): string {
     `// mapping the all-nullable mirror onto the strict payload. No registry / binding / factory.\n` +
     `\n` +
     `import {\n  ${extractLenientWithName},\n  type ${mirrorTypes.join(",\n  type ")},\n} from "./${templateName}.output.js";\n` +
-    `import type { ${payloadTypes.join(", ")} } from "./payloads.js";\n` +
+    `${payloadImports}\n` +
     `import type { MetaRoot } from "@metaobjectsdev/metadata";\n` +
     `import type { ExtractionResult } from "@metaobjectsdev/render";\n` +
     `\n` +

server/typescript/packages/codegen-ts/src/templates/render-helper.ts

@@ -192,7 +192,7 @@ export function renderRenderHelper(
 
     return `import { render } from "@metaobjectsdev/render";
 import type { Provider, EmailDocument } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} email (subject + html body${typeof textBodyRef === "string" ? " + text body" : ""}) from a
@@ -230,7 +230,7 @@ export function ${fnName}(payload: ${payloadRef}, provider: Provider): EmailDocu
 
   return `import { render } from "@metaobjectsdev/render";
 import type { Provider } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} document from a typed ${payloadRef} payload. Wraps the

server/typescript/packages/codegen-ts/test/extractor-codegen.test.ts

@@ -18,6 +18,41 @@ import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
 import { renderOutputParser } from "../src/templates/output-parser.js";
 import { renderExtractor } from "../src/templates/extractor.js";
 import { generatePayloadInterfaces } from "../src/payload-codegen.js";
+import { entityFile } from "../src/generators/index.js";
+import { makeRenderContext } from "../src/render-context.js";
+import { buildPkMap } from "../src/pk-resolver.js";
+import { buildRelationMap } from "../src/relation-resolver.js";
+import type { GenContext } from "../src/generator.js";
+
+// Emit the REAL per-VO entity modules (`<VO>.ts` exporting `interface <VO>` +
+// its enum union-aliases) the same way `meta gen` does, so the generated
+// extractor's `from "./<VO>.js"` payload imports RESOLVE against the modules
+// that actually exist (no hand-written `payloads.ts` that no generator emits).
+async function writeEntityModules(
+  dir: string,
+  root: Awaited<ReturnType<typeof loadRoot>>,
+): Promise<void> {
+  const renderContext = makeRenderContext({
+    dialect: "sqlite",
+    loadedRoot: root,
+    outDir: "/tmp",
+    dbImport: "~/db",
+    pkMap: buildPkMap(root),
+    relationMap: buildRelationMap(root),
+  });
+  const ctx: GenContext = {
+    entities: root.objects(),
+    loadedRoot: root,
+    matches: () => true,
+    projectRoot: "/tmp",
+    config: { outDir: "/tmp", extStyle: "none", dbImport: "~/db", dialect: "sqlite" } as never,
+    renderContext,
+    warn: () => {},
+  };
+  for (const f of await entityFile().generate(ctx)) {
+    writeFileSync(join(dir, f.path), f.content);
+  }
+}
 
 // ---------------------------------------------------------------------------
 // tsc --strict compile gate (mirrors fr004-verify-demo.test.ts's `compile()`).
@@ -166,12 +201,13 @@ describe("Extractor codegen — source shape", () => {
     // NOT a bare `m.tags!` / `m.flags!` (which would be a tsc --strict TS2322 error).
     expect(src).toContain("(m.tags ?? []).filter((x): x is NonNullable<typeof x> => x != null)");
     expect(src).toContain(
-      "m.flags == null ? null : m.flags.filter((x): x is NonNullable<typeof x> => x != null)",
+      "m.flags == null ? undefined : m.flags.filter((x): x is NonNullable<typeof x> => x != null)",
     );
     expect(src).not.toContain("m.tags!");
     expect(src).not.toContain("m.flags!");
-    // optional single nested object → null-guarded recurse into its mapper
-    expect(src).toContain("m.shipTo ? toStrictCustomer(m.shipTo) : null");
+    // optional single nested object → undefined-guarded recurse into its mapper
+    // (the strict entity-module interface types optionals `?: T` = `T | undefined`).
+    expect(src).toContain("m.shipTo ? toStrictCustomer(m.shipTo) : undefined");
   });
 
   test("payload typing: field.enum is a value-constrained union alias (not unknown), single + array", async () => {
@@ -233,7 +269,6 @@ describe("Extractor codegen — source shape", () => {
 
   test("tsc --strict gate: emitted payload + parser + extractor type-check with ZERO diagnostics", async () => {
     const root = await loadRoot(MODEL);
-    const payloadSrc = generatePayloadInterfaces(root, "Order");
     const parserSrc = renderOutputParser(root, "OrderOut");
     const extractorSrc = renderExtractor(root, "OrderOut");
 
@@ -246,13 +281,16 @@ describe("Extractor codegen — source shape", () => {
 
     const dir = mkdtempSync(join(import.meta.dir, "extractor-tsc-"));
     TEMP_DIRS.push(dir);
-    writeFileSync(join(dir, "payloads.ts"), payloadSrc);
+    // The REAL per-VO entity modules the extractor imports its payload types from.
+    await writeEntityModules(dir, root);
     writeFileSync(join(dir, "OrderOut.output.ts"), parserSrc);
     writeFileSync(join(dir, "OrderOut.extractor.ts"), extractorSrc);
     writeFileSync(join(dir, "engine.d.ts"), ENGINE_STUBS);
 
     const diagnostics = compile(dir, [
-      "payloads.ts",
+      "Order.ts",
+      "Customer.ts",
+      "Line.ts",
       "OrderOut.output.ts",
       "OrderOut.extractor.ts",
       "engine.d.ts",
@@ -266,13 +304,13 @@ describe("Extractor codegen — source shape", () => {
 describe("Extractor codegen — import-and-RUN proof (bun dynamic import)", () => {
   test("extractOrder() extracts dirty JSON into the strict payload; missing-required throws; extract re-exposed", async () => {
     const root = await loadRoot(MODEL);
-    const payloadSrc = generatePayloadInterfaces(root, "Order");
     const parserSrc = renderOutputParser(root, "OrderOut");
     const extractorSrc = renderExtractor(root, "OrderOut");
 
     const dir = mkdtempSync(join(import.meta.dir, "extractor-emit-"));
     TEMP_DIRS.push(dir);
-    writeFileSync(join(dir, "payloads.ts"), payloadSrc);
+    // The extractor's payload imports are `import type` (erased at runtime), so the
+    // VO modules need not be loaded here; the run-proof exercises the emitted logic.
     writeFileSync(join(dir, "OrderOut.output.ts"), parserSrc);
     writeFileSync(join(dir, "OrderOut.extractor.ts"), extractorSrc);
 
@@ -303,22 +341,23 @@ describe("Extractor codegen — import-and-RUN proof (bun dynamic import)", () =
     expect(order.priority).toBe("HIGH");
     // enum array: null-filtered, typed as OrderLabels[].
     expect(order.labels).toEqual(["A", "B"]);
-    // optional single nested object `shipTo` ABSENT in this input → the `m.shipTo ? toStrictCustomer(...) : null`
-    // branch produces null at runtime (not undefined, not a partial object).
-    expect(order.shipTo).toBeNull();
+    // optional single nested object `shipTo` ABSENT in this input → the `m.shipTo ? toStrictCustomer(...) : undefined`
+    // branch produces undefined at runtime (matches the strict `shipTo?: Customer` entity-module
+    // interface optionality — not a partial object).
+    expect(order.shipTo).toBeUndefined();
 
-    // optional single nested object PRESENT → the null-guard recurses into toStrictCustomer and populates.
+    // optional single nested object PRESENT → the guard recurses into toStrictCustomer and populates.
     const withShipTo =
       '{ "customer": { "name": "Ada" }, "lines": [ { "sku": "A", "qty": 2 } ], "tags": ["x"], "priority": "LOW", "labels": ["A"], "shipTo": { "name": "Grace" } }';
     const shipped = ex.extractOrderOut(root, withShipTo);
-    expect(shipped.shipTo).not.toBeNull();
+    expect(shipped.shipTo).not.toBeUndefined();
     expect(shipped.shipTo.name).toBe("Grace");
-    // and when shipTo is genuinely absent on a separate clean input, it is null (re-confirm the branch)
+    // and when shipTo is genuinely absent on a separate clean input, it is undefined (re-confirm the branch)
     const noShipTo = ex.extractOrderOut(
       root,
       '{ "customer": { "name": "Ada" }, "lines": [ { "sku": "A", "qty": 2 } ], "tags": ["x"], "priority": "LOW", "labels": ["A"] }',
     );
-    expect(noShipTo.shipTo).toBeNull();
+    expect(noShipTo.shipTo).toBeUndefined();
 
     // missing required `customer` → throws
     expect(() => ex.extractOrderOut(root, '{ "lines": [] }')).toThrow();