@metaobjectsdev/codegen-ts 0.7.0 → 0.8.0

package/src/generators/output-prompt-file.ts

@@ -0,0 +1,66 @@
+// server/typescript/packages/codegen-ts/src/generators/output-prompt-file.ts
+//
+// FR-010 stock generator that emits one <TemplateName>.prompt.ts file per json/xml
+// template.output node — the output-format prompt fragment ("produce your answer
+// like this"). Wraps renderOutputPrompt() from templates/output-prompt.ts. Skips
+// text-format outputs and outputs whose @payloadRef doesn't resolve to a value-object
+// (same contract as the output-parser generator).
+//
+// Consumer wiring (metaobjects.config.ts):
+//   generators: [..., promptRender(), outputParser(), outputPrompt()]
+//
+// Custom output directory:
+//   generators: [..., outputPrompt({ outDir: "src/generated/outputs" })]
+
+import {
+  TYPE_OBJECT,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+} from "@metaobjectsdev/metadata";
+import {
+  type EmittedFile,
+  type Generator,
+  type GeneratorFactory,
+  oncePerRun,
+} from "../generator.js";
+import { renderOutputPrompt, templateSupportsPrompt } from "../templates/output-prompt.js";
+
+export interface OutputPromptOpts {
+  /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+  outDir?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Generator {
+  const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+  const generator: Generator = {
+    name: "output-prompt",
+    generate: oncePerRun((_entities, ctx) => {
+      const root = ctx.loadedRoot;
+      const outputs = root
+        .ownChildren()
+        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
+      const files: EmittedFile[] = [];
+      for (const t of outputs) {
+        // Only json/xml outputs get a renderable prompt fragment.
+        if (!templateSupportsPrompt(t)) continue;
+        // @payloadRef must resolve to a value-object (same contract as the parser).
+        const payloadRef = t.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+        if (typeof payloadRef !== "string") continue;
+        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
+        if (!vo) continue;
+        files.push({
+          path: `${dirPrefix}${t.name}.prompt.ts`,
+          content: renderOutputPrompt(root, t.name),
+        });
+      }
+      return files;
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<OutputPromptOpts>;

package/src/index.ts

@@ -44,6 +44,7 @@ export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpeci
 export type { OutputLayout, ResolvedTarget } from "./import-path.js";
 
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
+export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
 export type { ExtractContext } from "./projection/extract-view-spec.js";
 export { emitViewDdl } from "./projection/view-ddl-emit.js";

package/src/instance-artifacts.ts

@@ -0,0 +1,61 @@
+// Framework-level guard shared by every generator that emits INSTANCE / WRITE
+// artifacts (write forms, CRUD hooks, grid columns, grid hooks, …).
+//
+// Two MetaData concepts make an entity *not* a source of instance artifacts:
+//
+//   1. Abstract (`@isAbstract: true`) — a fundamental MetaData concept: an
+//      abstract type contributes shape via inheritance ONLY. It never has an
+//      instantiable representation, so it must never produce a write form,
+//      CRUD hooks, columns, a grid, or any instance artifact. It still gets a
+//      type-only interface from the entity-file generator (so subclasses and
+//      consumers can reference its shape), but nothing that points at an
+//      `<E>Insert` schema / `$table` / mutation hook it does not have.
+//
+//   2. Projection (read-only view; see `isProjection`) — instantiable for READ
+//      but never for WRITE. It legitimately gets read models + read-only hooks
+//      + grids, but NOT a write form. WRITE-only generators (forms) reuse
+//      `emitsWriteArtifacts` to skip these; read-capable generators (tanstack
+//      hooks/grids) instead branch internally on `isProjection`.
+//
+// Centralizing these as `emitsInstanceArtifacts` / `emitsWriteArtifacts` keeps
+// the rule in one place: a generator composes the matching guard into its
+// `filter` rather than re-deriving "is this abstract / read-only" ad hoc.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { isProjection } from "./projection/projection-detector.js";
+
+/**
+ * True when `entity` is abstract (`@isAbstract: true`).
+ *
+ * Thin, framework-level accessor so generators in sibling codegen packages
+ * have a single import surface for the abstract concept and don't reach into
+ * metadata internals (mirrors how `isProjection` is the shared read-only
+ * discriminator). Abstract types contribute shape via inheritance only.
+ */
+export function isAbstract(entity: MetaData): boolean {
+  return entity.isAbstract === true;
+}
+
+/**
+ * True when `entity` should produce INSTANCE artifacts of ANY kind (read OR
+ * write): CRUD/read hooks, grid columns, grid hooks. Abstract types are
+ * excluded — they have no instantiable representation.
+ *
+ * Read-capable generators (tanstack hooks/grids) compose this so they skip
+ * abstract bases while still serving projections via their own
+ * `isProjection` read-only branch.
+ */
+export function emitsInstanceArtifacts(entity: MetaData): boolean {
+  return !isAbstract(entity);
+}
+
+/**
+ * True when `entity` should produce WRITE artifacts (write forms, mutation
+ * surfaces). Excludes both abstract types (no instance at all) and projections
+ * (read-only views — instantiable for read, never for write).
+ *
+ * WRITE-only generators (e.g. the React form generator) compose this.
+ */
+export function emitsWriteArtifacts(entity: MetaData): boolean {
+  return !isAbstract(entity) && !isProjection(entity);
+}

package/src/metaobjects-config.ts

@@ -37,6 +37,15 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix?: string;
+  /**
+   * Whether abstract entities (`@isAbstract: true`) emit their shape artifact
+   * (the type-only interface / value-object file from the entity-file
+   * generator). Defaults to `true`. Instance/write artifacts (forms, CRUD/read
+   * hooks, grids) are NEVER emitted for abstract entities regardless of this
+   * flag — that invariant lives in `instance-artifacts.ts`. This knob only
+   * governs the shape, mirroring the cross-port `emitAbstractShapes` option.
+   */
+  emitAbstractShapes?: boolean;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -57,6 +66,7 @@ export interface MetaobjectsGenConfig extends ResolvedGenConfig {
 export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets"> {
   columnNamingStrategy: ColumnNamingStrategy;
   apiPrefix: string;
+  emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
   targets: Record<string, ResolvedTarget>;
 }
@@ -98,6 +108,7 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     ...config,
     columnNamingStrategy: config.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY,
     apiPrefix: config.apiPrefix ?? "",
+    emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",
     targets: resolveTargets(config),
   };

package/src/render-context.ts

@@ -39,6 +39,8 @@ export interface RenderContext {
   columnNamingStrategy: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
+  /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
+  emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
   /** The target THIS generator emits to (drives path layout + same-target imports). */
@@ -53,11 +55,12 @@ export interface RenderContext {
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
   apiPrefix?: string;
+  emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
   selfTarget?: ResolvedTarget;
@@ -85,6 +88,7 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     omImport: opts.omImport ?? "../index",
     columnNamingStrategy: opts.columnNamingStrategy ?? "snake_case",
     apiPrefix: opts.apiPrefix ?? "",
+    emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
     selfTarget: defaultTarget,

package/src/runner.ts

@@ -155,6 +155,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       extStyle: config.extStyle,
       columnNamingStrategy: config.columnNamingStrategy,
       apiPrefix: config.apiPrefix,
+      emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
       pkMap,
       relationMap,

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}`
+  );
 }