@metaobjectsdev/codegen-ts 0.7.0-rc.9 → 0.8.0-rc.1

package/src/templates/docs-file.ts

@@ -0,0 +1,51 @@
+// Backward-compatible facade over the rc.12+ template-driven docsFile()
+// implementation. The Markdown structure now lives in
+// `templates/docs/entity-page.md.mustache`; this module preserves the
+// `renderDocsFile()` + `DocsRenderOpts` exports so the per-section unit
+// tests in `test/templates/docs-file.test.ts` keep working without
+// modification.
+//
+// Adopters writing custom docs templates should import the public surface
+// from `@metaobjectsdev/codegen-ts/generators` instead:
+//   - `buildEntityDocData(entity, opts)` for the typed data dict
+//   - `templateGenerator({ template: "docs/entity-page.md", ... })` for the
+//     standard end-to-end generator
+
+import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import type { Dialect } from "../column-mapper.js";
+import type { ColumnNamingStrategy } from "../metaobjects-config.js";
+import { render } from "@metaobjectsdev/render";
+import { buildEntityDocData } from "../generators/docs-data-builder.js";
+import { frameworkTemplatesProvider } from "../render-engine/framework-provider.js";
+
+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`). */
+export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string {
+  const data = buildEntityDocData(entity, {
+    dialect: opts.dialect,
+    ...(opts.columnNamingStrategy !== undefined
+      ? { columnNamingStrategy: opts.columnNamingStrategy }
+      : {}),
+    loadedRoot: opts.loadedRoot,
+    ...(opts.generatorNames !== undefined
+      ? { generatorNames: opts.generatorNames }
+      : {}),
+  });
+  return render({
+    ref: "docs/entity-page.md",
+    payload: data,
+    provider: frameworkTemplatesProvider,
+    format: "markdown",
+  });
+}

package/src/templates/entity-file.ts

@@ -20,6 +20,7 @@ import { isProjection } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { renderValueObjectFile } from "./value-object-file.js";
+import { isAbstract } from "../instance-artifacts.js";
 
 /**
  * Render-time options for the entity-file composer.
@@ -43,6 +44,18 @@ export function renderEntityFile(
 ): string {
   const allowlists = opts?.allowlists ?? true;
 
+  // --- Abstract path (shape only) ---
+  // An abstract entity contributes shape via inheritance only — it must NEVER
+  // produce a Drizzle table / migration footprint / filter allowlist, even when
+  // it carries a source.rdb child. This is the cross-port invariant (abstract →
+  // no instance/write artifacts, including CREATE TABLE). It still emits its
+  // value-object shape (interface + Zod) so subclasses/consumers can reference
+  // 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);
+  }
+
   // --- Projection path (read-only: view-backed entity with no table source) ---
   // Projections intentionally get the z.enum() validator but NOT a named enum
   // type alias — emitting aliases here is a deliberate v1 scope decision.

package/src/templates/fr010-field-mapping.ts

@@ -0,0 +1,191 @@
+// server/typescript/packages/codegen-ts/src/templates/fr010-field-mapping.ts
+//
+// Shared field-kind mapping for the FR-010 codegen emitters (recover-schema-emitter +
+// output-format-spec-emitter). Maps a metadata field subtype onto the render engine's
+// FieldKind member, the idiomatic nullable TS type used by the recover mirror interface,
+// and the RecoverMap accessor that reads it from the forgiving outcome map.
+//
+// Mirrors the C# Fr010FieldMapping (adapted to TS syntax + the `| null` nullable mirror).
+// Bounded scope (parity with Java/Kotlin/C#): scalar / enum / scalar-array. Nested object +
+// array-of-enum are deferred.
+
+import {
+  type MetaData,
+  TYPE_FIELD,
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_TIME,
+  FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_SHORT,
+  FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_VALUES,
+} from "@metaobjectsdev/metadata";
+
+/** The render-engine FieldKind member name for a scalar field subtype, or null if non-scalar. */
+export function scalarKind(subType: string): string | null {
+  switch (subType) {
+    case FIELD_SUBTYPE_STRING:
+    case FIELD_SUBTYPE_CLASS:
+    case FIELD_SUBTYPE_DATE:
+    case FIELD_SUBTYPE_TIME:
+    case FIELD_SUBTYPE_TIMESTAMP:
+      return "STRING";
+    case FIELD_SUBTYPE_INT:
+    case FIELD_SUBTYPE_SHORT:
+    case FIELD_SUBTYPE_BYTE:
+      return "INT";
+    case FIELD_SUBTYPE_LONG:
+    case FIELD_SUBTYPE_CURRENCY:
+      return "LONG";
+    case FIELD_SUBTYPE_DOUBLE:
+    case FIELD_SUBTYPE_FLOAT:
+    case FIELD_SUBTYPE_DECIMAL:
+      return "DOUBLE";
+    case FIELD_SUBTYPE_BOOLEAN:
+      return "BOOLEAN";
+    default:
+      return null;
+  }
+}
+
+/** The field children of a payload value-object, in declaration order. */
+export function fields(vo: MetaData): MetaData[] {
+  return vo.children().filter((c) => c.type === TYPE_FIELD);
+}
+
+/** isArray is a native (reserved) property on MetaData, not an attr. */
+export function isArray(field: MetaData): boolean {
+  return field.isArray === true;
+}
+
+/** True iff the field's @required is explicitly true (or the string "true"). */
+export function isRequired(field: MetaData): boolean {
+  const v = field.ownAttr(FIELD_ATTR_REQUIRED);
+  if (v === true) return true;
+  return typeof v === "string" && v.toLowerCase() === "true";
+}
+
+/** The string members of an enum field's @values attr (empty when absent). */
+export function enumValues(field: MetaData): string[] {
+  const v = field.ownAttr(FIELD_ATTR_VALUES);
+  if (Array.isArray(v)) return v.map((e) => String(e));
+  return [];
+}
+
+/** The nullable TS type for a field in the recover mirror interface. */
+export function mirrorType(field: MetaData): string {
+  // Matches asStringList's `(string | null)[] | null` return — a recovered array
+  // can contain null elements where individual items were lost.
+  if (isArray(field)) return "(string | null)[] | null";
+  if (field.subType === FIELD_SUBTYPE_OBJECT) return "unknown"; // nested deferred
+  if (field.subType === FIELD_SUBTYPE_ENUM) return "string | null"; // enum is string-backed
+  switch (scalarKind(field.subType)) {
+    case "INT":
+    case "LONG":
+    case "DOUBLE":
+      return "number | null";
+    case "BOOLEAN":
+      return "boolean | null";
+    default:
+      return "string | null";
+  }
+}
+
+/**
+ * The RecoverMap.as* helper name that reads this field from the forgiving map, or null
+ * for a nested object (which emits a null literal, not a helper call). Single source of
+ * truth for the per-field dispatch — both recoverMapCall and recoverMapHelpersUsed use it.
+ */
+function recoverMapHelper(field: MetaData): string | null {
+  if (isArray(field)) return "asStringList";
+  if (field.subType === FIELD_SUBTYPE_OBJECT) return null; // null literal, no helper
+  if (field.subType === FIELD_SUBTYPE_ENUM) return "asString";
+  switch (scalarKind(field.subType)) {
+    case "INT":
+      return "asInt";
+    case "LONG":
+      return "asLong";
+    case "DOUBLE":
+      return "asDouble";
+    case "BOOLEAN":
+      return "asBool";
+    default:
+      return "asString";
+  }
+}
+
+/** The RecoverMap.as* helper name + call that reads this field from the forgiving map `d`. */
+export function recoverMapCall(field: MetaData): string {
+  const helper = recoverMapHelper(field);
+  if (helper === null) return "null /* FR-010: nested recover deferred */";
+  return `${helper}(d, ${jsonStringLiteral(field.name)})`;
+}
+
+/** Distinct RecoverMap helper names used across a value-object's fields (for the import). */
+export function recoverMapHelpersUsed(vo: MetaData): string[] {
+  const used = new Set<string>();
+  for (const f of fields(vo)) {
+    const helper = recoverMapHelper(f);
+    if (helper !== null) used.add(helper);
+  }
+  return [...used].sort();
+}
+
+/** A TS double-quoted string literal for `value`, with the load-bearing chars escaped. */
+export function jsonStringLiteral(value: string): string {
+  let out = '"';
+  for (const ch of value) {
+    switch (ch) {
+      case "\\":
+        out += "\\\\";
+        break;
+      case '"':
+        out += '\\"';
+        break;
+      case "\t":
+        out += "\\t";
+        break;
+      case "\n":
+        out += "\\n";
+        break;
+      case "\r":
+        out += "\\r";
+        break;
+      default:
+        out += ch;
+    }
+  }
+  return out + '"';
+}
+
+/** A TS array literal `["a", "b"]` for the given members. */
+export function stringArrayLiteral(values: readonly string[]): string {
+  return "[" + values.map((v) => jsonStringLiteral(v)).join(", ") + "]";
+}
+
+/**
+ * A TS object literal `{ "k": "v", … }` for a properties-shaped attr (e.g. @enumAlias /
+ * @enumDoc), or "null" when absent/empty. Null values are dropped; keys are sorted
+ * ordinally for deterministic output (matches the canonical-serializer properties sort).
+ */
+export function propertiesMapLiteral(attr: unknown): string {
+  if (attr == null || typeof attr !== "object" || Array.isArray(attr)) return "null";
+  const d = attr as Record<string, unknown>;
+  const entries = Object.keys(d)
+    .filter((k) => d[k] != null)
+    .sort()
+    .map((k) => `${jsonStringLiteral(k)}: ${jsonStringLiteral(String(d[k]))}`);
+  if (entries.length === 0) return "null";
+  return "{ " + entries.join(", ") + " }";
+}

package/src/templates/output-format-spec-emitter.ts

@@ -0,0 +1,97 @@
+// server/typescript/packages/codegen-ts/src/templates/output-format-spec-emitter.ts
+//
+// Turns a payload value-object + its template.output node into a TS source literal for an
+// OutputFormatSpec — the artifact-1 prompt descriptor used by the FR-010 output-prompt codegen.
+//
+// Emits an `{ format, rootName, style, fields: [ … ] } satisfies OutputFormatSpec` literal.
+// Mirrors the C# OutputFormatSpecEmitter (adapted to TS syntax). Field-kind mapping is shared
+// via fr010-field-mapping. Bounded scope: scalar / enum. Nested object → FieldKind.OBJECT placeholder.
+
+import {
+  type MetaData,
+  FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_EXAMPLE,
+  FIELD_ATTR_INSTRUCTION,
+  FIELD_ATTR_ENUM_DOC,
+  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_PROMPT_STYLE,
+  PROMPT_STYLE_INLINE,
+  PROMPT_STYLE_EXAMPLE_ONLY,
+} from "@metaobjectsdev/metadata";
+import {
+  fields,
+  isRequired,
+  isArray,
+  scalarKind,
+  enumValues,
+  jsonStringLiteral,
+  stringArrayLiteral,
+  propertiesMapLiteral,
+} from "./fr010-field-mapping.js";
+
+/** Emit `{ format, rootName, style, fields: [ … ] } satisfies OutputFormatSpec`. */
+export function specLiteral(vo: MetaData, template: MetaData, rootName: string): string {
+  const formatEnum = resolveFormat(template);
+  const styleEnum = resolvePromptStyle(template);
+  const fieldLits = fields(vo).map(promptFieldLiteral);
+  return (
+    `{ format: ${formatEnum}, rootName: ${jsonStringLiteral(rootName)}, ` +
+    `style: ${styleEnum}, fields: [${fieldLits.join(", ")}] } satisfies OutputFormatSpec`
+  );
+}
+
+function resolveFormat(template: MetaData): string {
+  const f = template.ownAttr(TEMPLATE_ATTR_FORMAT);
+  return typeof f === "string" && f.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
+}
+
+function resolvePromptStyle(template: MetaData): string {
+  switch (template.ownAttr(TEMPLATE_ATTR_PROMPT_STYLE)) {
+    case PROMPT_STYLE_INLINE:
+      return "PromptStyle.INLINE";
+    case PROMPT_STYLE_EXAMPLE_ONLY:
+      return "PromptStyle.EXAMPLE_ONLY";
+    default:
+      return "PromptStyle.GUIDE";
+  }
+}
+
+/** A PromptField object literal. Field order matches the PromptField interface. */
+function promptFieldLiteral(field: MetaData): string {
+  const name = jsonStringLiteral(field.name);
+  const required = isRequired(field);
+  const array = isArray(field);
+
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    return (
+      `{ name: ${name}, kind: FieldKind.OBJECT, required: ${required}, array: ${array}, ` +
+      `enumValues: null, enumDoc: null, example: null, instruction: null, nested: null }` +
+      ` /* FR-010: nested prompt deferred */`
+    );
+  }
+
+  const example = optStringAttr(field, FIELD_ATTR_EXAMPLE);
+  const instruction = optStringAttr(field, FIELD_ATTR_INSTRUCTION);
+
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const valuesLit = stringArrayLiteral(enumValues(field));
+    const enumDocLit = propertiesMapLiteral(field.ownAttr(FIELD_ATTR_ENUM_DOC));
+    return (
+      `{ name: ${name}, kind: FieldKind.ENUM, required: ${required}, array: ${array}, ` +
+      `enumValues: ${valuesLit}, enumDoc: ${enumDocLit}, example: ${example}, ` +
+      `instruction: ${instruction}, nested: null }`
+    );
+  }
+
+  const kind = scalarKind(field.subType) ?? "STRING";
+  return (
+    `{ name: ${name}, kind: FieldKind.${kind}, required: ${required}, array: ${array}, ` +
+    `enumValues: null, enumDoc: null, example: ${example}, instruction: ${instruction}, nested: null }`
+  );
+}
+
+function optStringAttr(field: MetaData, attrName: string): string {
+  const v = field.ownAttr(attrName);
+  return typeof v === "string" ? jsonStringLiteral(v) : "null";
+}

package/src/templates/output-parser.ts

@@ -17,7 +17,14 @@ import {
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_OBJECT_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_FORMAT,
 } from "@metaobjectsdev/metadata";
+import {
+  schemaLiteral,
+  mirrorInterface,
+  mirrorInitializer,
+} from "./recover-schema-emitter.js";
+import { recoverMapHelpersUsed } from "./fr010-field-mapping.js";
 
 const SCALAR_ZOD: Record<string, string> = {
   string: "z.string()",
@@ -103,9 +110,14 @@ export function renderOutputParser(root: MetaData, templateName: string): string
   const parseName = `parse${templateName}`;
   const safeParseName = `safeParse${templateName}`;
 
-  return `import { z } from "zod";
+  // FR-010: emit the tolerant recover() API alongside the strict Zod parser when the
+  // template targets json/xml. The @payloadRef already resolved to a value-object above,
+  // so a RecoverSchema can always be baked. text-format outputs get no recover.
+  const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
+  const lc = format.toLowerCase();
+  const emitRecover = lc === "json" || lc === "xml";
 
