@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

package/src/templates/find-inbound.ts

@@ -0,0 +1,96 @@
+// server/typescript/packages/codegen-ts/src/templates/find-inbound.ts
+//
+// The ADR-0052 direction rule, in ONE place.
+//
+// A template subtype's axis is DIRECTION: `template.output` renders outbound (a
+// document or an email) and generates no parser; the inbound half — the response
+// shape, the FR-010 response-format fragment, and the parser-on-receipt — belongs
+// to a `template.prompt` that declares `@responseRef`.
+//
+// Every inbound generator calls through here rather than re-deriving "which
+// templates have a response". Three call sites each deciding for themselves is
+// exactly how the pre-ADR-0052 tier drifted: the parser had no `@kind` filter at
+// all, so an email template generated a parser for text the system had just
+// rendered, while the extractor and the fragment emitter each applied a different
+// json/xml gate.
+
+import {
+  type MetaData,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_PROMPT,
+  TEMPLATE_ATTR_RESPONSE_REF,
+  TEMPLATE_ATTR_RESPONSE_FORMAT,
+  RESPONSE_FORMAT_DEFAULT,
+  RESPONSE_FORMAT_XML,
+  type ResponseFormat,
+  resolveObjectRef,
+} from "@metaobjectsdev/metadata";
+
+/** What an inbound generator needs about one responding prompt. */
+export interface InboundShape {
+  /** The resolved response value-object — the shape a reply is parsed INTO. */
+  readonly vo: MetaData;
+  /** The `@responseRef` string as authored (bare or fully-qualified). */
+  readonly ref: string;
+  /**
+   * The syntax of the REPLY (ADR-0053) — never the template's `@format`, which is
+   * the syntax of the rendered prompt BODY. The two genuinely differ.
+   */
+  readonly format: ResponseFormat;
+}
+
+/**
+ * Every `template.prompt` that declares a response shape, in declaration order.
+ *
+ * The gate is `@responseRef` PRESENCE, not a format value: declaring a response
+ * shape is the request for a parser. Gating on `@format` was what let a `text`
+ * template get a strict parser but no tolerant extract, and — because `@format`
+ * defaults to `text` — would silently emit nothing at all after the re-homing.
+ *
+ * ADR-0039: resolving accessors throughout. A root has no super, but a template
+ * may inherit `@responseRef` from an abstract base via `extends`, and three
+ * shipped fixtures rely on exactly that.
+ */
+export function inboundTemplates(root: MetaData): MetaData[] {
+  return root
+    .children()
+    .filter(
+      (c) =>
+        c.type === TYPE_TEMPLATE &&
+        c.subType === TEMPLATE_SUBTYPE_PROMPT &&
+        typeof c.attr(TEMPLATE_ATTR_RESPONSE_REF) === "string",
+    );
+}
+
+/**
+ * Resolve a prompt's response value-object and reply syntax.
+ *
+ * Returns `undefined` when the template declares no `@responseRef` or the ref does
+ * not resolve — callers skip rather than throw, matching the pre-ADR-0052 contract
+ * for an unresolvable payload ref.
+ */
+export function responseShape(root: MetaData, tmpl: MetaData): InboundShape | undefined {
+  // ADR-0039: resolving — @responseRef may be inherited via extends.
+  const ref = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
+  if (typeof ref !== "string") return undefined;
+  // ADR-0042: a bare @responseRef resolves package-locally, then root-level.
+  const vo = resolveObjectRef(root, ref, tmpl.package ?? tmpl.fileDefaultPackage ?? "").node;
+  if (!vo) return undefined;
+  return { vo, ref, format: responseFormatOf(tmpl) };
+}
+
+/**
+ * The declared reply syntax, defaulted per ADR-0053.
+ *
+ * The default is `json` because that reproduces the trace helper's pre-ADR-0053
+ * fallback exactly (anything that was not `"xml"` was treated as JSON), which is
+ * what makes the attribute's introduction behaviour-preserving rather than a new
+ * policy.
+ */
+export function responseFormatOf(tmpl: MetaData): ResponseFormat {
+  // ADR-0039: resolving — @responseFormat may be inherited via extends.
+  const raw = tmpl.attr(TEMPLATE_ATTR_RESPONSE_FORMAT);
+  return typeof raw === "string" && raw.toLowerCase() === RESPONSE_FORMAT_XML
+    ? RESPONSE_FORMAT_XML
+    : RESPONSE_FORMAT_DEFAULT;
+}

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

@@ -14,11 +14,12 @@ import {
   FIELD_ATTR_EXAMPLE,
   FIELD_ATTR_INSTRUCTION,
   FIELD_ATTR_ENUM_DOC,
-  TEMPLATE_ATTR_FORMAT,
   TEMPLATE_ATTR_PROMPT_STYLE,
   PROMPT_STYLE_INLINE,
   PROMPT_STYLE_EXAMPLE_ONLY,
+  RESPONSE_FORMAT_XML,
 } from "@metaobjectsdev/metadata";
+import { responseFormatOf } from "./find-inbound.js";
 import {
   fields,
   isRequired,
@@ -42,9 +43,11 @@ export function specLiteral(vo: MetaData, template: MetaData, rootName: string):
 }
 
 function resolveFormat(template: MetaData): string {
-  // ADR-0039: resolving — a template may inherit @format via extends.
-  const f = template.attr(TEMPLATE_ATTR_FORMAT);
-  return typeof f === "string" && f.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
+  // ADR-0053: the fragment describes the REPLY, so its syntax is @responseFormat —
+  // NOT @format, which is the syntax of the rendered prompt BODY. Reading @format
+  // here typed the instruction "produce your answer like this" off the format of
+  // the question.
+  return responseFormatOf(template) === RESPONSE_FORMAT_XML ? "Format.XML" : "Format.JSON";
 }
 
 function resolvePromptStyle(template: MetaData): string {

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