@metaobjectsdev/codegen-ts 0.9.0 → 0.11.0-rc.1

package/src/templates/docs-file.ts

@@ -22,15 +22,11 @@ export interface DocsRenderOpts {
   dialect: Dialect;
   columnNamingStrategy?: ColumnNamingStrategy;
   loadedRoot: MetaRoot;
-  /** Names of generators present in the pipeline — drives the "Generated code"
-   *  section. Always includes "entity-file" implicitly. Recognized names:
-   *  "queries-file", "routes-file", "routes-file-hono". */
-  generatorNames?: ReadonlySet<string>;
 }
 
 /** Backward-compatible entry point: builds the EntityDocData payload and
- *  renders it via the framework template. Byte-identical to the hand-coded
- *  rc.11 output (gated by `docs-file-conformance.test.ts`). */
+ *  renders it via the framework template. Output is gated by
+ *  `docs-file-conformance.test.ts`. */
 export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string {
   const data = buildEntityDocData(entity, {
     dialect: opts.dialect,
@@ -38,9 +34,6 @@ export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string
       ? { columnNamingStrategy: opts.columnNamingStrategy }
       : {}),
     loadedRoot: opts.loadedRoot,
-    ...(opts.generatorNames !== undefined
-      ? { generatorNames: opts.generatorNames }
-      : {}),
   });
   return render({
     ref: "docs/entity-page.md",

package/src/templates/drizzle-schema.ts

@@ -3,7 +3,7 @@
 // plus the relations() block auto-emitted at the end.
 
 import { code, imp, joinCode, type Code } from "ts-poet";
-import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
 import {
   IDENTITY_SUBTYPE_SECONDARY, FIELD_SUBTYPE_LONG,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION, IDENTITY_ATTR_UNIQUE,
@@ -11,11 +11,12 @@ import {
   FIELD_ATTR_AUTO_SET,
 } from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
-import { crossEntitySpecifier } from "../import-path.js";
+import { crossEntitySpecifier, valueObjectModuleSpecifier } from "../import-path.js";
 import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
-import { tableNameFromEntity, variableNameFromEntity, columnNameFromField } from "../naming.js";
+import { tableNameFromEntity, columnNameFromField } from "../naming.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { collectTphSubtypeFields } from "./tph-discriminator.js";
 
 /**
  * Render the Drizzle table definition for one entity, including:
@@ -32,17 +33,17 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   const tableFnSym = imp(`${tableFn}@${importModule}`);
 
   const tableName = obj.dbTable ?? tableNameFromEntity(obj.name, ctx.columnNamingStrategy);
-  const varName = variableNameFromEntity(obj.name);
+  const varName = ctx.collectionName(obj.name);
 
   const primary = obj.primaryIdentity();
-  const rawPkFields = primary?.ownAttr(IDENTITY_ATTR_FIELDS);
+  const rawPkFields = primary?.attr(IDENTITY_ATTR_FIELDS);
   const pkFieldsList: string[] = Array.isArray(rawPkFields)
     ? rawPkFields as string[]
     : typeof rawPkFields === "string"
       ? rawPkFields.split(",").map((f) => f.trim()).filter(Boolean)
       : [];
   const pkFieldNames = new Set<string>(pkFieldsList);
-  const pkGeneration = primary?.ownAttr(IDENTITY_ATTR_GENERATION) as string | undefined;
+  const pkGeneration = primary?.attr(IDENTITY_ATTR_GENERATION) as string | undefined;
 
   const fkMap = buildFkMapForEntity(obj, ctx);
 
@@ -55,9 +56,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   const secondaryIdentities = obj.secondaryIdentities();
   const uniqueFieldNames = new Set<string>();
   for (const sec of secondaryIdentities) {
-    const uniqueAttr = sec.ownAttr(IDENTITY_ATTR_UNIQUE);
+    const uniqueAttr = sec.attr(IDENTITY_ATTR_UNIQUE);
     if (uniqueAttr === false) continue; // explicit non-unique → don't mark column
-    const fields = sec.ownAttr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
+    const fields = sec.attr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
     if (!Array.isArray(fields) || fields.length !== 1) continue; // multi-col uniques use a callback index, not a column flag
     uniqueFieldNames.add(fields[0]!);
   }
@@ -71,9 +72,9 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     const fkInfo = fkMap.get(child.name);
     // Compute the column spec once per field and reuse it for both the column
     // line and the CHECK collection.
-    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy);
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
     const fieldDocs = renderDocsFor(child);
-    const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package);
+    const columnLine = renderColumn(spec, child, ctx, isPk, pkGeneration, fkInfo, isComposite, isUnique, obj.package, obj.name);
     columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
     if (spec.checkConstraint !== undefined) {
       checkConstraints.push({
@@ -83,6 +84,29 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     }
   }
 
+  // FR-017 Tier 2 — TPH single-table inheritance. When this entity is a
+  // discriminator base, fold every concrete subtype's own columns into this
+  // one table. Subtype-only columns are ALWAYS nullable (a row of any other
+  // subtype stores NULL there) and never carry a DB default (a default would
+  // stamp onto other-subtype inserts), regardless of the field's @required.
+  // Subtype entities emit no table of their own (the value-object path).
+  for (const child of collectTphSubtypeFields(obj, ctx.loadedRoot)) {
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
+    const fieldDocs = renderDocsFor(child);
+    const columnLine = renderColumn(
+      spec, child, ctx, false, undefined, fkMap.get(child.name), isComposite, false, obj.package, obj.name, true,
+    );
+    columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
+    // Enum CHECK constraints stay valid under TPH: `NULL IN (...)` is NULL
+    // (not false), so other-subtype rows with NULL pass the check.
+    if (spec.checkConstraint !== undefined) {
+      checkConstraints.push({
+        name: `chk_${tableName}_${spec.dbName}`,
+        expr: spec.checkConstraint,
+      });
+    }
+  }
+
   // Build all table callback entries
   const callbackEntries: Code[] = [];
 
@@ -91,13 +115,13 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   }
 
   for (const sec of secondaryIdentities) {
-    const fields = sec.ownAttr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
+    const fields = sec.attr(IDENTITY_ATTR_FIELDS) as string[] | undefined;
     if (!Array.isArray(fields) || fields.length === 0) continue;
     const indexName = `idx_${tableName}_${fields.map((f) => columnNameFromField(f, ctx.columnNamingStrategy)).join("_")}`;
     // @unique on the identity defaults to true (preserves back-compat with
     // foundations fixtures that assumed secondary identities were always
     // unique). Explicit @unique: false → ordinary non-unique index.
-    const uniqueAttr = sec.ownAttr(IDENTITY_ATTR_UNIQUE);
+    const uniqueAttr = sec.attr(IDENTITY_ATTR_UNIQUE);
     const isUnique = uniqueAttr !== false;
     const indexFn = isUnique ? "uniqueIndex" : "index";
     const indexSym = imp(`${indexFn}@${importModule}`);
@@ -160,11 +184,15 @@ function buildFkMapForEntity(obj: MetaObject, ctx: RenderContext): Map<string, F
     const fkField = fkFieldNames[0]!;
     const targetName = ref.targetEntity;
     if (!targetName) continue;
-    const targetObj = ctx.loadedRoot.findObject(targetName);
+    // @references may be authored bare OR package-qualified, and the loader can
+    // resolve it to an FQN (e.g. the YAML front-end qualifies it). Strip the
+    // package so the lookup matches the object's bare name — mirrors the
+    // relation-resolver, which already does this.
+    const targetObj = ctx.loadedRoot.findObject(stripPackage(targetName));
     if (!targetObj) continue;
     const targetPkField = ref.resolvedTargetPkField(ctx.loadedRoot) ?? "id";
     result.set(fkField, {
-      targetVarName: variableNameFromEntity(targetObj.name),
+      targetVarName: ctx.collectionName(targetObj.name),
       targetEntityName: targetObj.name,
       targetPkField,
     });
@@ -212,6 +240,12 @@ function renderColumn(
   isComposite: boolean,
   isUnique: boolean = false,
   entityPackage: string | undefined = undefined,
+  // Name of the entity this column belongs to — used to detect a self-referential
+  // FK (target entity === this entity), which Drizzle emits without a self-import.
+  currentEntityName: string = "",
+  // FR-017 Tier 2 — TPH subtype-only column: force nullable (drop .notNull())
+  // and suppress any DB default (other-subtype rows must stay NULL here).
+  forceNullable: boolean = false,
 ): Code {
   const fnSym = imp(`${spec.fnName}@${spec.importModule}`);
 
@@ -261,6 +295,9 @@ function renderColumn(
     if (isPk && !isComposite && (m === ".notNull()" || m === ".unique()")) continue;
     // Avoid double-emitting .unique() if it was already appended above.
     if (isUnique && m === ".unique()") continue;
+    // TPH subtype-only column: never .notNull() / .unique() — rows of other
+    // subtypes store NULL, so neither constraint can hold across the table.
+    if (forceNullable && (m === ".notNull()" || m === ".unique()")) continue;
     modifiersStr += m;
   }
 
@@ -268,7 +305,7 @@ function renderColumn(
   // the `sql` import via imp(); a raw `.default(sql`...`)` would leave `sql`
   // unresolved in the generated file.
   let sqlDefaultSegment: Code | null = null;
-  if (spec.defaultExpr !== undefined && !isPk) {
+  if (spec.defaultExpr !== undefined && !isPk && !forceNullable) {
     if (spec.defaultExpr.kind === "now") {
       if (ctx.dialect === "sqlite") {
         const sqlSym = imp("sql@drizzle-orm");
@@ -289,21 +326,30 @@ function renderColumn(
   // FK .references() uses imp() so ts-poet tracks the cross-entity import.
   let fkRefSegment: Code | null = null;
   if (fkInfo !== undefined && !isPk) {
-    const targetSpec = crossEntitySpecifier(
-      ctx.outputLayout,
-      entityPackage,
-      ctx.packageOf.get(fkInfo.targetEntityName),
-      fkInfo.targetEntityName,
-      ctx.extStyle,
-    );
-    const targetVarSym = imp(`${fkInfo.targetVarName}@${targetSpec}`);
-    fkRefSegment = code`.references(() => ${targetVarSym}.${fkInfo.targetPkField})`;
+    if (fkInfo.targetEntityName === currentEntityName) {
+      // Self-referential FK (e.g. createdBy → this same table). Drizzle requires
+      // referencing the local table const directly — NOT a self-import — with an
+      // explicit `Any*Column` return type to break the circular type inference.
+      const anyColType = ctx.dialect === "sqlite" ? "AnySQLiteColumn" : "AnyPgColumn";
+      const anyColSym = imp(`${anyColType}@${spec.importModule}`);
+      fkRefSegment = code`.references((): ${anyColSym} => ${fkInfo.targetVarName}.${fkInfo.targetPkField})`;
+    } else {
+      const targetSpec = crossEntitySpecifier(
+        ctx.outputLayout,
+        entityPackage,
+        ctx.packageOf.get(fkInfo.targetEntityName),
+        fkInfo.targetEntityName,
+        ctx.extStyle,
+      );
+      const targetVarSym = imp(`${fkInfo.targetVarName}@${targetSpec}`);
+      fkRefSegment = code`.references(() => ${targetVarSym}.${fkInfo.targetPkField})`;
+    }
   }
 
   // @autoSet fields: emit .$defaultFn(() => new Date().toISOString()) so Drizzle
   // inserts stamp the server-side timestamp automatically. This means callers don't
   // need to supply createdAt / updatedAt in INSERT calls — Drizzle fills them in.
-  const autoSet = field.ownAttr(FIELD_ATTR_AUTO_SET);
+  const autoSet = field.attr(FIELD_ATTR_AUTO_SET);
   const autoSetSuffix = (autoSet === "onCreate" || autoSet === "onUpdate")
     ? `.$defaultFn(() => new Date().toISOString())`
     : "";
@@ -316,11 +362,17 @@ function renderColumn(
   let dollarTypeSegment: Code | string = "";
   if (spec.dollarTypeRef !== undefined) {
     const ref = spec.dollarTypeRef;
+    const suffix = ref.array ? "[]" : "";
     if (ref.kind === "scalar") {
-      dollarTypeSegment = `.$type<${ref.tsType}[]>()`;
+      dollarTypeSegment = `.$type<${ref.tsType}${suffix}>()`;
     } else {
-      const refSym = imp(`${ref.name}@${ref.module}`);
-      dollarTypeSegment = code`.$type<${refSym}[]>()`;
+      // Resolve the VO module through the shared layout/package/extStyle-aware
+      // helper so the .$type<VO> import matches the field's TS type + Zod schema.
+      const moduleSpec = valueObjectModuleSpecifier(
+        ref.name, ctx.packageOf, entityPackage, ctx.outputLayout, ctx.extStyle,
+      );
+      const refSym = imp(`${ref.name}@${moduleSpec}`);
+      dollarTypeSegment = ref.array ? code`.$type<${refSym}[]>()` : code`.$type<${refSym}>()`;
     }
   }
 

package/src/templates/entity-constants.ts

@@ -67,7 +67,7 @@ function humanize(s: string): string {
  *   "Subscriber" → "/subscribers"
  *   "WorkoutEvent" → "/workout_events"
  */
-function resourcePath(entity: MetaData): string {
+export function resourcePath(entity: MetaData): string {
   const overrideAttr = entity.ownAttr("routePath");
   if (typeof overrideAttr === "string" && overrideAttr.length > 0) {
     return overrideAttr.startsWith("/") ? overrideAttr : `/${overrideAttr}`;
@@ -160,12 +160,12 @@ function renderFieldRules(field: MetaField): string | undefined {
   }
 
   // Field-level @required attr (if not already covered by validator).
-  if (!hasRequired && field.ownAttr(FIELD_ATTR_REQUIRED) === true) {
+  if (!hasRequired && field.attr(FIELD_ATTR_REQUIRED) === true) {
     ruleParts.push(`required: ${JSON.stringify(`${humanize(field.name)} is required`)}`);
   }
 
   // Field-level @maxLength attr (if not already covered).
-  const maxLenAttr = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
+  const maxLenAttr = field.attr(FIELD_ATTR_MAX_LENGTH);
   if (!hasMaxLength && typeof maxLenAttr === "number") {
     ruleParts.push(
       `maxLength: { value: ${maxLenAttr}, message: ${JSON.stringify(`Must be ${maxLenAttr} characters or fewer`)} }`,

package/src/templates/entity-file.ts

@@ -15,6 +15,7 @@ import { renderZodValidators } from "./zod-validators.js";
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
+import { renderTphDiscriminatorUnion, isTphDiscriminatorBase } from "./tph-discriminator.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
@@ -53,7 +54,7 @@ export function renderEntityFile(
   // it. The entity-file generator suppresses this entirely when
   // emitAbstractShapes is off; here we only guarantee "shape, never table".
   if (isAbstract(entity)) {
-    return renderValueObjectFile(entity);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Projection path (read-only: view-backed entity with no table source) ---
@@ -72,19 +73,29 @@ export function renderEntityFile(
   // the shape (LLM tool_use input_schema, REST body parsing) use the Zod
   // schema; consumers that need the type use the interface.
   if (!hasWritableRdbSource(entity)) {
-    return renderValueObjectFile(entity);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Vanilla / write-through entity path ---
-  const enumAliases = renderEnumTypeAliases(entity);
+  const enumAliases = renderEnumTypeAliases(entity, ctx);
+  // FR-017 Tier 1: when this entity carries @discriminator AND has concrete
+  // subtypes, append the discriminated-union type alias, type guards, and
+  // the parse<Base>(row) dispatcher. Returns null otherwise (no subtypes, or
+  // not a discriminator-bearing entity); the section is suppressed cleanly.
+  const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
+  // FR-017: when a discriminator base also has a union block, the union owns the
+  // bare `<Base>` type — so the inferred Drizzle row type is emitted as
+  // `<Base>Row` to avoid a duplicate `export type <Base>`.
+  const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
-    renderInferredTypes(entity),
+    renderInferredTypes(entity, tphBase, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
-    renderZodValidators(entity),
+    renderZodValidators(entity, ctx),
     renderEntityConstants(entity, ctx.apiPrefix),
     ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
+    ...(tphBlock !== null ? [tphBlock] : []),
   ];
 
   // Render ts-poet body first (ts-poet hoists imp()-tracked imports to the top),

package/src/templates/enums-file.ts

@@ -0,0 +1,50 @@
+// FR-019 — shared enums module.
+//
+// Emits, ONCE per run, the materialized (non-@provided) shared enum types that
+// at least one concrete entity field references via `extends` of a root-level
+// abstract `field.enum`. Each enum yields:
+//   • `export type <E> = "A" | "B";`   — the cross-port type identity
+//   • `export const <E>Enum = z.enum(["A","B"]);` — the shared Zod validator
+//
+// Consuming entity files import these instead of redeclaring the union inline.
+// @provided enums are NEVER materialized here (they live in hand-written code,
+// imported from the configured providedEnumModule).
+
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { materializedSharedEnums, type SharedEnum } from "../enum-shared.js";
+import { enumUnionString } from "./inferred-types.js";
+
+/** Basename (no extension) of the shared-enums module emitted at the entity-module target root. */
+export const SHARED_ENUMS_BASENAME = "enums";
+
+/** The exported Zod-constant name for a shared enum (`<E>Enum`). */
+export function sharedEnumZodConstName(enumName: string): string {
+  return `${enumName}Enum`;
+}
+
+/** One enum's two declarations (type alias + shared z.enum const). */
+function renderOneSharedEnum(e: SharedEnum): Code {
+  const z = imp("z@zod");
+  const members = e.values.map((v) => JSON.stringify(v)).join(", ");
+  return code`
+export type ${e.name} = ${enumUnionString(e.values)};
+export const ${sharedEnumZodConstName(e.name)} = ${z}.enum([${members}]);
+`;
+}
+
+/**
+ * The full shared-enums module body, or null when the model has no materialized
+ * shared enums (so the generator emits no file at all).
+ */
+export function renderSharedEnumsFile(root: MetaRoot): string | null {
+  const enums = materializedSharedEnums(root);
+  if (enums.length === 0) return null;
+
+  const body = joinCode(enums.map(renderOneSharedEnum), { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Shared enum types (FR-019): one declaration per reused package-level enum.\n`;
+  return header + body;
+}

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

@@ -1,11 +1,9 @@
 // server/typescript/packages/codegen-ts/src/templates/extract-delegate-emitter.ts
 //
-// FR-010 Plan 2.1 (nested codegen gap) — the runtime-DELEGATING extract emitter.
+// FR-010 — the runtime-DELEGATING extract emitter (the single metadata-driven extract path).
 //
-// The self-contained extract<Name>(text) path (extract-schema-emitter + the baked
-// ExtractSchema) covers scalars / enums / scalar-arrays but leaves nested-object and
-// array-of-object components NULL — the historical FR-010 codegen gap. This module emits
-// the additive delegating overload that CLOSES that gap by wrapping the runtime extract:
+// This module emits the loader-delegating extract entry point that reads the live metadata
+// directly and populates nested-object and array-of-object components in full:
 //
 //   extract<Name>(root: MetaRoot, text, opts?) -> ExtractionResult<<Name>Extracted>
 //
@@ -29,16 +27,17 @@ import {
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
   PACKAGE_SEPARATOR,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.js";
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
-  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
   const direct = findObject(root, ref);
   if (direct !== undefined) return direct;

package/src/templates/extractor.ts

@@ -33,6 +33,7 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
   PACKAGE_SEPARATOR,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray } from "./fr010-field-mapping.js";
 import { mirrorName } from "./extract-delegate-emitter.js";
@@ -40,7 +41,7 @@ import { enumUnionAliasName } from "./inferred-types.js";
 import { enumValues } from "../enum-meta.js";
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
@@ -49,7 +50,7 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
 function refVo(field: MetaData, root: MetaData): MetaData | undefined {
-  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string") return undefined;
   const direct = findObject(root, ref);
   if (direct !== undefined) return direct;
@@ -64,9 +65,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,14 +77,15 @@ 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;
+  return field.attr(FIELD_ATTR_REQUIRED) === true;
 }
 
 /** The mirror→strict mapper name for a value-object (`toStrict<Name>`). */
@@ -93,8 +95,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 +108,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 +140,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,24 +206,44 @@ 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);
@@ -227,7 +251,7 @@ function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
     }
   };
   visit(vo);
-  return order;
+  return groups;
 }
 
 /** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
@@ -286,10 +310,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,13 +331,13 @@ 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` +
     `/**\n` +
     ` * Extract a fully-typed \`${strictType}\` from dirty \`text\` using the loaded \`root\` (which must\n` +
-    ` * declare the "${payloadRef}" payload value-object). Runs the tolerant extract, then maps the\n` +
+    ` * declare the "${strictType}" payload value-object). Runs the tolerant extract, then maps the\n` +
     ` * extracted mirror onto the strict payload.\n` +
     ` *\n` +
     ` * @throws Error iff a \`@required\` field was lost (the strict opt-in gate).\n` +