@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/templates/zod-validators.ts

@@ -10,7 +10,7 @@
 // downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
 import { code, joinCode, imp, type Code } from "ts-poet";
-import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
 import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
@@ -24,9 +24,82 @@ import {
   AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
+  OBJECT_ATTR_DISCRIMINATOR, OBJECT_ATTR_DISCRIMINATOR_VALUE,
 } from "@metaobjectsdev/metadata";
 import { enumValues, zodEnumExpr } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { sharedEnumForField } from "../enum-shared.js";
+import { sharedEnumImportSpecifier } from "../enum-import.js";
+import { sharedEnumZodConstName } from "./enums-file.js";
+import type { RenderContext } from "../render-context.js";
+
+/**
+ * FR-017 Tier 1 — when this object is a TPH subtype (@discriminatorValue set
+ * and an ancestor carries @discriminator), return the discriminator-field-name
+ * → pinned-literal-value pair. Subtypes emit `<field>: z.literal("<value>")`
+ * instead of the inherited field's normal type expression. Returns undefined
+ * when the object is not a TPH subtype.
+ */
+export function tphDiscriminatorPin(obj: MetaObject): { fieldName: string; value: string } | undefined {
+  const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+  if (typeof value !== "string" || value === "") return undefined;
+
+  // Walk the extends chain to find the root carrying @discriminator.
+  let cursor = obj.superResolved;
+  while (cursor !== undefined) {
+    const fieldName = cursor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (typeof fieldName === "string" && fieldName !== "") {
+      return { fieldName, value };
+    }
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
+/** True when this object is a TPH subtype — it declares @discriminatorValue
+ *  and an ancestor carries @discriminator. */
+export function isTphSubtype(obj: MetaObject): boolean {
+  return tphDiscriminatorPin(obj) !== undefined;
+}
+
+/**
+ * FR-017 Tier 2 — the per-subtype FULL read schema `<Sub>Schema`. Unlike the
+ * insert schema, this includes every effective field (PK included) so a raw DB
+ * row parses through it. The discriminator field is pinned to its literal value
+ * (`type: z.literal("Bridge")`) so the schema rejects a row of another subtype.
+ *
+ * This is the schema parse<Base>(row) dispatches to (see tph-discriminator.ts).
+ * Non-required columns are `.nullable()`-tolerant: a nullable TPH column read
+ * back from the DB arrives as `null`, not `undefined`, so the read schema must
+ * accept null (the insert schema, by contrast, makes them `.optional()`).
+ */
+export function renderTphSubtypeReadSchema(obj: MetaObject): Code {
+  const z = imp("z@zod");
+  const tphPin = tphDiscriminatorPin(obj);
+
+  const fieldLines: Code[] = [];
+  for (const child of obj.fields()) {
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      fieldLines.push(code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`);
+      continue;
+    }
+    const expr = zodFieldExpr(child);
+    // zodFieldExpr already appends `.optional()` for non-required fields; add
+    // `.nullable()` on top so a NULL column value (the TPH default for any
+    // subtype-only column) parses cleanly.
+    fieldLines.push(
+      fieldWillBeOptional(child) ? code`  ${child.name}: ${expr}.nullable()` : code`  ${child.name}: ${expr}`,
+    );
+  }
+
+  const docs = renderDocsFor(obj);
+  const docsPrefix = docs ? `${docs}\n` : "";
+  return code`
+${docsPrefix}export const ${obj.name}Schema = ${z}.object({
+${joinCode(fieldLines, { on: ",\n" })}
+});
+`;
+}
 
 /** Auto-generated PK field names that should be omitted from InsertSchema. */
 function autoGenPkFieldNames(obj: MetaObject): Set<string> {
@@ -55,6 +128,7 @@ function autoGenPkFieldNames(obj: MetaObject): Set<string> {
 export function renderInsertSchemaOnly(obj: MetaObject): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   for (const child of obj.fields()) {
@@ -64,6 +138,14 @@ export function renderInsertSchemaOnly(obj: MetaObject): Code {
     // create-shape schema entirely.
     if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
+
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
     if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
@@ -86,9 +168,90 @@ ${joinCode(insertFieldLines, { on: ",\n" })}
 `;
 }
 
-export function renderZodValidators(obj: MetaObject): Code {
+/** One documented field in an Insert/Update schema's accepted shape. */
+export interface SchemaFieldShape {
+  /** The field name (the schema property key). */
+  name: string;
+  /** Whether the property is optional in the schema (`.optional()` / omitted-OK). */
+  optional: boolean;
+  /** For the @discriminator field on a TPH subtype's InsertSchema: the pinned
+   *  literal value (`z.literal("Bridge")`). Undefined otherwise. */
+  pinnedLiteral?: string;
+  /** True for @autoSet timestamp fields the schema fills server-side
+   *  (`z.string().optional().transform(...)`). */
+  autoSet?: boolean;
+}
+
+/**
+ * The field SET (name + optionality) the `<Name>InsertSchema` accepts — derived
+ * by the SAME iteration + skip rules `renderInsertSchemaOnly` /
+ * `renderZodValidators` use to EMIT that schema, so a documented create-payload
+ * shape can never drift from the real schema:
+ *   • auto-generated PK fields are omitted (caller doesn't provide them);
+ *   • @readOnly fields are omitted (DB / replication owns the write path);
+ *   • a TPH subtype's @discriminator field is a pinned `z.literal(value)`;
+ *   • @autoSet fields are present but optional (server fills them);
+ *   • every other field's optionality is `fieldWillBeOptional` (not required, or
+ *     carries a @default).
+ */
+export function insertSchemaFields(obj: MetaObject): SchemaFieldShape[] {
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
+  const out: SchemaFieldShape[] = [];
+  for (const child of obj.fields()) {
+    if (autoGenPkFields.has(child.name)) continue;
+    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      out.push({ name: child.name, optional: false, pinnedLiteral: tphPin.value });
+      continue;
+    }
+    const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
+    if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
+      out.push({ name: child.name, optional: true, autoSet: true });
+    } else {
+      out.push({ name: child.name, optional: fieldWillBeOptional(child) });
+    }
+  }
+  return out;
+}
+
+/**
+ * The field SET the `<Name>UpdateSchema` accepts — same iteration + skip rules
+ * as `insertSchemaFields`, but mirroring the UpdateSchema branch of
+ * `renderZodValidators`:
+ *   • a TPH subtype's @discriminator field is OMITTED (clients can't change subtype);
+ *   • @autoSet onCreate fields are OMITTED (creation timestamps are immutable);
+ *   • @autoSet onUpdate fields are present + optional (server fills them);
+ *   • every other field is optional (PATCH semantics).
+ */
+export function updateSchemaFields(obj: MetaObject): SchemaFieldShape[] {
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
+  const out: SchemaFieldShape[] = [];
+  for (const child of obj.fields()) {
+    if (autoGenPkFields.has(child.name)) continue;
+    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // TPH subtype discriminator: omitted from the update schema entirely.
+    if (tphPin !== undefined && child.name === tphPin.fieldName) continue;
+    const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
+    if (autoSet === AUTO_SET_ON_CREATE) {
+      // Omitted: creation timestamps cannot change after creation.
+      continue;
+    }
+    if (autoSet === AUTO_SET_ON_UPDATE) {
+      out.push({ name: child.name, optional: true, autoSet: true });
+      continue;
+    }
+    // All non-autoSet fields are optional in the update schema (PATCH semantics).
+    out.push({ name: child.name, optional: true });
+  }
+  return out;
+}
+
+export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   const updateFieldLines: Code[] = [];
@@ -100,6 +263,17 @@ export function renderZodValidators(obj: MetaObject): Code {
     // contract at the boundary with a 400 response).
     if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    // The discriminator is implicit on subtype rows (controlled by URL / insert
+    // path) — the app never writes it via the body and never updates it.
+    // Insert: pinned literal. Update: omitted entirely (clients can't change subtype).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
+
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
     // Insert schema: @autoSet fields use transform (always override client input).
@@ -108,7 +282,7 @@ export function renderZodValidators(obj: MetaObject): Code {
         code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
     } else {
-      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child)}`);
+      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`);
     }
 
     // Update schema: @autoSet onCreate → omit entirely; onUpdate → transform
@@ -122,7 +296,7 @@ export function renderZodValidators(obj: MetaObject): Code {
       // All non-autoSet fields are optional in the update schema (PATCH semantics).
       // zodFieldExpr already appends .optional() when the field is non-required
       // OR has a default; only append once more when it didn't.
-      const baseExpr = zodFieldExpr(child);
+      const baseExpr = zodFieldExpr(child, obj, ctx);
       updateFieldLines.push(
         fieldWillBeOptional(child) ? code`  ${child.name}: ${baseExpr}` : code`  ${child.name}: ${baseExpr}.optional()`,
       );
@@ -146,7 +320,7 @@ ${joinCode(updateFieldLines, { on: ",\n" })}
 `;
 }
 
-function zodFieldExpr(field: MetaField): Code {
+function zodFieldExpr(field: MetaField, owner?: MetaObject, ctx?: RenderContext): Code {
   // FIELD_SUBTYPE_OBJECT: emit z.array(<Ref>InsertSchema) / <Ref>InsertSchema
   // via an imp() so ts-poet hoists the cross-module import. Without this the
   // field used to collapse to z.string() / z.array(z.string()) and downstream
@@ -154,7 +328,10 @@ function zodFieldExpr(field: MetaField): Code {
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const refImp = imp(`${ref}InsertSchema@./${ref}.js`);
+      // @objectRef may be authored fully-qualified or bare — the referenced
+      // <Ref>InsertSchema + its sibling module use the BARE short name.
+      const refBase = stripPackage(ref);
+      const refImp = imp(`${refBase}InsertSchema@./${refBase}.js`);
       let base: Code = code`${refImp}`;
       if (field.isArray) base = code`z.array(${base})`;
       return appendValidatorChain(base, field);
@@ -187,7 +364,27 @@ function zodFieldExpr(field: MetaField): Code {
       break;
     case FIELD_SUBTYPE_ENUM: {
       const values = enumValues(field);
-      baseStr = values !== undefined ? zodEnumExpr(values) : "z.string()";
+      if (values === undefined) {
+        baseStr = "z.string()";
+        break;
+      }
+      // FR-019: a field extending a MATERIALIZED root-level abstract enum uses the
+      // shared `<E>Enum` Zod const (imported from ./enums) instead of inlining
+      // z.enum([...]). A @provided enum keeps inline z.enum([...]) — validation
+      // stays metaobjects-owned (the @values SSOT); only the TS type is external.
+      // Inline enums (and bare-ctx unit-test calls) keep inlining as before.
+      if (ctx !== undefined) {
+        const shared = sharedEnumForField(field);
+        if (shared !== undefined && !shared.provided) {
+          const constName = sharedEnumZodConstName(shared.name);
+          const spec = sharedEnumImportSpecifier(ctx, owner?.package);
+          const sharedConst = imp(`${constName}@${spec}`);
+          let base: Code = code`${sharedConst}`;
+          if (field.isArray) base = code`z.array(${base})`;
+          return appendValidatorChain(base, field);
+        }
+      }
+      baseStr = zodEnumExpr(values);
       break;
     }
     case FIELD_SUBTYPE_STRING:

package/templates/api/agent-api.md.mustache

@@ -0,0 +1,30 @@
+{{{generatedMarker}}}
+
+# {{title}}
+
+Generated API reference for {{project}}; call these exactly as written. {{importNote}}
+{{#hasSetup}}
+
+## Setup
+{{#setup}}
+- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`
+{{/setup}}
+{{/hasSetup}}
+{{#units}}
+
+## {{node}}
+{{#groups}}
+
+`{{importHeader}}`
+{{#symbols}}
+- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}
+{{/symbols}}
+{{/groups}}
+{{#example}}
+
+Example:
+```ts
+{{{example}}}
+```
+{{/example}}
+{{/units}}

package/templates/api/entity-api.md.mustache

@@ -0,0 +1,69 @@
+{{{generatedMarker}}}
+
+# {{node}} API
+{{#modelPageHref}}
+
+**Model / metadata:** [{{node}}]({{modelPageHref}})
+{{/modelPageHref}}
+
+> Import paths are relative to your generated-output directory.
+{{#hasSetup}}
+
+## Setup
+
+Obtain the runtime handles the calls below need:
+{{#setup}}
+
+- `{{handle}}` — {{{note}}}
+
+```ts
+{{{snippet}}}
+```
+{{/setup}}
+{{/hasSetup}}
+{{#unitExample}}
+
+## Example
+
+```ts
+{{{unitExample}}}
+```
+{{/unitExample}}
+{{#sections}}
+
+## {{heading}}
+{{#symbols}}
+
+### `{{signature}}`
+
+{{usage}}
+
+```ts
+{{importLine}}
+```
+{{#hasFields}}
+
+{{fieldsCaption}}:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+{{#fieldRows}}
+| `{{field}}` | `{{{type}}}` | {{required}} | {{notes}} |
+{{/fieldRows}}
+{{/hasFields}}
+{{#mountNote}}
+
+Mount: {{{mountNote}}}
+{{/mountNote}}
+{{#throws}}
+
+Throws: {{throws}}
+{{/throws}}
+{{#example}}
+
+```ts
+{{{example}}}
+```
+{{/example}}
+{{/symbols}}
+{{/sections}}

package/templates/api/index.md.mustache

@@ -0,0 +1,21 @@
+{{{generatedMarker}}}
+
+# {{title}}
+
+{{intro}}
+{{#hasEntities}}
+
+## Entities
+
+{{#entities}}
+- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})
+{{/entities}}
+{{/hasEntities}}
+{{#hasTemplates}}
+
+## Templates
+
+{{#templates}}
+- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})
+{{/templates}}
+{{/hasTemplates}}

package/templates/docs/entity-page.md.mustache

@@ -1,21 +1,20 @@
 {{{generatedMarker}}}
 
 # {{entity.name}}
+{{#summaryLead}}
+
+{{{.}}}
+{{/summaryLead}}
 {{#descriptionQuote}}
 
 {{{.}}}
 {{/descriptionQuote}}
+{{#apiRefs.0}}
 
-{{{preambleHeader}}}
-{{#hasStorage}}
-
-## Storage
+**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}
+{{/apiRefs.0}}
 
-{{{storage.tableHeader}}}
-{{#storage.rows}}
-{{{rowLine}}}
-{{/storage.rows}}
-{{/hasStorage}}
+{{{preambleHeader}}}
 {{#hasIdentities}}
 
 ## Identity
@@ -24,6 +23,31 @@
 - {{{bullet}}}
 {{/identities}}
 {{/hasIdentities}}
+{{#hasNeighborhoodEr}}
+
+## In context
+
+{{{neighborhoodErBlock}}}
+{{/hasNeighborhoodEr}}
+{{#fields.hasFields}}
+
+## Fields
+
+| Field | Type | Required | Column | Rules |
+|---|---|---|---|---|
+{{#fields.rows}}
+| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |
+{{/fields.rows}}
+{{/fields.hasFields}}
+{{#fieldDetails.hasDetails}}
+
+## Field details
+
+{{#fieldDetails.rows}}
+{{{block}}}
+
+{{/fieldDetails.rows}}
+{{/fieldDetails.hasDetails}}
 {{#hasRelationships}}
 
 ## Relationships
@@ -32,12 +56,6 @@
 - {{{bullet}}}
 {{/relationships}}
 {{/hasRelationships}}
-
-## Validation
-
-- `{{validation.insertSchema}}` (Zod) — for creating new {{validation.lower}}s.
-- `{{validation.updateSchema}}` (Zod) — for partial updates.
-- See `{{validation.entityFile}}` for the exported schemas.
 {{#hasUsedBy}}
 
 ## Used by
@@ -46,9 +64,3 @@
 - {{{bullet}}}
 {{/usedBy}}
 {{/hasUsedBy}}
-
-## Generated code
-
-{{#generated}}
-- `{{filename}}` — {{{description}}}
-{{/generated}}

package/templates/docs/template-page.md.mustache

@@ -0,0 +1,56 @@
+{{{generatedMarker}}}
+
+# {{name}}
+{{#descriptionQuote}}
+
+{{{.}}}
+{{/descriptionQuote}}
+
+**Kind:** {{kind}}
+
+## Output
+{{^isEmail}}
+
+- Format: `{{format}}`
+{{/isEmail}}
+{{#isEmail}}
+
+Multipart email — rendered as the following parts:
+
+| Part | Source | Format | Escaping |
+|---|---|---|---|
+{{#parts}}
+| {{label}} | `{{ref}}` | `{{format}}` | {{#escaped}}escaped{{/escaped}}{{^escaped}}raw{{/escaped}} |
+{{/parts}}
+{{/isEmail}}
+
+## Input
+
+- Payload: [`{{payload.name}}`]({{payload.link}})
+{{#hasRequiredTags}}
+- Required fields:{{#requiredTags}} `{{.}}`{{/requiredTags}}
+{{/hasRequiredTags}}
+
+## Render contract
+
+- Every field referenced by the template is validated against the payload at generation time; an unknown field fails generation.
+{{#maxChars}}
+- Maximum length: {{.}} characters (rendering longer output fails).
+{{/maxChars}}
+{{#hasRequiredTags}}
+- Required tags must be present:{{#requiredTags}} `{{.}}`{{/requiredTags}}
+{{/hasRequiredTags}}
+
+## Source
+
+{{#sourceRefs}}
+- `{{.}}`
+{{/sourceRefs}}
+{{#templateSourceSection}}
+
+{{{.}}}
+{{/templateSourceSection}}
+
+## Capability
+
+{{capability}}

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

@@ -1,111 +0,0 @@
-// server/typescript/packages/codegen-ts/src/templates/extract-schema-emitter.ts
-//
-// Turns a payload value-object into TS source fragments for the FR-010 extract codegen:
-//   • schemaLiteral     — a `extractSchema(Format.JSON, "root", [ … ])` baked descriptor
-//                         built from FieldSpec factories (scalar / enumField).
-//   • mirrorInterface   — an all-nullable mirror interface `<Payload>Extracted` (each
-//                         component `T | null`); extract returns this nullable twin rather
-//                         than the strict payload (same reasoning as the Java/C#/Kotlin ports).
-//   • mirrorInitializer — `{ prop: asString(d, "prop"), … }` building the mirror from the
-//                         forgiving outcome map `d`.
-//
-// Mirrors the C# ExtractSchemaEmitter (adapted to TS syntax + the `| null` nullable mirror).
-// Bounded scope: scalar / enum / scalar-array. Nested object + array-of-enum deferred.
-
-import {
-  type MetaData,
-  FIELD_SUBTYPE_ENUM,
-  FIELD_SUBTYPE_OBJECT,
-  FIELD_ATTR_ENUM_ALIAS,
-} from "@metaobjectsdev/metadata";
-import {
-  fields,
-  isRequired,
-  isArray,
-  scalarKind,
-  mirrorType,
-  extractMapCall,
-  enumValues,
-  coerceDefault,
-  defaultValue,
-  resolveNormalize,
-  jsonStringLiteral,
-  stringArrayLiteral,
-  propertiesMapLiteral,
-} from "./fr010-field-mapping.js";
-import { NORMALIZE_DEFAULT } from "@metaobjectsdev/metadata";
-
-/** Emit `extractSchema(Format.X, "rootName", [ … ])`. */
-export function schemaLiteral(vo: MetaData, format: string, rootName: string): string {
-  const formatEnum = format.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
-  const specs = fields(vo).map((f) => fieldSpecLiteral(f, vo));
-  return `extractSchema(${formatEnum}, ${jsonStringLiteral(rootName)}, [${specs.join(", ")}])`;
-}
-
-function fieldSpecLiteral(field: MetaData, owner: MetaData): string {
-  const name = jsonStringLiteral(field.name);
-  const required = isRequired(field);
-
-  if (field.subType === FIELD_SUBTYPE_ENUM) {
-    const valuesLit = stringArrayLiteral(enumValues(field));
-    const aliasLit = propertiesMapLiteral(field.ownAttr(FIELD_ATTR_ENUM_ALIAS));
-    // FR-011: extended enumField signature is (name, required, values, aliases,
-    // coerceDefault?, normalize="strip", defaultValue?). Resolve the three new args
-    // (field → object → "strip" for normalize) and emit only what's needed: keep the
-    // back-compat 4-arg form when nothing is set, else emit the positional tail up to
-    // the last meaningful arg.
-    const cd = coerceDefault(field);
-    const dv = defaultValue(field);
-    const normalize = resolveNormalize(field, owner);
-    // enumField() sets array:false; enum-array is a bounded deferral (parity with Java/C#).
-    if (cd == null && dv == null && normalize === NORMALIZE_DEFAULT) {
-      return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit})`;
-    }
-    const cdLit = cd == null ? "null" : jsonStringLiteral(cd);
-    const normLit = jsonStringLiteral(normalize);
-    if (dv == null) {
-      return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit}, ${cdLit}, ${normLit})`;
-    }
-    return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit}, ${cdLit}, ${normLit}, ${jsonStringLiteral(dv)})`;
-  }
-
-  if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    // FR-010: nested extract deferred — treat as an opaque required/optional string slot.
-    return `scalar(${name}, FieldKind.STRING, ${required}) /* FR-010: nested extract deferred */`;
-  }
-
-  const kind = scalarKind(field.subType) ?? "STRING";
-  // Scalar-array: the scalar() factory only builds singular specs (array:false), so emit a
-  // FieldSpec object literal with array:true. Tier-2 win over the Roslyn proof: the emitted
-  // extract() actually populates the array at runtime (ExtractMap.asStringList).
-  if (isArray(field)) {
-    return (
-      `{ name: ${name}, kind: FieldKind.${kind}, required: ${required}, array: true, ` +
-      `enumValues: null, enumAlias: null, min: null, max: null, nested: null }`
-    );
-  }
-  return `scalar(${name}, FieldKind.${kind}, ${required})`;
-}
-
-/** Emit the all-nullable mirror interface declaration. */
-export function mirrorInterface(vo: MetaData, interfaceName: string): string {
-  const base = interfaceName.endsWith("Extracted")
-    ? interfaceName.slice(0, -"Extracted".length)
-    : interfaceName;
-  const lines: string[] = [];
-  lines.push(
-    `/** Best-effort extracted twin of \`${base}\` — every field nullable (null where lost/malformed). */`,
-  );
-  lines.push(`export interface ${interfaceName} {`);
-  for (const f of fields(vo)) {
-    lines.push(`  ${f.name}: ${mirrorType(f)};`);
-  }
-  lines.push("}");
-  return lines.join("\n");
-}
-
-/** Emit `{ prop: asString(d, "prop"), … }` building the mirror from the forgiving map `d`. */
-export function mirrorInitializer(vo: MetaData): string {
-  const assigns = fields(vo).map((f) => `${f.name}: ${extractMapCall(f)}`);
-  return `{ ${assigns.join(", ")} }`;
-}