@metaobjectsdev/codegen-ts 0.23.2 → 0.24.0

package/src/templates/output-parser.ts

@@ -13,13 +13,15 @@ import {
   type MetaData,
   TYPE_FIELD,
   TYPE_TEMPLATE,
-  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_PROMPT,
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_OBJECT_REF,
-  TEMPLATE_ATTR_PAYLOAD_REF,
-  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_RESPONSE_REF,
+  RESPONSE_FORMAT_XML,
   resolveObjectRef,
 } from "@metaobjectsdev/metadata";
+import { responseShape } from "./find-inbound.js";
+import { isRequired } from "./fr010-field-mapping.js";
 import {
   nestedMirrorInterfaces,
   nestedMappers,
@@ -53,7 +55,19 @@ function findTemplate(root: MetaData, name: string): MetaData | undefined {
   return root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
 }
 
-/** Render the Zod expression for a single field; recurses on @objectRef. */
+/** Render the Zod expression for a single field; recurses on @objectRef.
+ *
+ * Optionality comes from `@required`, via the SAME `isRequired` predicate the
+ * tolerant tier uses — so the two tiers in this file cannot disagree about what
+ * the contract is. They used to: this schema emitted every field as mandatory
+ * and never read `@required`, so `parse<Name>` threw on a reply that correctly
+ * omitted a declared-optional field, while the tolerant extract accepted it.
+ *
+ * Every other port reuses the payload VO, which #309 made `@required`-correct.
+ * TypeScript re-derives its schema inline here, which is how it drifted — the
+ * same "payload tier disagrees with the rest of the toolchain" shape ADR-0052
+ * came out of.
+ */
 function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, depth: number): string {
   // isArray is a native (reserved) property on MetaData, not an attr.
   const isArray = field.resolvedIsArray();
@@ -73,7 +87,10 @@ function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, de
   } else {
     base = SCALAR_ZOD[field.subType] ?? "z.unknown()";
   }
-  return isArray ? `z.array(${base})` : base;
+  const shaped = isArray ? `z.array(${base})` : base;
+  // `.optional()` wraps the ARRAY, not its element: an absent list and a list of
+  // absent things are different claims.
+  return isRequired(field) ? shaped : `${shaped}.optional()`;
 }
 
 /** Render a `z.object({ ... })` for an object.value node.
@@ -90,28 +107,34 @@ function renderObjectSchema(vo: MetaData, root: MetaData, seen: ReadonlySet<stri
 }
 
 /**
- * Render the full output-parser file for one `template.output` node.
- * Throws if the template isn't found, isn't a template.output, or its
- * @payloadRef doesn't resolve to an object.value.
+ * Render the full response-parser file for one responding `template.prompt`.
+ * Throws if the template isn't found, isn't a template.prompt, or its
+ * @responseRef is missing / doesn't resolve to an object.value.
+ *
+ * ADR-0052: the shape parsed INTO is `@responseRef`, not `@payloadRef` —
+ * `@payloadRef` types the REQUEST rendered outbound, which is the distinction the
+ * trace helper has always drawn ("@responseRef types the result; @payloadRef types
+ * the request") and the inbound tier used to ignore.
  */
 export function renderOutputParser(root: MetaData, templateName: string, ctx?: RenderContext): 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}")`);
