@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

package/src/column-mapper.ts

@@ -46,7 +46,7 @@ import {
   AGG_COLLECT,
 } from "@metaobjectsdev/metadata";
 import { columnNameFromField } from "./naming.js";
-import { enumValues } from "./enum-meta.js";
+import { enumValues, intValueMapOf, intValueForMember } from "./enum-meta.js";
 import { DEFAULT_COLUMN_NAMING_STRATEGY, stripPackage } from "@metaobjectsdev/metadata";
 import type { Dialect, ColumnNamingStrategy } from "./metaobjects-config.js";
 
@@ -212,9 +212,42 @@ function canonicalizeSqlExpr(value: string): string {
   return value; // unrecognized — pass through (function calls etc.)
 }
 
+/**
+ * An int-backed `field.enum` column: a generated Drizzle `customType` whose
+ * `toDriver`/`fromDriver` translate member symbol <-> stored integer, so the
+ * codec lives in the COLUMN definition rather than in the query layer.
+ *
+ * This is the TS analogue of what every other port already does at its own
+ * `MetaField` codec seam (EF Core `HasConversion`, OMDB `JdbcFieldCodec`, Exposed
+ * `customEnumeration`, Python `ObjectManager` coercion) — which is why it was
+ * chosen over a Zod write-transform plus a bespoke read-decode: TS's generated
+ * queries hand back raw Drizzle rows and have no decode seam at all, so a
+ * query-layer codec would have meant inventing one and wrapping every generated
+ * read. Binding through the column type also makes filter values encode for free.
+ */
+export interface EnumIntCustomType {
+  /** Local const name for the customType column helper, e.g. `orderStatusEnumCol`. */
+  fnConstName: string;
+  /** Local const name for the symbol->int map, e.g. `ORDER_STATUS_TO_INT`. */
+  toIntConstName: string;
+  /** Local const name for the int->symbol map, e.g. `ORDER_STATUS_FROM_INT`. */
+  fromIntConstName: string;
+  /** Physical column type for `dataType()` — always integer for an int-backed enum. */
+  dataType: string;
+  /** Member symbols, in `@values` order (the TS union and the map key order). */
+  members: string[];
+  /** Member symbol -> stored integer. */
+  intByMember: Record<string, number>;
+}
+
 export interface ColumnSpec {
   /** Drizzle function name, e.g., "text", "integer", "varchar". */
   fnName: string;
+  /**
+   * When set, `fnName` names a LOCAL generated const (this spec's customType
+   * helper) rather than a Drizzle export — the renderer must NOT `imp()` it.
+   */
+  enumIntCustomType?: EnumIntCustomType;
   /** DB column name (snake_case from field name, or @column override). */
   dbName: string;
   /** Positional args after dbName (currently always empty; reserved). */
@@ -342,6 +375,48 @@ function objectRefBaseName(field: MetaField): string | undefined {
   return undefined;
 }
 
+/** SCREAMING_SNAKE_CASE for a generated map const name. */
+function screamingSnake(s: string): string {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .toUpperCase();
+}
+
+/**
+ * Build the customType descriptor for an int-backed `field.enum`, or undefined
+ * when `@values` is missing (the field then degrades to a plain integer column
+ * rather than emitting a codec over an unknown member set).
+ *
+ * Names are derived from the FIELD name, so the consts are per-entity-file and
+ * self-contained. A shared enum consumed by N entities therefore emits N small
+ * identical helpers rather than requiring a cross-module import — the same
+ * self-contained tradeoff the per-entity enum union already makes.
+ */
+function buildEnumIntCustomType(
+  field: MetaField,
+  intByMember: Record<string, number>,
+): EnumIntCustomType | undefined {
+  const members = enumValues(field);
+  if (members === undefined || members.length === 0) return undefined;
+  // Every member must map — the loader pins key-set-equals-@values (Check 5b), so a
+  // miss is unreachable; throwing beats emitting a codec with a hole in it.
+  for (const m of members) {
+    intValueForMember(intByMember, m, `customType codec for field '${field.name}'`);
+  }
+  const base = field.name.replace(/[^A-Za-z0-9]/g, "");
+  const camel = base.charAt(0).toLowerCase() + base.slice(1);
+  const screaming = screamingSnake(base);
+  return {
+    fnConstName: `${camel}IntEnum`,
+    toIntConstName: `${screaming}_TO_INT`,
+    fromIntConstName: `${screaming}_FROM_INT`,
+    dataType: "integer",
+    members,
+    intByMember,
+  };
+}
+
 export function mapColumnType(
   field: MetaField,
   dialect: Dialect,
@@ -355,6 +430,8 @@ export function mapColumnType(
 
   let fnName: string;
   let fnOptions: Record<string, unknown> | undefined;
+  // Set only for an int-backed field.enum — see EnumIntCustomType.
+  let enumIntCustomType: EnumIntCustomType | undefined;
 
   let leadingComment: string | undefined;
   if (dialect === "sqlite") {
@@ -405,8 +482,20 @@ export function mapColumnType(
           // "string" by the time it reaches here for this dialect.
           fnName = "text";
           break;
-        case FIELD_SUBTYPE_STRING:
         case FIELD_SUBTYPE_ENUM:
+          // An INT-BACKED enum stores the mapped integer on SQLite too — SQLite has
+          // one integer storage class, so this matches migrate-ts's integer{32}.
+          {
+            const im = intValueMapOf(field);
+            if (im !== undefined) {
+              enumIntCustomType = buildEnumIntCustomType(field, im);
+              fnName = enumIntCustomType?.fnConstName ?? "integer";
+            } else {
+              fnName = "text";
+            }
+          }
+          break;
+        case FIELD_SUBTYPE_STRING:
         case FIELD_SUBTYPE_UUID:
         case FIELD_SUBTYPE_URI:
         case FIELD_SUBTYPE_INET:
@@ -524,6 +613,22 @@ export function mapColumnType(
           fnName = "jsonb";
           break;
         case FIELD_SUBTYPE_ENUM:
+          // An INT-BACKED enum (@intValueMap, design D5) stores the mapped integer,
+          // so the Drizzle column is integer — matching migrate-ts's expected-schema.
+          // The TS-facing type stays the member-string union; the symbol<->int
+          // translation happens at the write/read boundary. Scalar only: D7 makes
+          // @intValueMap + isArray ERR_ENUM_INT_VALUE_MAP_ARRAY at load, so an array
+          // enum reaching here is always string-backed.
+          {
+            const im = intValueMapOf(field);
+            if (im !== undefined) {
+              enumIntCustomType = buildEnumIntCustomType(field, im);
+              fnName = enumIntCustomType?.fnConstName ?? "integer";
+            } else {
+              fnName = "text";
+            }
+          }
+          break;
         default:
           fnName = "text";
           break;
@@ -669,6 +774,7 @@ export function mapColumnType(
   };
   if (fnOptions !== undefined) result.fnOptions = fnOptions;
   if (defaultExpr !== undefined) result.defaultExpr = defaultExpr;
+  if (enumIntCustomType !== undefined) result.enumIntCustomType = enumIntCustomType;
   if (dollarTypeRef !== undefined) result.dollarTypeRef = dollarTypeRef;
   if (leadingComment !== undefined) result.leadingComment = leadingComment;
 
@@ -676,12 +782,22 @@ export function mapColumnType(
   if (subType === FIELD_SUBTYPE_ENUM && !isArray) {
     const values = enumValues(field);
     if (values !== undefined && values.length > 0) {
-      // Single-quote escaping is belt-and-suspenders: the loader's
-      // ENUM_MEMBER_PATTERN already rejects quote-bearing members (members are
-      // validated to be identifier-safe), so this never fires in practice.
-      const list = values
-        .map((v) => `'${v.replace(/'/g, "''")}'`)
-        .join(", ");
+      const intMap = intValueMapOf(field);
+      let list: string;
+      if (intMap !== undefined) {
+        // Int-backed: the column holds integers, so the CHECK lists them unquoted.
+        // Keyed BY MEMBER through the map (not Object.values) so the constraint can
+        // never disagree with @values, which stays the SSOT. Must match
+        // migrate-ts's buildChecks exactly or `meta verify` reports permanent drift.
+        list = values
+          .map((v) => String(intValueForMember(intMap, v, `CHECK for column '${dbName}'`)))
+          .join(", ");
+      } else {
+        // Single-quote escaping is belt-and-suspenders: the loader's
+        // ENUM_MEMBER_PATTERN already rejects quote-bearing members (members are
+        // validated to be identifier-safe), so this never fires in practice.
+        list = values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
+      }
       result.checkConstraint = `${dbName} IN (${list})`;
     }
   }

package/src/enum-meta.ts

@@ -3,7 +3,7 @@
 // extraction and the z.enum([...]) expression are derived in exactly one place.
 
 import type { MetaField } from "@metaobjectsdev/metadata";
-import { FIELD_ATTR_VALUES } from "@metaobjectsdev/metadata";
+import { FIELD_ATTR_VALUES, FIELD_ATTR_INT_VALUE_MAP } from "@metaobjectsdev/metadata";
 
 /**
  * Effective enum member values (`@values`) for a field, as strings.
@@ -20,6 +20,42 @@ export function enumValues(field: MetaField): string[] | undefined {
   return values.map((v) => String(v));
 }
 
+/**
+ * The effective `@intValueMap` (member symbol → integer) for an int-backed enum,
+ * or undefined when the enum is string-backed. Its PRESENCE is the whole trigger
+ * for integer persistence (design D5) — there is no separate flag or config.
+ *
+ * ADR-0039: RESOLVING (`attr`, not `ownAttr`), and this is load-bearing rather
+ * than incidental. Post-#246 an own `@intValueMap` declared against a shared
+ * (root-level abstract) enum is `ERR_ENUM_EXTENDS_VALUES_CONFLICT`, so the map
+ * lives on the SHARED DECLARATION and every consuming field INHERITS it. An
+ * own-only read would therefore see undefined on exactly the shape adopters are
+ * steered toward, and silently emit a string codec into an integer column.
+ */
+export function intValueMapOf(field: MetaField): Record<string, number> | undefined {
+  const raw = field.attr(FIELD_ATTR_INT_VALUE_MAP);
+  if (raw === undefined || raw === null || typeof raw !== "object") return undefined;
+  return raw as Record<string, number>;
+}
+
+/**
+ * The integer a member symbol persists as, for an int-backed enum. Throws when the
+ * member has no mapping — the loader pins key-set-equals-`@values` (Check 5b) in
+ * every port, so a miss is unreachable and must not be papered over: emitting the
+ * symbol instead would fail only at INSERT time, against a live database.
+ */
+export function intValueForMember(
+  intMap: Record<string, number>,
+  member: string,
+  context: string,
+): number {
+  const n = intMap[member];
+  if (typeof n !== "number") {
+    throw new Error(`@intValueMap has no integer for member '${member}' (${context}).`);
+  }
+  return n;
+}
+
 /** Build the Zod expression for a set of enum members, e.g. `z.enum(["A", "B"])`. */
 export function zodEnumExpr(values: string[]): string {
   return `z.enum([${values.map((v) => JSON.stringify(v)).join(", ")}])`;

package/src/generator.ts

@@ -1,6 +1,7 @@
 import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "./render-context.js";
 import type { ResolvedGenConfig } from "./metaobjects-config.js";
+import type { OrphanPolicy } from "./reconcile-orphans.js";
 import { effectivePackage } from "./docs-paths.js";
 
 export interface EmittedFile {
@@ -48,6 +49,14 @@ export interface Generator {
   /** Marks the generator that produces entity modules — the runner uses its
    *  target as the entity-module target for cross-target import resolution. */
   emitsEntityModule?: boolean;
+  /** FR-038 §8 — OPT IN to orphan reconciliation by declaring the output
+   *  namespace this generator exclusively owns. When set, the runner removes
+   *  files inside that namespace which a previous run generated and this run did
+   *  not, REFUSING any that have been edited by hand. Absent (the default for
+   *  every existing generator) means the runner never deletes anything, which is
+   *  why this is additive: output stops being generated and the stale file simply
+   *  stays, exactly as before. */
+  orphanPolicy?: OrphanPolicy;
   /** Marks the OPT-IN Hono routes generator (routesFileHono). The runner
    *  aggregates this across the active suite into `ctx.config.includeHonoRoutes`,
    *  so a generator that documents the API surface (api-docs) can AUTO-DETECT

package/src/generators/api-field-shape.ts

@@ -9,7 +9,7 @@
 //     emitter uses) and the optional/nullable rule from `isFieldRequired` (the
 //     SAME rule the docs Storage/Constraints nullable column uses).
 //   • create-payload     → `insertSchemaFields` (the EXACT field set + optionality
-//     the zod InsertSchema emitter walks: auto-gen PK omitted, @readOnly omitted,
+//     the zod InsertSchema emitter walks: auto-gen PK omitted, @mutability:"readOnly" omitted,
 //     TPH discriminator pinned, @autoSet optional, else `fieldWillBeOptional`).
 //   • update-payload     → `updateSchemaFields` (the UpdateSchema walk: TPH
 //     discriminator + @autoSet-onCreate omitted, everything else optional).

package/src/generators/api-model.ts

@@ -107,6 +107,7 @@ import {
   variableNameFromEntity,
 } from "../naming.js";
 import { getPkInfo } from "../templates/queries.js";
+import { responseShape } from "../templates/find-inbound.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
 import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
 import { isCallableEntity } from "../templates/callable-file.js";
@@ -823,50 +824,21 @@ function templateOutputs(root: MetaRoot): MetaData[] {
 function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout): ApiUnitDoc {
   const name = tmpl.name;
   const symbols: ApiSymbol[] = [];
-  // extractor + render-helper generators emit FLAT `<Name>.extractor.ts` /
-  // `<Name>.render.ts` (no package folding), so importPath ignores layout.
-  const extractorMod = templateModulePath(`${name}.extractor`);
+  // The render-helper generator emits a FLAT `<Name>.render.ts` (no package
+  // folding), so importPath ignores layout.
   const renderMod = templateModulePath(`${name}.render`);
 
-  // ADR-0039: resolving — a template may inherit @payloadRef/@format/@kind via extends.
+  // ADR-0039: resolving — a template may inherit @payloadRef/@kind via extends.
   const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   const payload = typeof payloadRef === "string" ? payloadRef : undefined;
-  const format = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
   const kind = ((tmpl.attr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT).toLowerCase();
 
-  // --- extractor: only json/xml output-parsers expose the extract API (matches
-  //     extractor-file.ts's `if (format !== "json" && format !== "xml") continue`). ---
-  if (payload && (format === "json" || format === "xml")) {
-    const extract = `extract${name}`;
-    const extractLenient = `extractLenient${name}`;
-    // The extractor's strict return IS the @payloadRef value-object's interface —
-    // document its field shape (same VO field walk the payload interface emitter
-    // uses) so an agent sees what `extract<Name>` yields, not just the type name.
-    const payloadShape = payloadFieldShapes(root, payload);
-    const extractSym: ApiSymbol = {
-      name: extract,
-      kind: "extractor",
-      importPath: extractorMod,
-      signature: `${extract}(root: MetaRoot, text: string): ${payload}`,
-      params: [`root: MetaRoot`, `text: string`],
-      returns: payload,
-      throws: `Error when a @required field is lost (the strict opt-in gate).`,
-      usage: `Parse dirty LLM ${format} text into a strict, fully-typed ${payload} graph.`,
-    };
-    if (payloadShape !== undefined) extractSym.fields = payloadShape;
-    symbols.push(
-      extractSym,
-      {
-        name: extractLenient,
-        kind: "extractor",
-        importPath: extractorMod,
-        signature: `${extractLenient}(root: MetaRoot, text: string): ExtractionResult<${name}Extracted>`,
-        params: [`root: MetaRoot`, `text: string`],
-        returns: `ExtractionResult<${name}Extracted>`,
-        usage: `Never-throwing extract; inspect report for lost/defaulted fields.`,
-      },
-    );
-  }
+  // ADR-0052: a template.output documents its RENDER and nothing else. The
+  // extractor symbols used to be built here, gated on @format ∈ {json,xml} and
+  // typed on @payloadRef — so the reference documented functions this subtype no
+  // longer emits, named the REQUEST shape as the parse result, and said nothing
+  // about the prompts that actually do emit them. They now live in
+  // buildPromptUnit, keyed on @responseRef.
 
   // --- render: render<Name>; document → string, email → EmailDocument
   //     (matches render-helper.ts's @kind branch). Render is emitted for any
@@ -875,7 +847,7 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
     const render = `render${name}`;
     const isEmail = kind === TEMPLATE_KIND_EMAIL;
     const returns = isEmail ? "EmailDocument" : "string";
-    symbols.push({
+    const renderSym: ApiSymbol = {
       name: render,
       kind: "render",
       importPath: renderMod,
@@ -885,7 +857,14 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
       usage: isEmail
         ? `Render the ${name} email (subject + bodies) from a typed ${payload} payload.`
         : `Render the ${name} document from a typed ${payload} payload.`,
-    });
+    };
+    // The payload shape used to reach this unit only via the extractor symbol.
+    // ADR-0052 moved that away, which left the render example with no field shape
+    // to build from — it degraded to `render<Name>({}, provider)`. Attach it here,
+    // where it always belonged: this is the payload the render handle takes.
+    const renderShape = payloadFieldShapes(root, payload);
+    if (renderShape !== undefined) renderSym.fields = renderShape;
+    symbols.push(renderSym);
   }
 
   const unit: ApiUnitDoc = {
@@ -950,12 +929,57 @@ function buildPromptUnit(tmpl: MetaData, root: MetaRoot): ApiUnitDoc {
     symbols.push(sym);
   }
 
-  return {
+  // --- ADR-0052 inbound half: a prompt declaring @responseRef also owns the
+  //     parser-on-receipt and the tolerant extract. Gated on @responseRef
+  //     PRESENCE, matching extractor-file.ts / output-parser-file.ts — never on
+  //     a format value, and never on @payloadRef, which types the REQUEST. ---
+  const shape = responseShape(root, tmpl);
+  if (shape) {
+    const { vo, ref: responseRef, format } = shape;
+    // The extractor generator emits a FLAT `<Name>.extractor.ts`.
+    const extractorMod = templateModulePath(`${name}.extractor`);
+    const extract = `extract${name}`;
+    const extractLenient = `extractLenient${name}`;
+    // The strict return IS the @responseRef value-object's interface — document
+    // its field shape so an agent sees what `extract<Name>` yields, not just a
+    // type name. `vo` is the resolved node; `responseRef` is the authored ref.
+    void vo;
+    const responseFieldShape = payloadFieldShapes(root, responseRef);
+    const extractSym: ApiSymbol = {
+      name: extract,
+      kind: "extractor",
+      importPath: extractorMod,
+      signature: `${extract}(root: MetaRoot, text: string): ${responseRef}`,
+      params: [`root: MetaRoot`, `text: string`],
+      returns: responseRef,
+      throws: `Error when a @required field is lost (the strict opt-in gate).`,
+      usage: `Parse the model's ${format} reply to ${name} into a strict, fully-typed ${responseRef} graph.`,
+    };
+    if (responseFieldShape !== undefined) extractSym.fields = responseFieldShape;
+    symbols.push(extractSym, {
+      name: extractLenient,
+      kind: "extractor",
+      importPath: extractorMod,
+      signature: `${extractLenient}(root: MetaRoot, text: string): ExtractionResult<${name}Extracted>`,
+      params: [`root: MetaRoot`, `text: string`],
+      returns: `ExtractionResult<${name}Extracted>`,
+      usage: `Never-throwing extract of the ${name} reply; inspect report for lost/defaulted fields.`,
+    });
+  }
+
+  const unit: ApiUnitDoc = {
     node: name,
     package: effectivePackage(tmpl),
     nodeKind: "template",
     symbols,
   };
+  // ADR-0052: the extractor symbols moved here, so their worked example must move
+  // with them. Without this the page documents `extract<Name>(root, …)` but the
+  // setup preamble never introduces `root`, because the preamble derives its
+  // handles from the rendered EXAMPLE text.
+  const example = templateExample(name, symbols);
+  if (example !== undefined) unit.example = example;
+  return unit;
 }
 
 // ---------------------------------------------------------------------------
@@ -1069,9 +1093,10 @@ function templateExample(name: string, symbols: ApiSymbol[]): UnitExample | unde
   if (renderSym !== undefined) {
     picks.push({ name: renderSym.name, importPath: renderSym.importPath });
     // Render's payload object literal comes from the @payloadRef VO shape the
-    // render symbol returns/consumes; reuse the extractor's documented payload
-    // fields when present so the example body is real.
-    const payloadFields = extract?.fields;
+    // render symbol consumes. Prefer the render symbol's OWN fields — it borrowed
+    // the extractor's before ADR-0052, which silently degraded the example to
+    // `render<Name>({}, provider)` the moment the extractor moved to the prompt.
+    const payloadFields = renderSym.fields ?? extract?.fields;
     const payloadLit = objectLiteralFromFields(payloadFields);
     body.push(`const output = ${renderSym.name}(${payloadLit}, provider);`);
   }

package/src/generators/docs-data-builder.ts

@@ -11,7 +11,9 @@ import {
   type MetaRoot,
   TYPE_TEMPLATE,
   TEMPLATE_ATTR_PAYLOAD_REF,
+  REQUIREMENT_ATTR_STATEMENT,
   OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
   IDENTITY_SUBTYPE_PRIMARY,
   IDENTITY_SUBTYPE_SECONDARY,
   IDENTITY_SUBTYPE_REFERENCE,
@@ -52,6 +54,9 @@ import { enumValues } from "../enum-meta.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { renderEntityNeighborhoodErBlock } from "../templates/mermaid-er.js";
+// Shape C reuses the SAME walk the stub generator and the requirements index use, so
+// all three agree about what the ledger contains by construction.
+import { walkRequirements } from "../requirement-walk.js";
 import type {
   EntityDocData,
   StorageFieldDoc,
@@ -684,6 +689,34 @@ export function buildEntityDocData(
   }
   const usedBy = usedByMatches.length > 0 ? usedByMatches : undefined;
 
+  // ---- ClaimedBy (shape C) — the requirements whose `@implementedBy` resolves HERE.
+  //
+  // Matched on the RESOLVED NODE, never on the reference string: `@implementedBy` may
+  // be authored fully-qualified or bare, and a bare ref binds package-locally under
+  // ADR-0042. `walkRequirements` already did that resolution (it is what the stub
+  // generator uses), so comparing nodes inherits the correct binding rather than
+  // re-deriving it here and drifting from it.
+  //
+  // ENTITY-GRAIN. Object coverage is entity-grain, so a claimed value/projection gets
+  // nothing — surfacing one would imply a coverage rule the ledger does not have.
+  const claimedByMatches: UsedByDoc[] = [];
+  if (entity.subType === OBJECT_SUBTYPE_ENTITY) {
+    for (const walked of walkRequirements(root)) {
+      if (!walked.targets.some((t) => t.node === entity)) continue;
+      const v = walked.view;
+      const level = v.level === undefined ? "" : ` · **L${v.level}**`;
+      const status = v.status === undefined ? "" : ` · status: \`${v.status}\``;
+      const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
+      const said = typeof statement === "string" && statement.length > 0 ? ` — ${statement}` : "";
+      claimedByMatches.push({
+        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${said}`,
+      });
+    }
+  }
+  // ABSENT, not empty: the Mustache gate must not render for an unclaimed entity, so
+  // its page stays byte-identical to its pre-feature output.
+  const claimedBy = claimedByMatches.length > 0 ? claimedByMatches : undefined;
+
   // Preamble header — built up exactly as the legacy emitter did.
   const preambleLines: string[] = [];
   const typeStr = `${entity.type}.${entity.subType}`;
@@ -761,6 +794,10 @@ export function buildEntityDocData(
     data.usedBy = usedBy;
     data.hasUsedBy = true;
   }
+  if (claimedBy !== undefined) {
+    data.claimedBy = claimedBy;
+    data.hasClaimedBy = true;
+  }
   // Cross-link to the api surfaces — present ONLY when the caller computed the
   // hrefs (api surfaces emitted alongside model); model-only runs stay identical.
   // `last` flags the final ref so the template renders an inline ` · ` separator.

package/src/generators/docs-data.ts

@@ -256,6 +256,21 @@ export interface EntityDocData {
   /** Present-and-non-empty flag for the usedBy section. */
   hasUsedBy?: boolean;
 
+  /** "Required by" (shape C) — the `requirement.*` nodes whose `@implementedBy`
+   *  resolves to THIS entity. Same list+flag pattern as `usedBy`.
+   *
+   *  ABSENT — not empty, not false — when nothing claims the entity, so the
+   *  Mustache section does not render and an unclaimed entity's page stays
+   *  BYTE-IDENTICAL to its pre-feature output. That is the no-churn contract:
+   *  a project with no ledger, or an entity nothing claims, must see no diff.
+   *
+   *  ENTITY-GRAIN ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
+   *  so a claimed `object.value` / `object.projection` gets nothing here — surfacing
+   *  one would imply a coverage rule the ledger does not actually have. */
+  claimedBy?: UsedByDoc[];
+  /** Present-and-non-empty flag for the claimedBy section. */
+  hasClaimedBy?: boolean;
+
   /** Present flag for the storage section. */
   hasStorage?: boolean;
 

package/src/generators/docs-file.ts

@@ -19,7 +19,7 @@
 // breaks, the refactor is the bug, not the fixture.
 
 import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE } from "@metaobjectsdev/metadata";
 import { render } from "@metaobjectsdev/render";
 import type { Provider } from "@metaobjectsdev/render";
 import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
@@ -132,12 +132,21 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
           return { path, content: renderDocPage(TEMPLATE_REF, payload, provider, path) };
         });
 
-      // ALSO emit one NEUTRAL render-contract page per `template.output` node —
-      // a sibling artifact, distinct from the entity page. Raw node name → file
+      // ALSO emit one NEUTRAL render-contract page per top-level `template.*` node
+      // — a sibling artifact, distinct from the entity page. Raw node name → file
       // (`<name>.md`), agreeing with the entity Used-by back-link target.
+      //
+      // EVERY template subtype, not just `template.output`: the api-docs surface
+      // has always emitted `api/<lang>/<pkg>/<Prompt>.md` for a top-level
+      // `template.prompt` (it documents the prompt-render handle), and that page
+      // carries a "Model / metadata" back-link to `<pkg>/<Prompt>.md`. While this
+      // loop filtered to outputs, that link pointed at a page nothing wrote — a
+      // broken link in every shipped doc tree containing a prompt. ADR-0052 makes
+      // it worse rather than better: a responding prompt now carries the whole
+      // inbound tier, so it is the LAST node a doc tree should omit.
       // ADR-0039: resolving — root has no super (children()==ownChildren()).
       for (const child of ctx.loadedRoot.children()) {
-        if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
+        if (child.type !== TYPE_TEMPLATE) continue;
         const node = docPageNode(child);
         templateNodes.push(node);
         const path = docPageOutputPath(layout, node);

package/src/generators/extractor-file.ts

@@ -4,7 +4,7 @@
 // node whose @format is json/xml. Wraps renderExtractor() from templates/extractor.ts.
 //
 // The emitted extractor sits over the output-parser's nested-capable extract and turns dirty LLM
-// text into the strict typed payload graph. It imports from the sibling <Name>.output.ts (the
+// text into the strict typed payload graph. It imports from the sibling <Name>.response.ts (the
 // output-parser) and from each payload value-object's own entity module (<VO>.ts, emitted by
 // entityFile), so run it alongside outputParser() + entityFile().
 //
@@ -14,13 +14,13 @@
 // Custom output directory:
 //   generators: [..., extractor({ outDir: "src/generated/outputs" })]
 
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
   type Generator,
   type GeneratorFactory,
   oncePerRun,
 } from "../generator.js";
+import { inboundTemplates, responseShape } from "../templates/find-inbound.js";
 import { renderExtractor } from "../templates/extractor.js";
 
 export interface ExtractorOpts {
@@ -35,16 +35,12 @@ export const extractor = function extractor(opts?: ExtractorOpts): Generator {
   const generator: Generator = {
     name: "extractor",
     generate: oncePerRun((_entities, ctx) => {
-      // ADR-0039: resolving — root has no super (children()==ownChildren()).
-      const outputs = ctx.loadedRoot
-        .children()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
-        // The extract tier requires the extract API, which only json/xml output-parsers emit.
-        // ADR-0039: resolving — a template may inherit @format via extends.
-        const format = ((t.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-        if (format !== "json" && format !== "xml") continue;
+      for (const t of inboundTemplates(ctx.loadedRoot)) {
+        // The extract tier sits over the parser's extract API. Since ADR-0052 every
+        // responding prompt emits one (@responseFormat is a closed json|xml set), so
+        // the only remaining skip is an unresolvable @responseRef.
+        if (!responseShape(ctx.loadedRoot, t)) continue;
         files.push({
           path: `${dirPrefix}${t.name}.extractor.ts`,
           // ADR-0044/#228: thread ctx.renderContext (when present — runGen always supplies it;

package/src/generators/index.ts

@@ -44,3 +44,14 @@ export type {
 export { buildEntityDocData } from "./docs-data-builder.js";
 export type { TemplateDocData, TemplateOutputPart } from "./template-doc-data.js";
 export { buildTemplateDocData } from "./template-doc-builder.js";
+
+// FR-038 — requirement-derived test stubs. The factory is a convenience; the
+// primitives beside it are the real escape hatch, so an app needing different
+// behaviour composes its own generator instead of filing an issue here.
+export { requirementTests } from "./requirement-tests.js";
+export { requirementsFile } from "./requirements-file.js";
+export type { RequirementRow } from "./requirements-view.js";
+export type {
+  RequirementTestsOpts,
+  RequirementTestRenderer,
+} from "./requirement-tests.js";