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

package/src/templates/output-parser.ts

@@ -21,10 +21,17 @@ import {
 } from "@metaobjectsdev/metadata";
 import {
   schemaLiteral,
-  mirrorInterface,
   mirrorInitializer,
-} from "./recover-schema-emitter.js";
-import { recoverMapHelpersUsed } from "./fr010-field-mapping.js";
+} from "./extract-schema-emitter.js";
+import { extractMapHelpersUsed } from "./fr010-field-mapping.js";
+import {
+  nestedMirrorInterfaces,
+  nestedMappers,
+  rootMapperName,
+  delegateHelpers,
+  usedHelpers,
+  hasNested,
+} from "./extract-delegate-emitter.js";
 
 const SCALAR_ZOD: Record<string, string> = {
   string: "z.string()",
@@ -110,12 +117,12 @@ export function renderOutputParser(root: MetaData, templateName: string): string
   const parseName = `parse${templateName}`;
   const safeParseName = `safeParse${templateName}`;
 
-  // FR-010: emit the tolerant recover() API alongside the strict Zod parser when the
+  // FR-010: emit the tolerant extract() 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.
+  // so a ExtractSchema can always be baked. text-format outputs get no extract.
   const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
   const lc = format.toLowerCase();
-  const emitRecover = lc === "json" || lc === "xml";
+  const emitExtractLenient = lc === "json" || lc === "xml";
 
   const strictBody = `const ${schemaName} = ${schema};
 
@@ -153,66 +160,132 @@ export function ${safeParseName}(
 }
 `;
 
-  if (!emitRecover) {
+  if (!emitExtractLenient) {
     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`;
+  // ---- FR-010 tolerant extract block (json/xml only) ----
+  const extractedName = `${templateName}Extracted`;
+  const extractLenientFnName = `extractLenient${templateName}`;
+  const tryExtractLenientName = `tryExtractLenient${templateName}`;
+  const extractLenientWithName = `extractLenient${templateName}WithLoader`;
+  const schemaConstName = `${templateName}ExtractSchema`;
+  const payloadFqnConst = `${templateName.toUpperCase()}_PAYLOAD_NAME`;
+  const formatEnum = format.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
   const schemaLit = schemaLiteral(vo, format, payloadRef);
-  const mirrorDecl = mirrorInterface(vo, recoveredName);
   const initializer = mirrorInitializer(vo);
-  const mapHelpers = recoverMapHelpersUsed(vo);
+  const mapHelpers = extractMapHelpersUsed(vo);
+
+  // The nullable mirror is shared by BOTH extract paths. Use the nested-aware emitter so the
+  // payload mirror's nested-object / array-of-object components are typed (not `unknown`), and
+  // so a mirror interface is emitted for every reachable nested value-object. The payload mirror
+  // keeps the canonical `<Template>Extracted` name (instead of `<PayloadVO>Extracted`) so the
+  // existing self-contained extract<Name>() initializer continues to satisfy it.
+  const mirrorDecls = nestedMirrorInterfaces(vo, root, extractedName);
+  const payloadHasNested = hasNested(vo, root);
 
-  // Render-package imports the recover block needs. Only pull in the names the emitted
+  // Render-package imports the extract 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"];
+  const renderImports = ["extract", "extractSchema", "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("type ExtractSchema", "type ExtractOptions", "type ExtractionResult");
   renderImports.push(...mapHelpers);
 
-  const recoverBody = `/** Baked recover descriptor for the ${templateName} output. */
-const ${schemaConstName}: RecoverSchema = ${schemaLit};
+  const selfContained = `/** Baked extract descriptor for the ${templateName} output. */
+const ${schemaConstName}: ExtractSchema = ${schemaLit};
 
-${mirrorDecl}
+${mirrorDecls}
 
 /**
- * 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.
+ * Self-contained tolerant best-effort extraction of a dirty LLM response; never throws.
+ * Returns a nullable mirror (\`${extractedName}\`) with fields null where lost/malformed,
+ * plus the per-field extraction report. Does NOT populate nested-object / array-of-object
+ * components (those stay null — the historical FR-010 gap). For full nested extraction, use
+ * \`${extractLenientWithName}(root, text)\`, which delegates to the runtime extract.
  */
-export function ${recoverFnName}(
+export function ${extractLenientFnName}(
   text: string,
-  opts?: RecoverOptions,
-): RecoveryResult<${recoveredName}> {
-  const outcome = recover(text, ${schemaConstName}, opts);
+  opts?: ExtractOptions,
+): ExtractionResult<${extractedName}> {
+  const outcome = extract(text, ${schemaConstName}, opts);
   const d = outcome.data;
-  const data: ${recoveredName} = ${initializer};
+  const data: ${extractedName} = ${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.
+ * Extraction as a bool gate: \`true\` when the response was non-empty and no required
+ * field was lost. On success, \`result\` carries the extracted mirror + report.
  */
-export function ${tryRecoverName}(
+export function ${tryExtractLenientName}(
   text: string,
-): { ok: boolean; result: RecoveryResult<${recoveredName}> } {
-  const result = ${recoverFnName}(text);
+): { ok: boolean; result: ExtractionResult<${extractedName}> } {
+  const result = ${extractLenientFnName}(text);
   const ok = !result.report.isEmpty() && !result.report.hasLostRequired();
   return { ok, result };
 }
 `;
 
+  // ---- Runtime-delegating extract (closes the nested gap) ----
+  // Resolves this payload's MetaObject from a loaded MetaRoot by its baked simple name and
+  // delegates to extractObject() in @metaobjectsdev/runtime-ts, which assembles the FULL nested
+  // object graph reflection-free. The assembled ValueObject graph is then mapped into the typed
+  // nullable mirror graph by the generated from<VO>Extracted mappers. Codegen-wrapping-runtime
+  // (a generated DAO calling the dynamic-metadata runtime) — mirrors the Java/Kotlin pilots.
+  //
+  // The baked PAYLOAD_NAME is the resolved payload VO's SIMPLE name (root.findObject matches on
+  // the object's `name`, not its FQN). The root mapper is named for the TEMPLATE (so it returns
+  // the canonically-named `<Template>Extracted` mirror); nested mappers use their VO names.
+  const payloadName = vo.name;
+  const rootMapper = rootMapperName(templateName);
+  const delegating = `
+/** Payload value-object name this parser extracts — resolved against a loaded MetaRoot at runtime. */
+export const ${payloadFqnConst} = ${JSON.stringify(payloadName)};
+
+${nestedMappers(vo, root, rootMapper, extractedName)}
+
+${delegateHelpers(usedHelpers(vo, root))}
+
+/**
+ * Runtime-delegating tolerant extraction; never throws. Unlike \`${extractLenientFnName}(text)\`, this FULLY
+ * populates nested-object and array-of-object components by delegating to the metadata-driven
+ * runtime \`extractObject\` (which assembles the whole graph reflection-free via the Phase A object
+ * model), then maps the assembled graph into the typed \`${extractedName}\` mirror.
+ *
+ * @param root a loaded MetaRoot (e.g. \`(await new MetaDataLoader().load(...)).root\`) that declares
+ *             the \`${payloadRef}\` value-object.
+ */
+export function ${extractLenientWithName}(
+  root: MetaRoot,
+  text: string,
+  opts?: Partial<ExtractOptions> | null,
+): ExtractionResult<${extractedName}> {
+  const mo = root.findObject(${payloadFqnConst});
+  if (mo === undefined) {
+    throw new Error(\`${extractLenientWithName}: payload "\${${payloadFqnConst}}" not found in the supplied MetaRoot\`);
+  }
+  const outcome = extractObject(mo, text, ${formatEnum}, opts);
+  return { data: ${rootMapper}(outcome.data), report: outcome.report };
+}
+`;
+
+  // The delegating overload needs runtime-ts (extractObject) + the MetaRoot type from metadata.
+  // It is always emitted (the gap-closing path), regardless of whether THIS payload has nested
+  // fields — a flat payload still benefits from the loader-driven path and keeps the API uniform.
+  void payloadHasNested;
+  const metadataImport = `import type { MetaRoot } from "@metaobjectsdev/metadata";\n`;
+  const runtimeImport = `import { extractObject } from "@metaobjectsdev/runtime-ts";\n`;
+
   return (
     `import { z } from "zod";\n` +
-    `import {\n  ${renderImports.join(",\n  ")},\n} from "@metaobjectsdev/render";\n\n` +
+    `import {\n  ${renderImports.join(",\n  ")},\n} from "@metaobjectsdev/render";\n` +
+    metadataImport +
+    runtimeImport +
+    `\n` +
     `${strictBody}\n` +
-    `${recoverBody}`
+    `${selfContained}\n` +
+    `${delegating}`
   );
 }

package/src/templates/output-prompt.ts

@@ -5,7 +5,7 @@
 // @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.
+// so the prompt fragment and the extract() 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).
@@ -59,7 +59,7 @@ export function renderOutputPrompt(root: MetaData, templateName: string): string
     throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
   }
 
-  // rootName == payload name so the prompt fragment and recover() agree.
+  // rootName == payload name so the prompt fragment and extract() agree.
   const spec = specLiteral(vo, tmpl, payloadRef);
   const specName = `${templateName}FormatSpec`;
   const fnName = `render${templateName}Format`;

package/src/templates/render-helper.ts

@@ -0,0 +1,244 @@
+// server/typescript/packages/codegen-ts/src/templates/render-helper.ts
+//
+// Per-template.output render helper: emits a typed `render<Name>(payload, provider)`
+// that wraps the EXISTING render() engine, AND enforces the mustache↔payload-VO
+// drift check (the EXISTING verify() engine) at BUILD time.
+//
+// Two shapes, keyed off @kind:
+//   • document (default) → renders @textRef in @format → one string.
+//   • email              → renders @subjectRef + @htmlBodyRef (+ optional
+//                           @textBodyRef) → a structured EmailDocument.
+//
+// The headline is the BUILD-TIME drift gate: BEFORE emitting, every referenced
+// mustache is resolved via the codegen-time provider and verify()'d against the
+// payload field tree. If a referenced text is unresolvable OR carries any
+// NON-warning verify error (e.g. `{{field}}` not on the payload VO), this THROWS
+// and FAILS codegen — naming the template, the ref, the error code, and the
+// offending field. This is what makes the build fail when a mustache references
+// a field the payload VO doesn't declare.
+//
+// Reuse, not reimplementation:
+//   • render()  — the runtime helper delegates to it (emitted call).
+//   • verify()  — run here at build time for the drift gate.
+//   • derivePayloadFieldTree (replicated minimally below — codegen-ts must NOT
+//     depend on the cli package; the walk is the same as cli's payload-field-tree).
+//   • PayloadField — the verify() field-tree shape; serialized into the emitted
+//     `verify:` literal so render()'s runtime drift check runs too.
+
+import {
+  type MetaData,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_TEMPLATE,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_TEXT_REF,
+  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_MAX_CHARS,
+  TEMPLATE_ATTR_KIND,
+  TEMPLATE_KIND_EMAIL,
+  TEMPLATE_KIND_DEFAULT,
+  TEMPLATE_ATTR_SUBJECT_REF,
+  TEMPLATE_ATTR_HTML_BODY_REF,
+  TEMPLATE_ATTR_TEXT_BODY_REF,
+} from "@metaobjectsdev/metadata";
+import {
+  verify,
+  ERR_REQUIRED_SLOT_UNUSED,
+  type Provider,
+  type PayloadField,
+  type VerifyError,
+} from "@metaobjectsdev/render";
+
+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);
+}
+
+/**
+ * Walk an `object.value` view-object into a render `PayloadField[]`. Object-ref
+ * fields recurse into their referenced view-object; a `seen` set guards a
+ * (pathological) reference cycle. Replicates cli's `derivePayloadFieldTree` —
+ * codegen-ts must not depend on the cli package (wrong layer / would cycle), so
+ * the same small walk lives here against the metadata constants codegen-ts
+ * already imports.
+ */
+function derivePayloadFieldTree(
+  root: MetaData,
+  voName: string,
+  seen: ReadonlySet<string> = new Set(),
+): PayloadField[] {
+  if (seen.has(voName)) return [];
+  const vo = findObject(root, voName);
+  if (!vo) return [];
+  const nextSeen = new Set(seen).add(voName);
+  const fields: PayloadField[] = [];
+  for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
+    if (f.subType === FIELD_SUBTYPE_OBJECT) {
+      const ref = f.ownAttr(FIELD_ATTR_OBJECT_REF);
+      if (typeof ref === "string") {
+        fields.push({ name: f.name, fields: derivePayloadFieldTree(root, ref, nextSeen) });
+        continue;
+      }
+    }
+    fields.push({ name: f.name });
+  }
+  return fields;
+}
+
+/** Serialize a PayloadField[] as a stable, deterministic TS array literal so the
+ *  emitted render() call runs the same runtime drift check the build gate ran. */
+function fieldTreeLiteral(fields: PayloadField[]): string {
+  // JSON.stringify is deterministic for this shape (no functions/cycles by
+  // construction) and produces valid TS object/array literal syntax.
+  return JSON.stringify(fields);
+}
+
+/** Run the build-time drift gate for one referenced mustache. Throws (fails
+ *  codegen) when the ref is unresolvable OR verify() reports a non-warning error.
+ *  Warnings (ERR_REQUIRED_SLOT_UNUSED) are tolerated. */
+function gateRef(
+  templateName: string,
+  ref: string,
+  provider: Provider,
+  fields: PayloadField[],
+): void {
+  const text = provider.resolve(ref);
+  if (text === undefined) {
+    throw new Error(
+      `render-helper drift: template "${templateName}" ref "${ref}" — unresolved (provider returned no text)`,
+    );
+  }
+  const errors: VerifyError[] = verify(text, fields, { provider }).filter(
+    (e) => e.code !== ERR_REQUIRED_SLOT_UNUSED,
+  );
+  if (errors.length > 0) {
+    const e = errors[0]!;
+    throw new Error(
+      `render-helper drift: template "${templateName}" ref "${ref}" — ${e.code}: {{${e.path}}} not on payload VO`,
+    );
+  }
+}
+
+/**
+ * Render the per-template render-helper source for one `template.output`, AND
+ * run the build-time drift gate first. Throws if: the template isn't found /
+ * isn't a template.output; @payloadRef is missing or doesn't resolve to an
+ * object.value; a required ref for the kind is missing; or ANY referenced
+ * mustache drifts from the payload VO (the headline build gate).
+ *
+ * @param provider the codegen-time provider (e.g. projectProvider(projectRoot))
+ *                 used to resolve + verify each referenced mustache at build time.
+ */
+export function renderRenderHelper(
+  root: MetaData,
+  templateName: string,
+  provider: Provider,
+): 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}")`,
+    );
+  }
+  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`,
+    );
+  }
+
+  const fields = derivePayloadFieldTree(root, payloadRef);
+  const ft = fieldTreeLiteral(fields);
+  const fnName = `render${templateName}`;
+
+  const kind = ((tmpl.ownAttr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT)
+    .toLowerCase();
+
+  if (kind === TEMPLATE_KIND_EMAIL) {
+    const subjectRef = tmpl.ownAttr(TEMPLATE_ATTR_SUBJECT_REF);
+    const htmlBodyRef = tmpl.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF);
+    const textBodyRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_BODY_REF);
+    if (typeof subjectRef !== "string") {
+      throw new Error(`template "${templateName}" (email) missing @subjectRef`);
+    }
+    if (typeof htmlBodyRef !== "string") {
+      throw new Error(`template "${templateName}" (email) missing @htmlBodyRef`);
+    }
+
+    // BUILD-TIME drift gate — every email part-ref is resolved + verified.
+    gateRef(templateName, subjectRef, provider, fields);
+    gateRef(templateName, htmlBodyRef, provider, fields);
+    if (typeof textBodyRef === "string") {
+      gateRef(templateName, textBodyRef, provider, fields);
+    }
+
+    const textBodyLine =
+      typeof textBodyRef === "string"
+        ? `\n    textBody: render({ ref: ${JSON.stringify(textBodyRef)}, payload, format: "text", provider, verify: ${ft} }),`
+        : "";
+
+    return `import { render } from "@metaobjectsdev/render";
+import type { Provider, EmailDocument } from "@metaobjectsdev/render";
+import type { ${payloadRef} } from "./payloads.js";
+
+/**
+ * Render the ${templateName} email (subject + html body${typeof textBodyRef === "string" ? " + text body" : ""}) from a
+ * typed ${payloadRef} payload. Wraps the render() engine; the payload field tree is
+ * baked in so render()'s runtime drift check matches the build-time gate.
+ */
+export function ${fnName}(payload: ${payloadRef}, provider: Provider): EmailDocument {
+  return {
+    subject: render({ ref: ${JSON.stringify(subjectRef)}, payload, format: "text", provider, verify: ${ft} }),
+    htmlBody: render({ ref: ${JSON.stringify(htmlBodyRef)}, payload, format: "html", provider, verify: ${ft} }),${textBodyLine}
+  };
+}
+`;
+  }
+
+  // --- document kind ---
+  const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+  if (typeof textRef !== "string") {
+    throw new Error(`template "${templateName}" (document) missing @textRef`);
+  }
+  const format = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  const maxCharsAttr = tmpl.ownAttr(TEMPLATE_ATTR_MAX_CHARS);
+  const maxChars =
+    typeof maxCharsAttr === "number"
+      ? maxCharsAttr
+      : typeof maxCharsAttr === "string" && maxCharsAttr.trim() !== ""
+        ? Number(maxCharsAttr)
+        : undefined;
+
+  // BUILD-TIME drift gate.
+  gateRef(templateName, textRef, provider, fields);
+
+  const maxCharsArg =
+    maxChars !== undefined && Number.isFinite(maxChars) ? `, maxChars: ${maxChars}` : "";
+
+  return `import { render } from "@metaobjectsdev/render";
+import type { Provider } from "@metaobjectsdev/render";
+import type { ${payloadRef} } from "./payloads.js";
+
+/**
+ * Render the ${templateName} document from a typed ${payloadRef} payload. Wraps the
+ * render() engine; the payload field tree is baked in so render()'s runtime drift
+ * check matches the build-time gate enforced when this file was generated.
+ */
+export function ${fnName}(payload: ${payloadRef}, provider: Provider): string {
+  return render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(format)}, provider, verify: ${ft}${maxCharsArg} });
+}
+`;
+}

package/src/templates/zod-validators.ts

@@ -15,11 +15,13 @@ import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
   FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP,
-  FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT, FIELD_SUBTYPE_UUID,
   VALIDATOR_SUBTYPE_REQUIRED, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_ARRAY,
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   FIELD_ATTR_REQUIRED, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT,
-  FIELD_ATTR_AUTO_SET, FIELD_ATTR_OBJECT_REF, AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
+  FIELD_ATTR_AUTO_SET, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_READ_ONLY,
+  AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
 } from "@metaobjectsdev/metadata";
@@ -57,6 +59,10 @@ export function renderInsertSchemaOnly(obj: MetaObject): Code {
   const insertFieldLines: Code[] = [];
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
+    // FR-013: @readOnly fields are populated by DB / replication / external
+    // owner; the application has no path to write them. Exclude from the
+    // create-shape schema entirely.
+    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
@@ -88,6 +94,11 @@ export function renderZodValidators(obj: MetaObject): Code {
   const updateFieldLines: Code[] = [];
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
+    // FR-013: @readOnly fields appear in neither InsertSchema nor UpdateSchema.
+    // The DB / trigger / replication owns the write path; the app must not
+    // pass these values in POST/PATCH bodies (routesFile enforces the same
+    // contract at the boundary with a 400 response).
+    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
 
     const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
 
@@ -180,6 +191,7 @@ function zodFieldExpr(field: MetaField): Code {
       break;
     }
     case FIELD_SUBTYPE_STRING:
+    case FIELD_SUBTYPE_UUID:
     default:
       baseStr = "z.string()";
       break;
@@ -200,12 +212,28 @@ function fieldWillBeOptional(field: MetaField): boolean {
   return !isRequired || hasDefault;
 }
 
-/** Append .min/.max/.regex/.optional() based on field-level validators + required state. */
+/** Numeric field subtypes whose Zod base is `z.number()` — value bounds apply. */
+const NUMERIC_FIELD_SUBTYPES = new Set<string>([
+  FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
+]);
+
+/** Append .min/.max/.regex/.optional() based on field-level validators + required state.
+ *
+ * Bound semantics by field shape:
+ *  - string (scalar)        → .min/.max = character count (validator.length + @maxLength)
+ *  - numeric (scalar)       → .min/.max = numeric value     (validator.numeric)
+ *  - array (any element)    → .min/.max = element count     (validator.array)
+ */
 function appendValidatorChain(base: Code, field: MetaField): Code {
   let isRequired = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
   let maxLen: number | undefined = field.ownAttr(FIELD_ATTR_MAX_LENGTH) as number | undefined;
   let minLen: number | undefined;
   let pattern: string | undefined;
+  let numMin: number | undefined;
+  let numMax: number | undefined;
+  let arrMin: number | undefined;
+  let arrMax: number | undefined;
   for (const child of field.validators()) {
     if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) isRequired = true;
     if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
@@ -218,14 +246,33 @@ function appendValidatorChain(base: Code, field: MetaField): Code {
       const p = child.ownAttr(VALIDATOR_ATTR_PATTERN);
       if (typeof p === "string") pattern = p;
     }
+    if (child.subType === VALIDATOR_SUBTYPE_NUMERIC) {
+      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = child.ownAttr(VALIDATOR_ATTR_MIN);
+      if (typeof max === "number") numMax = max;
+      if (typeof min === "number") numMin = min;
+    }
+    if (child.subType === VALIDATOR_SUBTYPE_ARRAY) {
+      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = child.ownAttr(VALIDATOR_ATTR_MIN);
+      if (typeof max === "number") arrMax = max;
+      if (typeof min === "number") arrMin = min;
+    }
   }
 
   let chain: Code = base;
-  if (field.subType === FIELD_SUBTYPE_STRING && !field.isArray) {
+  // Array element-count bounds apply to the z.array(...) wrapper regardless of element type.
+  if (field.isArray) {
+    if (arrMin !== undefined) chain = code`${chain}.min(${arrMin})`;
+    if (arrMax !== undefined) chain = code`${chain}.max(${arrMax})`;
+  } else if (field.subType === FIELD_SUBTYPE_STRING) {
     if (minLen !== undefined) chain = code`${chain}.min(${minLen})`;
     else if (isRequired) chain = code`${chain}.min(1)`;
     if (maxLen !== undefined) chain = code`${chain}.max(${maxLen})`;
     if (pattern !== undefined) chain = code`${chain}.regex(new RegExp(${JSON.stringify(pattern)}))`;
+  } else if (NUMERIC_FIELD_SUBTYPES.has(field.subType)) {
+    if (numMin !== undefined) chain = code`${chain}.min(${numMin})`;
+    if (numMax !== undefined) chain = code`${chain}.max(${numMax})`;
   }
 
   // Fields with DB-level defaults are optional in the InsertSchema: the caller

package/dist/templates/recover-schema-emitter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recover-schema-emitter.d.ts","sourceRoot":"","sources":["../../src/templates/recover-schema-emitter.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,QAAQ,EAId,MAAM,0BAA0B,CAAC;AAclC,yDAAyD;AACzD,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIpF;AA+BD,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAc3E;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAGtD"}

package/dist/templates/recover-schema-emitter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recover-schema-emitter.js","sourceRoot":"","sources":["../../src/templates/recover-schema-emitter.ts"],"names":[],"mappings":"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"}