-  }
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-  if (typeof payloadRef !== "string") {
-    throw new Error(`template "${templateName}" missing @payloadRef`);
+  if (tmpl.subType !== TEMPLATE_SUBTYPE_PROMPT) {
+    throw new Error(`template "${templateName}" is not a template.prompt (got subtype "${tmpl.subType}")`);
   }
-  // ADR-0042: a bare @payloadRef resolves in the template's package.
-  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
-  if (!vo) {
-    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
+  const shape = responseShape(root, tmpl);
+  if (!shape) {
+    // ADR-0039: resolving — @responseRef may be inherited via extends.
+    const declared = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
+    throw new Error(
+      typeof declared === "string"
+        ? `template "${templateName}" @responseRef "${declared}" not found in metadata root`
+        : `template "${templateName}" missing @responseRef`,
+    );
   }
+  const { vo, ref: payloadRef } = shape;
 
   const schema = renderObjectSchema(vo, root, new Set([payloadRef]), 0);
   const schemaName = `${templateName}Schema`;
@@ -120,13 +143,31 @@ export function renderOutputParser(root: MetaData, templateName: string, ctx?: R
   const parseName = `parse${templateName}`;
   const safeParseName = `safeParse${templateName}`;
 
-  // 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 ExtractSchema can always be baked. text-format outputs get no extract.
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const format = (tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
-  const lc = format.toLowerCase();
-  const emitExtractLenient = lc === "json" || lc === "xml";
+  // FR-010: emit the tolerant extract() API alongside the strict Zod parser.
+  //
+  // ADR-0052/0053: a declared @responseRef ALWAYS gets the tolerant path, and the
+  // syntax comes from @responseFormat (json|xml, default json) — never from
+  // @format, which is the syntax of the rendered prompt BODY. The old json/xml
+  // gate on @format is what made a text-bodied prompt with a JSON reply emit a
+  // strict parser and no extract at all.
+  const format = shape.format;
+
+  // The strict Zod tier is JSON-ONLY, by construction.
+  //
+  // Its body is `Schema.parse(JSON.parse(text))`, and there is no XML equivalent to
+  // generate. Not because no XML reader exists — `render/src/extract/
+  // xml-forgiving-reader.ts` ships one — but because that reader is FORGIVING by
+  // design, and strict all-or-nothing semantics layered over a repairing parser is
+  // incoherent: it would throw or accept based on how much repair happened, which
+  // is not a contract anyone can reason about. The JS runtime's `JSON.parse` is an
+  // exact parser, which is what makes the strict tier meaningful for JSON and only
+  // for JSON. Before this, an XML template got `JSON.parse` anyway — a generated
+  // function that could never work.
+  //
+  // So an XML reply gets the tolerant extract and nothing else. Its typed shape is
+  // `<Name>Extracted` — a nullable mirror, which is the honest type for a
+  // best-effort parse of model output.
+  const emitStrict = format !== RESPONSE_FORMAT_XML;
 
   const strictBody = `const ${schemaName} = ${schema};
 
@@ -164,15 +205,14 @@ export function ${safeParseName}(
 }
 `;
 
-  if (!emitExtractLenient) {
-    return `import { z } from "zod";\n\n${strictBody}`;
-  }
-
-  // ---- FR-010 tolerant extract block (json/xml only) ----
+  // ---- FR-010 tolerant extract block ----
+  // Unconditional since ADR-0052: a declared @responseRef IS the request for the
+  // tolerant path, and @responseFormat is a closed json|xml set, so there is no
+  // longer a third case to gate on.
   const extractedName = `${templateName}Extracted`;
   const extractLenientWithName = `extractLenient${templateName}WithLoader`;
   const payloadFqnConst = `${templateName.toUpperCase()}_PAYLOAD_NAME`;
-  const formatEnum = format.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
+  const formatEnum = format === RESPONSE_FORMAT_XML ? "Format.XML" : "Format.JSON";
 
   // The nullable mirror is the return shape of the delegating extract. Use the nested-aware
   // emitter so the payload mirror's nested-object / array-of-object components are typed (not
@@ -262,13 +302,15 @@ export function ${extractLenientWithName}(
     : `import type { MetaRoot } from "@metaobjectsdev/metadata";\n`;
   const runtimeImport = `import { extractObject } from "@metaobjectsdev/runtime-ts";\n`;
 
+  // `zod` is imported only when the strict tier is emitted — an XML reply's file
+  // would otherwise carry an unused import (tsc noUnusedLocals-unsafe).
   return (
-    `import { z } from "zod";\n` +
+    (emitStrict ? `import { z } from "zod";\n` : "") +
     `import {\n  ${renderImports.join(",\n  ")},\n} from "@metaobjectsdev/render";\n` +
     metadataImport +
     runtimeImport +
     `\n` +
-    `${strictBody}\n` +
+    (emitStrict ? `${strictBody}\n` : "") +
     `${delegating}`
   );
 }

package/src/templates/output-prompt.ts

@@ -1,11 +1,11 @@
 // 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 extract() codegen agree on the root name.
+// Per-template renderer for the FR-010 artifact-1 response-format fragment
+// ("produce your answer like this"). For each `template.prompt` whose @responseRef
+// resolves to a value-object, emits a `<PromptName>.responseFormat.ts` file
+// exporting `render<PromptName>Format(overrides?)` backed by the render engine's
+// renderOutputFormat(). The baked OutputFormatSpec's rootName is the RESPONSE VO's
+// name, so the 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).
@@ -13,59 +13,46 @@
 import {
   type MetaData,
   TYPE_TEMPLATE,
-  TEMPLATE_SUBTYPE_OUTPUT,
-  TEMPLATE_ATTR_PAYLOAD_REF,
-  TEMPLATE_ATTR_FORMAT,
-  resolveObjectRef,
+  TEMPLATE_SUBTYPE_PROMPT,
+  TEMPLATE_ATTR_RESPONSE_REF,
 } from "@metaobjectsdev/metadata";
 import { specLiteral } from "./output-format-spec-emitter.js";
-
-// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
-// ADR-0042: resolveObjectRef gives package-local-before-root-level precedence for a bare ref, FQN-exact otherwise.
-function findObject(root: MetaData, name: string, referrerPkg = ""): MetaData | undefined {
-  return resolveObjectRef(root, name, referrerPkg).node;
-}
+import { responseShape } from "./find-inbound.js";
 
 // ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
   return root.children().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 {
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const f = ((tmpl.attr(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.
+ * Render the full response-format fragment file for one responding
+ * `template.prompt`. Throws if the template isn't found, isn't a template.prompt,
+ * or its @responseRef is missing / doesn't resolve to an object.value.
+ *
+ * ADR-0052: the fragment describes the shape named by `@responseRef` — the reply —
+ * not `@payloadRef`, which is the request this prompt renders outbound.
  */
 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`);
-  }
-  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-  if (typeof payloadRef !== "string") {
-    throw new Error(`template "${templateName}" missing @payloadRef`);
+  if (tmpl.subType !== TEMPLATE_SUBTYPE_PROMPT) {
+    throw new Error(`template "${templateName}" is not a template.prompt (got subtype "${tmpl.subType}")`);
   }
-  // ADR-0042: a bare @payloadRef resolves in the template's package.
-  const vo = findObject(root, payloadRef, tmpl.package ?? tmpl.fileDefaultPackage ?? "");
-  if (!vo) {
-    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
+  const shape = responseShape(root, tmpl);
+  if (!shape) {
+    // ADR-0039: resolving — @responseRef may be inherited via extends.
+    const declared = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
+    throw new Error(
+      typeof declared === "string"
+        ? `template "${templateName}" @responseRef "${declared}" not found in metadata root`
+        : `template "${templateName}" missing @responseRef`,
+    );
   }
+  const { vo, ref: payloadRef } = shape;
 
-  // rootName == payload name so the prompt fragment and extract() agree.
+  // rootName == response VO name so the fragment and extract() agree.
   const spec = specLiteral(vo, tmpl, payloadRef);
   const specName = `${templateName}FormatSpec`;
   const fnName = `render${templateName}Format`;
@@ -82,7 +69,7 @@ export function renderOutputPrompt(root: MetaData, templateName: string): string
 const ${specName}: OutputFormatSpec = ${spec};
 
 /**
- * The output-format instruction fragment for the ${templateName} template.output
+ * The response-format instruction fragment for the ${templateName} template.prompt
  * ("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.

package/src/templates/queries.ts

@@ -130,7 +130,7 @@ export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const fnName = updateFnName(entityName);
   const findByIdFn = findByIdFnName(entityName);
   // PATCH contract (FR-035): validate the caller's assignments against the
-  // UPDATE schema (all-optional, PK/@readOnly excluded, no insert-time transforms
+  // UPDATE schema (all-optional; PK, @mutability readOnly AND writeOnce excluded; no insert-time transforms
   // like @autoSet-onCreate → now() or the InsertSchema's discriminator handling)
   // — NOT `InsertSchema.partial()`. The typed `<Entity>Patch` param makes a
   // renamed/dropped field a compile error at every call site (PATCH-1..4);

package/src/templates/requirement-test.ts

@@ -0,0 +1,140 @@
+// FR-038 §4 — the DEFAULT requirement-test renderer.
+//
+// "Default" is the operative word: an application owns its testing style, so this
+// is what it gets when it registers no renderer of its own. The library supplies
+// DATA (statement, counterexample, status, claimed refs); a renderer supplies SYNTAX.
+// That separation is what keeps bun / vitest / jest / pytest / JUnit / xUnit from
+// each being an upstream change to this package.
+//
+// The load-bearing rule: an empty generated stub must NOT pass. A `live` entry
+// claims the capability works, so an empty green test asserts the opposite of the
+// claim — the original defect recreated in a new place.
+
+import { GENERATED_HEADER } from "../constants.js";
+import type { RequirementView, ResolvedClaim } from "../requirement-walk.js";
+
+export interface RequirementTestArgs {
+  readonly view: RequirementView;
+  readonly concern: string;
+  readonly statement: string;
+  readonly counterexample: string;
+  readonly targets: readonly ResolvedClaim[];
+  readonly disposition?: string | undefined;
+  readonly trackedBy?: readonly string[] | undefined;
+}
+
+/**
+ * Statuses whose stub is SKIPPED rather than failing.
+ *
+ * The rule is "does this entry claim the capability works right now?" — only `live`
+ * and `partial` do. `planned` is intended-not-built; `abandoned` and `superseded`
+ * describe a capability deliberately retired, whose `@implementedBy` is SUPPOSED to
+ * dangle. Emitting a failing stub for any of the three reddens an application's suite
+ * forever for something nobody intends to build, which is the noise an app silences
+ * wholesale — taking the `live` stubs with it.
+ *
+ * (FR-038 §4 proposes retiring `abandoned`/`superseded` from the vocabulary entirely.
+ * Until that breaking cut lands they are legal `@status` values, so the renderer has
+ * to handle them.)
+ */
+const SKIPPED_STATUSES: ReadonlySet<string> = new Set([
+  "planned",
+  "abandoned",
+  "superseded",
+]);
+
+/**
+ * Escape an author-supplied value for a double-quoted TS string literal.
+ *
+ * Unescaped, a quote closes the literal and a newline breaks it — emitting a stub that
+ * does not parse, which `meta gen` still reports as written because nothing here
+ * compiles it.
+ *
+ * Applied to EVERY value that reaches a literal, not only the two obviously-prose ones.
+ * `@statement` and `@counterexample` are the fields that look dangerous, but the requirement
+ * path and the concern land in the same two literals, and escaping only what looks like
+ * prose leaves the identical hole open one line down.
+ */
+function forStringLiteral(s: string): string {
+  return s
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, "\\n")
+    .replace(/\r/g, "\\r");
+}
+
+/**
+ * Make an author-supplied value safe inside a JSDoc block, preserving what was written.
+ *
+ * A comment-terminator would close the block early and spill the remainder into code; a
+ * newline needs its own continuation marker or the block's shape breaks. The terminator
+ * is separated by a space rather than deleted, so the sentence still reads — and
+ * deliberately NOT by a zero-width space, which would keep the text pixel-identical at
+ * the cost of putting an invisible character into generated source that nobody can see
+ * when debugging it.
+ *
+ * Every value interpolated into the block goes through this, including the ones whose
+ * shape the loader constrains. `@trackedBy` is the one that makes the rule non-optional:
+ * it is registered free-form ON PURPOSE — `verify` never resolves it, because which
+ * sprint owns a gap belongs in the tracker — so its contract invites arbitrary text.
+ */
+function forDocComment(s: string): string {
+  return s.replace(/\*\//g, "* /").replace(/\r?\n/g, "\n * ");
+}
+
+function claimLines(targets: readonly ResolvedClaim[]): string {
+  if (targets.length === 0) {
+    return " *   (none — this requirement names no model nodes)";
+  }
+  return targets
+    .map((t) => ` *   - ${forDocComment(t.ref)}  (${forDocComment(t.concern)})`)
+    .join("\n");
+}
+
+function gapLine(a: RequirementTestArgs): string {
+  const tracked = a.trackedBy ?? [];
+  if (a.disposition === undefined && tracked.length === 0) return "";
+  const decided = forDocComment(a.disposition ?? "undecided");
+  const refs = tracked.length > 0 ? ` — ${tracked.map(forDocComment).join(", ")}` : "";
+  return `\n *\n * Known gap: ${decided}${refs}`;
+}
+
+export function renderRequirementTest(a: RequirementTestArgs): string {
+  const skipped = a.view.status !== undefined && SKIPPED_STATUSES.has(a.view.status);
+  const statement = forDocComment(a.statement);
+  const counterexample = forDocComment(a.counterexample);
+  const runner = skipped ? "test.skip" : "test";
+  // The test NAME is the link between the ledger entry and the assertion, so it is
+  // built from the same two values every time — but it is still a string literal, and
+  // an unescaped quote in either closes it.
+  const testName = `${forStringLiteral(a.view.path)} [${forStringLiteral(a.concern)}]`;
+
+  // A `live` or `partial` stub asserts FAILURE until someone writes the real
+  // assertion over it. `expect.unreachable` names the requirement in the failure
+  // message, so a red run says which claim is unproven rather than just "failed".
+  const body = skipped
+    ? `  // Intended, not built. Write the assertion when this becomes live.`
+    : `  expect.unreachable(\n` +
+      `    "unimplemented requirement stub: ${testName} — " +\n` +
+      `    "replace this with an assertion that fails when: ${forStringLiteral(a.counterexample)}",\n` +
+      `  );`;
+
+  return (
+    `// ${GENERATED_HEADER}.\n` +
+    `// The test IDENTITY is generated from the requirement; the BODY below is yours\n` +
+    `// and survives regeneration. Do not rename the test — the name is the link.\n` +
+    `import { test, expect } from "bun:test";\n` +
+    `\n` +
+    `/**\n` +
+    ` * ${statement}\n` +
+    ` *\n` +
+    ` * Counterexample: ${counterexample}${gapLine(a)}\n` +
+    ` *\n` +
+    ` * Claims:\n` +
+    `${claimLines(a.targets)}\n` +
+    ` */\n` +
+    `${runner}("${testName}", () => {\n` +
+    `${body}\n` +
+    `});\n`
+  );
+}

package/src/templates/zod-validators.ts

@@ -22,7 +22,8 @@ import {
   IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
   FIELD_ATTR_STRING_FORMAT, FIELD_ATTR_LENIENT, STRING_FORMAT_EMAIL, STRING_FORMAT_HOSTNAME,
   FIELD_ATTR_REQUIRED, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT,
-  FIELD_ATTR_AUTO_SET, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_VALUE_TYPE, FIELD_ATTR_READ_ONLY,
+  FIELD_ATTR_AUTO_SET, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_VALUE_TYPE,
+  isReadOnlyMutability, isWriteOnceMutability,
   FIELD_ATTR_DB_COLUMN_TYPE, DB_COLUMN_TYPE_JSONB,
   AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
@@ -215,12 +216,13 @@ export function renderInsertSchemaOnly(obj: MetaObject, ctx?: RenderContext): Co
   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.
+    // FR-037 R1: an @mutability:"readOnly" field is populated by DB / replication /
+    // external owner; the application has no path to write it. Exclude from the
+    // create-shape schema entirely. ("writeOnce" is NOT excluded here — that is
+    // the whole point of the mode: settable on create, frozen after.)
     // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
-    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
+    // excluded from the Insert/Update/preserving schemas, exactly like readOnly.
+    if (isReadOnlyMutability(child) || child.isDerived()) continue;
 
     // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
     if (tphPin !== undefined && child.name === tphPin.fieldName) {
@@ -300,8 +302,9 @@ export function insertSchemaFields(obj: MetaObject): SchemaFieldShape[] {
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
     // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
-    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
+    // excluded from the Insert/Update/preserving schemas, exactly like readOnly.
+    // "writeOnce" stays IN the create shape — it is settable exactly once.
+    if (isReadOnlyMutability(child) || child.isDerived()) continue;
     if (tphPin !== undefined && child.name === tphPin.fieldName) {
       out.push({ name: child.name, optional: false, pinnedLiteral: tphPin.value });
       continue;
@@ -335,8 +338,16 @@ export function updateSchemaFields(obj: MetaObject): SchemaFieldShape[] {
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
     // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
-    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
+    // excluded from the Insert/Update/preserving schemas, exactly like readOnly.
+    if (isReadOnlyMutability(child) || child.isDerived()) continue;
+    // FR-037 R1 — "writeOnce" leaves the UPDATE shape, and only the update shape.
+    // Omitted, not rejected: a key absent from the settable set is STRIPPED on this
+    // path today (D1), and the generated edit form submits EVERY registered field
+    // (0.19.2 switched the resolver to UpdateSchema on edit and does not
+    // diff-and-omit), so 400-on-present would fail every save on every generated
+    // edit form for an entity carrying one. Clearing counts as a write, so the
+    // FR-035 present-null arm never reaches it either.
+    if (isWriteOnceMutability(child)) continue;
     // TPH subtype discriminator: omitted from the update schema entirely.
     if (tphPin !== undefined && child.name === tphPin.fieldName) continue;
     const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
@@ -370,13 +381,13 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
   const emitPreserving = hasAutoSetFields(obj);
   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
+    // FR-037 R1: an @mutability:"readOnly" field appears 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).
     // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
-    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
+    // excluded from the Insert/Update/preserving schemas, exactly like readOnly.
+    if (isReadOnlyMutability(child) || child.isDerived()) 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
@@ -413,6 +424,12 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
       preservingFieldLines.push(fieldLine);
     }
 
+    // FR-037 R1 — "writeOnce": present in Insert + preserving (both are CREATE
+    // shapes), absent from Update. Same mechanism that drops @autoSet onCreate
+    // below; a value presented on PATCH is stripped, not 400'd (see
+    // updateSchemaFields for the grounding).
+    if (isWriteOnceMutability(child)) continue;
+
     // Update schema: @autoSet onCreate → omit entirely; onUpdate → transform
     if (autoSet === AUTO_SET_ON_CREATE) {
       // Omit: creation timestamps cannot be changed after creation

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

@@ -64,3 +64,11 @@
 - {{{bullet}}}
 {{/usedBy}}
 {{/hasUsedBy}}
+{{#hasClaimedBy}}
+
+## Required by
+
+{{#claimedBy}}
+- {{{bullet}}}
+{{/claimedBy}}
+{{/hasClaimedBy}}