-const ${schemaName} = ${schema};
+  const strictBody = `const ${schemaName} = ${schema};
 
 export type ${dataName} = z.infer<typeof ${schemaName}>;
 export type ${errorName} = z.ZodError;
@@ -140,4 +152,67 @@ export function ${safeParseName}(
     : { success: false, error: result.error };
 }
 `;
+
+  if (!emitRecover) {
+    return `import { z } from "zod";\n\n${strictBody}`;
+  }
+
+  // ---- FR-010 tolerant recover block (json/xml only) ----
+  const recoveredName = `${templateName}Recovered`;
+  const recoverFnName = `recover${templateName}`;
+  const tryRecoverName = `tryRecover${templateName}`;
+  const schemaConstName = `${templateName}RecoverSchema`;
+  const schemaLit = schemaLiteral(vo, format, payloadRef);
+  const mirrorDecl = mirrorInterface(vo, recoveredName);
+  const initializer = mirrorInitializer(vo);
+  const mapHelpers = recoverMapHelpersUsed(vo);
+
+  // Render-package imports the recover block needs. Only pull in the names the emitted
+  // source actually references, so the file has no unused imports (tsc noUnusedLocals-safe).
+  const renderImports = ["recover", "recoverSchema", "Format"];
+  if (schemaLit.includes("scalar(")) renderImports.push("scalar");
+  if (schemaLit.includes("enumField(")) renderImports.push("enumField");
+  if (schemaLit.includes("FieldKind.")) renderImports.push("FieldKind");
+  renderImports.push("type RecoverSchema", "type RecoverOptions", "type RecoveryResult");
+  renderImports.push(...mapHelpers);
+
+  const recoverBody = `/** Baked recover descriptor for the ${templateName} output. */
+const ${schemaConstName}: RecoverSchema = ${schemaLit};
+
+${mirrorDecl}
+
+/**
+ * Tolerant best-effort recovery of a dirty LLM response; never throws. Returns a
+ * nullable mirror (\`${recoveredName}\`) with fields null where lost/malformed,
+ * plus the per-field recovery report.
+ */
+export function ${recoverFnName}(
+  text: string,
+  opts?: RecoverOptions,
+): RecoveryResult<${recoveredName}> {
+  const outcome = recover(text, ${schemaConstName}, opts);
+  const d = outcome.data;
+  const data: ${recoveredName} = ${initializer};
+  return { data, report: outcome.report };
+}
+
+/**
+ * Recovery as a bool gate: \`true\` when the response was non-empty and no required
+ * field was lost. On success, \`result\` carries the recovered mirror + report.
+ */
+export function ${tryRecoverName}(
+  text: string,
+): { ok: boolean; result: RecoveryResult<${recoveredName}> } {
+  const result = ${recoverFnName}(text);
+  const ok = !result.report.isEmpty() && !result.report.hasLostRequired();
+  return { ok, result };
+}
+`;
+
+  return (
+    `import { z } from "zod";\n` +
+    `import {\n  ${renderImports.join(",\n  ")},\n} from "@metaobjectsdev/render";\n\n` +
+    `${strictBody}\n` +
+    `${recoverBody}`
+  );
 }

package/src/templates/output-prompt.ts

@@ -0,0 +1,88 @@
+// server/typescript/packages/codegen-ts/src/templates/output-prompt.ts
+//
+// Per-template renderer for the FR-010 artifact-1 output-format prompt fragment
+// ("produce your answer like this"). For each json/xml `template.output` whose
+// @payloadRef resolves to a value-object, emits a `<TemplateName>.prompt.ts` file
+// exporting `render<TemplateName>Format(overrides?)` backed by the render engine's
+// renderOutputFormat(). The baked OutputFormatSpec's rootName is the payload name,
+// so the prompt fragment and the recover() codegen agree on the root name.
+//
+// Mirrors the C# OutputPromptGenerator + OutputFormatSpecEmitter (split into a
+// generator factory + this pure renderer, matching the TS output-parser shape).
+
+import {
+  type MetaData,
+  TYPE_OBJECT,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_FORMAT,
+} from "@metaobjectsdev/metadata";
+import { specLiteral } from "./output-format-spec-emitter.js";
+
+function findObject(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+}
+
+function findTemplate(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+}
+
+/** True iff the template.output's @format is json or xml (the renderable structured formats). */
+export function templateSupportsPrompt(tmpl: MetaData): boolean {
+  const f = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  return f === "json" || f === "xml";
+}
+
+/**
+ * Render the full output-prompt file for one json/xml `template.output` node.
+ * Throws if the template isn't found, isn't a template.output, isn't json/xml,
+ * or its @payloadRef doesn't resolve to an object.value.
+ */
+export function renderOutputPrompt(root: MetaData, templateName: string): string {
+  const tmpl = findTemplate(root, templateName);
+  if (!tmpl) {
+    throw new Error(`template "${templateName}" not found in metadata root`);
+  }
+  if (tmpl.subType !== TEMPLATE_SUBTYPE_OUTPUT) {
+    throw new Error(`template "${templateName}" is not a template.output (got subtype "${tmpl.subType}")`);
+  }
+  if (!templateSupportsPrompt(tmpl)) {
+    throw new Error(`template "${templateName}" @format is not json/xml — no prompt fragment`);
+  }
+  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  if (typeof payloadRef !== "string") {
+    throw new Error(`template "${templateName}" missing @payloadRef`);
+  }
+  const vo = findObject(root, payloadRef);
+  if (!vo) {
+    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
+  }
+
+  // rootName == payload name so the prompt fragment and recover() agree.
+  const spec = specLiteral(vo, tmpl, payloadRef);
+  const specName = `${templateName}FormatSpec`;
+  const fnName = `render${templateName}Format`;
+
+  return `import {
+  renderOutputFormat,
+  Format,
+  FieldKind,
+  PromptStyle,
+  type OutputFormatSpec,
+  type PromptOverrides,
+} from "@metaobjectsdev/render";
+
+const ${specName}: OutputFormatSpec = ${spec};
+
+/**
+ * The output-format instruction fragment for the ${templateName} template.output
+ * ("produce your answer like this"). Comment-free — guidance lives in prose /
+ * inline placeholders / a filled skeleton. Pass \`overrides\` to override the style
+ * or per-field example/instruction at render time.
+ */
+export function ${fnName}(overrides?: PromptOverrides): string {
+  return renderOutputFormat(${specName}, overrides ?? {});
+}
+`;
+}

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

@@ -0,0 +1,91 @@
+// server/typescript/packages/codegen-ts/src/templates/recover-schema-emitter.ts
+//
+// Turns a payload value-object into TS source fragments for the FR-010 recover codegen:
+//   • schemaLiteral     — a `recoverSchema(Format.JSON, "root", [ … ])` baked descriptor
+//                         built from FieldSpec factories (scalar / enumField).
+//   • mirrorInterface   — an all-nullable mirror interface `<Payload>Recovered` (each
+//                         component `T | null`); recover 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# RecoverSchemaEmitter (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,
+  recoverMapCall,
+  enumValues,
+  jsonStringLiteral,
+  stringArrayLiteral,
+  propertiesMapLiteral,
+} from "./fr010-field-mapping.js";
+
+/** Emit `recoverSchema(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(fieldSpecLiteral);
+  return `recoverSchema(${formatEnum}, ${jsonStringLiteral(rootName)}, [${specs.join(", ")}])`;
+}
+
+function fieldSpecLiteral(field: 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));
+    // enumField() sets array:false; enum-array is a bounded deferral (parity with Java/C#).
+    return `enumField(${name}, ${required}, ${valuesLit}, ${aliasLit})`;
+  }
+
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    // FR-010: nested recover deferred — treat as an opaque required/optional string slot.
+    return `scalar(${name}, FieldKind.STRING, ${required}) /* FR-010: nested recover 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
+  // recover() actually populates the array at runtime (RecoverMap.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("Recovered")
+    ? interfaceName.slice(0, -"Recovered".length)
+    : interfaceName;
+  const lines: string[] = [];
+  lines.push(
+    `/** Best-effort recovered 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}: ${recoverMapCall(f)}`);
+  return `{ ${assigns.join(", ")} }`;
+}