@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

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

@@ -1,7 +1,13 @@
 // server/typescript/packages/codegen-ts/src/generators/output-parser-file.ts
 //
-// Stock generator that emits one <TemplateName>.output.ts file per declared
-// template.output node. Wraps renderOutputParser() from templates/output-parser.ts.
+// Stock generator that emits one <PromptName>.response.ts file per declared
+// `template.prompt` carrying `@responseRef`. Wraps renderOutputParser() from
+// templates/output-parser.ts.
+//
+// ADR-0052: this tier is INBOUND — it reads a model's reply. It used to key on
+// `template.output` with no `@kind` filter at all, so an email template generated
+// a parser for text the system had just rendered. `template.output` is outbound
+// only and emits nothing here.
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., promptRender(), outputParser()]
@@ -9,8 +15,7 @@
 // Custom output directory:
 //   generators: [..., outputParser({ outDir: "src/generated/outputs" })]
 
-import { TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
-import { findTemplates } from "../templates/find-templates.js";
+import { inboundTemplates } from "../templates/find-inbound.js";
 import {
   type EmittedFile,
   type Generator,
@@ -31,11 +36,11 @@ export const outputParser = function outputParser(opts?: OutputParserOpts): Gene
   const generator: Generator = {
     name: "output-parser",
     generate: oncePerRun((_entities, ctx) => {
-      const outputs = findTemplates(ctx.loadedRoot, TEMPLATE_SUBTYPE_OUTPUT);
+      const responders = inboundTemplates(ctx.loadedRoot);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
+      for (const t of responders) {
         files.push({
-          path: `${dirPrefix}${t.name}.output.ts`,
+          path: `${dirPrefix}${t.name}.response.ts`,
           // ADR-0044/#228: thread ctx.renderContext (when present — runGen always supplies it;
           // a hand-rolled GenContext in a unit test may omit it, falling back to bare naming) so
           // a payload/nested value-object whose bare name collides across packages emits the

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

@@ -1,10 +1,13 @@
 // server/typescript/packages/codegen-ts/src/generators/output-prompt-file.ts
 //
-// FR-010 stock generator that emits one <TemplateName>.prompt.ts file per json/xml
-// template.output node — the output-format prompt fragment ("produce your answer
-// like this"). Wraps renderOutputPrompt() from templates/output-prompt.ts. Skips
-// text-format outputs and outputs whose @payloadRef doesn't resolve to a value-object
-// (same contract as the output-parser generator).
+// FR-010 stock generator that emits one <PromptName>.responseFormat.ts file per
+// responding `template.prompt` — the response-format fragment ("produce your answer
+// like this"). Wraps renderOutputPrompt() from templates/output-prompt.ts.
+//
+// ADR-0052: gated on `@responseRef` presence, like every other inbound generator.
+// It previously keyed on `template.output` + a json/xml `@format` gate, which is
+// how a fragment that instructs an LLM came to be emitted from the subtype defined
+// as "every rendered artifact other than an LLM prompt".
 //
 // Consumer wiring (metaobjects.config.ts):
 //   generators: [..., promptRender(), outputParser(), outputPrompt()]
@@ -12,19 +15,14 @@
 // Custom output directory:
 //   generators: [..., outputPrompt({ outDir: "src/generated/outputs" })]
 
-import {
-  TYPE_TEMPLATE,
-  TEMPLATE_SUBTYPE_OUTPUT,
-  TEMPLATE_ATTR_PAYLOAD_REF,
-  resolveObjectRef,
-} from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
   type Generator,
   type GeneratorFactory,
   oncePerRun,
 } from "../generator.js";
-import { renderOutputPrompt, templateSupportsPrompt } from "../templates/output-prompt.js";
+import { inboundTemplates, responseShape } from "../templates/find-inbound.js";
+import { renderOutputPrompt } from "../templates/output-prompt.js";
 
 export interface OutputPromptOpts {
   /** Output directory prefix relative to the target's outDir. Default: "" (root). */
@@ -39,23 +37,12 @@ export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Gene
     name: "output-prompt",
     generate: oncePerRun((_entities, ctx) => {
       const root = ctx.loadedRoot;
-      // ADR-0039: resolving — root has no super (children()==ownChildren()).
-      const outputs = root
-        .children()
-        .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
-      for (const t of outputs) {
-        // Only json/xml outputs get a renderable prompt fragment.
-        if (!templateSupportsPrompt(t)) continue;
-        // @payloadRef must resolve to a value-object (same contract as the parser).
-        // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
-        const payloadRef = t.attr(TEMPLATE_ATTR_PAYLOAD_REF);
-        if (typeof payloadRef !== "string") continue;
-        // ADR-0042: a bare @payloadRef resolves in the template's package.
-        const vo = resolveObjectRef(root, payloadRef, t.package ?? t.fileDefaultPackage ?? "").node;
-        if (!vo) continue;
+      for (const t of inboundTemplates(root)) {
+        // @responseRef must resolve to a value-object (same contract as the parser).
+        if (!responseShape(root, t)) continue;
         files.push({
-          path: `${dirPrefix}${t.name}.prompt.ts`,
+          path: `${dirPrefix}${t.name}.responseFormat.ts`,
           content: renderOutputPrompt(root, t.name),
         });
       }

package/src/generators/requirement-tests.ts

@@ -0,0 +1,203 @@
+// FR-038 §5/§6 — generate test stubs from `requirement.*` nodes.
+//
+// THE DIVISION OF LABOUR: this package owns the MECHANISM; the application owns
+// the POLICY. Which requirements get tests, at which levels, in what style, or
+// none at all, is the app's decision — the library ships defaults and
+// recommendations, never rules.
+//
+// The filter IS the policy declaration, which is why there is no opt-out
+// vocabulary: a requirement matched by no generator expects no stub by
+// construction, so `verify --codegen` has nothing to drift against. An `@noTest`
+// attribute would have to clear ADR-0023's can't-be-computed bar, and it cannot —
+// the generator config already says it.
+//
+// Every default below has an override seam. The rule: if an application can hit a
+// decision and cannot change it, that decision becomes a bug report against this
+// package.
+
+import {
+  REQUIREMENT_SUBTYPE_FUNCTIONAL,
+  REQUIREMENT_LINK_FLOOR_LEVEL,
+  REQUIREMENT_ATTR_STATEMENT,
+  REQUIREMENT_ATTR_COUNTEREXAMPLE,
+} from "@metaobjectsdev/metadata";
+import type { Generator, EmittedFile, GenContext } from "../generator.js";
+import {
+  walkRequirements,
+  groupByConcern,
+  NO_CONCERN,
+  type RequirementView,
+} from "../requirement-walk.js";
+import {
+  renderRequirementTest,
+  type RequirementTestArgs,
+} from "../templates/requirement-test.js";
+
+export type RequirementTestRenderer = (a: RequirementTestArgs) => string;
+
+export interface RequirementTestsOpts {
+  /** Generator name — surfaces in diagnostics and drift logs. */
+  name?: string;
+  /** WHICH requirements get stubs. This is the app's policy declaration. */
+  filter?: (r: RequirementView) => boolean;
+  /** Renderer per concern key: exact `type.subType`, `type.*`, or `*`. */
+  renderers?: Record<string, RequirementTestRenderer>;
+  /** Full control over renderer selection — beats `renderers` when it returns one. */
+  resolveRenderer?: (concern: string) => RequirementTestRenderer | undefined;
+  /** Where each stub lands. */
+  path?: (view: RequirementView, concern: string) => string;
+  /** Named output target (registry key). */
+  target?: string;
+  /** Name requirements no filter covered. Default true; never fails the build. */
+  warnUncovered?: boolean;
+  /**
+   * FR-038 §8 — which emitted paths this generator is the sole producer of, so
+   * the runner may remove a stub whose requirement was deleted. Given a path
+   * relative to this generator's output directory, `/`-separated.
+   *
+   * Defaults to the namespace `defaultPath` writes into. Supply this whenever you
+   * supply `path`: the two describe the same namespace from opposite directions
+   * and only you can keep them in agreement.
+   */
+  owns?: (relPathInTarget: string) => boolean;
+  /**
+   * Delete a hand-edited orphan rather than refusing it. Default false.
+   *
+   * A refusal already names the file and tells you the two ways out; this makes
+   * the destructive one automatic. It exists so the decision is yours, not
+   * because it is a good default.
+   */
+  forceOrphanDelete?: boolean;
+  /** Turn orphan reconciliation off entirely. Default true — a stub whose
+   *  requirement is gone is drift, and leaving it is how a deleted claim keeps a
+   *  green test. */
+  reconcileOrphans?: boolean;
+}
+
+/** How many uncovered requirements to name before "…and N more". Mirrors the
+ *  runner's MAX_NAMED — the same cutoff, so every wall-avoiding message in the
+ *  feature reads the same shape. */
+const MAX_NAMED_UNCOVERED = 5;
+
+/** The directory `defaultPath` writes into — and therefore the namespace the
+ *  default policy claims. Kept beside it so the pair cannot drift. */
+const DEFAULT_STUB_DIR = "requirements/";
+
+/**
+ * RECOMMENDATION, not a rule: functional requirements at or below the link floor.
+ *
+ * Architectural requirements are excluded by default because `verify`'s
+ * universality check already proves them structurally, so a test there is usually
+ * redundant — usually, not never, which is exactly why this is overridable.
+ */
+const defaultFilter = (r: RequirementView): boolean =>
+  r.subType === REQUIREMENT_SUBTYPE_FUNCTIONAL &&
+  (r.level ?? 0) >= REQUIREMENT_LINK_FLOOR_LEVEL;
+
+const defaultPath = (view: RequirementView, concern: string): string =>
+  concern === NO_CONCERN
+    ? `${DEFAULT_STUB_DIR}${view.path}.test.ts`
+    : `${DEFAULT_STUB_DIR}${view.path}.${concern}.test.ts`;
+
+/** Exact concern → `type.*` → `*` → the built-in renderer. */
+function pickRenderer(
+  concern: string,
+  opts: RequirementTestsOpts,
+): RequirementTestRenderer {
+  const viaFn = opts.resolveRenderer?.(concern);
+  if (viaFn !== undefined) return viaFn;
+  const map = opts.renderers ?? {};
+  const typeOnly = `${concern.split(".")[0] ?? ""}.*`;
+  return map[concern] ?? map[typeOnly] ?? map[NO_CONCERN] ?? renderRequirementTest;
+}
+
+function attrString(node: { attr: (n: string) => unknown }, name: string): string {
+  const v = node.attr(name);
+  return typeof v === "string" ? v : "";
+}
+
+export function requirementTests(opts: RequirementTestsOpts = {}): Generator {
+  const filter = opts.filter ?? defaultFilter;
+  const toPath = opts.path ?? defaultPath;
+  // A custom `path` with no custom `owns` leaves the default namespace pointing
+  // somewhere the generator no longer writes, so reconciliation matches nothing.
+  // That degrades safely — it can only ever delete less — but silently, and a
+  // policy nobody can tell isn't running is the failure mode §5 is about.
+  const namespaceUnknown = opts.path !== undefined && opts.owns === undefined;
+
+  const generator: Generator = {
+    name: opts.name ?? "requirement-tests",
+    generate: (ctx: GenContext): EmittedFile[] => {
+      const files: EmittedFile[] = [];
+      const uncovered: string[] = [];
+
+      if (namespaceUnknown && opts.reconcileOrphans !== false) {
+        ctx.warn(
+          `a custom 'path' was supplied without a matching 'owns', so a stub left ` +
+            `behind by a deleted requirement will NOT be cleaned up. Supply 'owns' ` +
+            `to describe where 'path' writes, or set reconcileOrphans: false.`,
+        );
+      }
+
+      for (const walked of walkRequirements(ctx.loadedRoot)) {
+        if (!filter(walked.view)) {
+          uncovered.push(walked.view.path);
+          continue;
+        }
+        for (const [concern, targets] of groupByConcern(walked)) {
+          const args: RequirementTestArgs = {
+            view: walked.view,
+            concern,
+            targets,
+            statement: attrString(walked.node, REQUIREMENT_ATTR_STATEMENT),
+            counterexample: attrString(walked.node, REQUIREMENT_ATTR_COUNTEREXAMPLE),
+            disposition: walked.node.disposition(),
+            trackedBy: walked.node.trackedBy(),
+          };
+          files.push({
+            path: toPath(walked.view, concern),
+            content: pickRenderer(concern, opts)(args),
+          });
+        }
+      }
+
+      // Policy living only in config means an uncovered requirement is
+      // indistinguishable from a deliberate exclusion. One warning, never failing,
+      // so "no tests here" is a visible choice rather than silence.
+      if ((opts.warnUncovered ?? true) && uncovered.length > 0) {
+        // CAPPED, matching the runner's refusal message. The default filter excludes
+        // every architectural node and every L1-L3 functional one, so on the ledger
+        // shapes this repo's own docs describe — dozens to hundreds of entries — an
+        // uncapped list is a wall of dotted paths with the one actionable sentence
+        // buried at the end of it. This is a generator meant to be the feature's first
+        // contact; burying the opt-out is how it gets switched off wholesale.
+        const shown = uncovered.slice(0, MAX_NAMED_UNCOVERED).join(", ");
+        const more =
+          uncovered.length > MAX_NAMED_UNCOVERED
+            ? `, and ${uncovered.length - MAX_NAMED_UNCOVERED} more`
+            : "";
+        ctx.warn(
+          `${uncovered.length} requirement(s) matched no filter and get no stub. ` +
+            `If that is deliberate, set warnUncovered: false to silence this. ` +
+            `Uncovered: ${shown}${more}.`,
+        );
+      }
+
+      return files;
+    },
+  };
+
+  if (opts.target !== undefined) generator.target = opts.target;
+  if (opts.reconcileOrphans !== false) {
+    generator.orphanPolicy = {
+      // With a custom `path` and no `owns`, claim NOTHING rather than guess: the
+      // default namespace would be a claim over a directory this generator does
+      // not write to, and a wrong claim deletes another generator's files.
+      owns: opts.owns ?? (namespaceUnknown
+        ? () => false
+        : (relPath) => relPath.startsWith(DEFAULT_STUB_DIR)),
+      ...(opts.forceOrphanDelete === true && { force: true }),
+    };
+  }
+  return generator;
+}

package/src/generators/requirements-file.ts

@@ -0,0 +1,71 @@
+// server/typescript/packages/codegen-ts/src/generators/requirements-file.ts
+//
+// The `requirements` docs surface generator — emits the ledger as documentation.
+//
+// Design: docs/superpowers/specs/2026-08-21-requirements-doc-surface-design.md
+//
+// METADATA ALONE. `meta docs` guarantees output "from metadata ALONE — no gen config, no
+// codegen pipeline" (cli/src/commands/docs.ts). This generator reads `ctx.loadedRoot` and
+// NOTHING else — no filesystem walk, no config read, no test-source scan. That sentence
+// is what rules out reviving the retired `@verifiedBy` scan here, and it only keeps being
+// true if nobody adds a second input.
+//
+// AN EMPTY LEDGER EMITS ZERO FILES, not an empty page. That is a contract with the
+// surface wiring, not a cosmetic choice: `requirements` defaults to ON, and this is the
+// only reason that is a no-op for every project without a ledger.
+//
+// BOTH FILES, UNCONDITIONALLY — deliberately not behind a `--format` flag. `meta docs`
+// writes FILES, while `--format` on gen/migrate selects a STDOUT encoding; reusing the
+// name would make it mean something materially different on this command. A drift gate
+// also wants the machine-readable artifact committed regardless of who ran it or from
+// what kind of terminal.
+
+import {
+  type EmittedFile,
+  type Generator,
+  type GeneratorFactory,
+  oncePerRun,
+} from "../generator.js";
+import { renderRequirementsMarkdown } from "./requirements-markdown.js";
+import { renderRequirementsToon } from "./requirements-toon.js";
+import { requirementRows } from "./requirements-view.js";
+
+/** The human-facing index. */
+const MARKDOWN_FILENAME = "requirements.md";
+/** The machine-facing artifact — see requirements-toon.ts for why TOON. */
+const TOON_FILENAME = "requirements.toon";
+
+export interface RequirementsFileOpts {
+  /** Output directory prefix relative to the target's outDir. Default: "" (root). */
+  outDir?: string;
+  /** Optional named output target (registry key). Defaults to "default". */
+  target?: string;
+}
+
+export const requirementsFile = function requirementsFile(
+  opts?: RequirementsFileOpts,
+): Generator {
+  const dirPrefix = opts?.outDir ? `${opts.outDir.replace(/\/$/, "")}/` : "";
+
+  const generator: Generator = {
+    name: "requirements-file",
+    generate: oncePerRun((_entities, ctx) => {
+      const rows = requirementRows(ctx.loadedRoot);
+      // The one early return that matters. Both renderers also return "" for an empty
+      // ledger, so this is belt-and-braces — but the guarantee callers depend on is
+      // "zero FILES", which only this line can provide.
+      if (rows.length === 0) return [];
+
+      const files: EmittedFile[] = [
+        { path: `${dirPrefix}${MARKDOWN_FILENAME}`, content: renderRequirementsMarkdown(rows) },
+        { path: `${dirPrefix}${TOON_FILENAME}`, content: renderRequirementsToon(rows) },
+      ];
+      return files;
+    }),
+  };
+
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RequirementsFileOpts>;

package/src/generators/requirements-markdown.ts

@@ -0,0 +1,72 @@
+// server/typescript/packages/codegen-ts/src/generators/requirements-markdown.ts
+//
+// The human-facing half of the `requirements` docs surface — shape A, one index page.
+//
+// Design: docs/superpowers/specs/2026-08-21-requirements-doc-surface-design.md §4, §5
+//
+// ONE PAGE, NOT ONE PER NODE. Shape B (a page per top-level requirement) was measured
+// and dominated: 19 files and ~30.5K tokens against ~11.9K for the index, with one page
+// at 86KB. An 86KB page is not a documentation page.
+//
+// NO TEST LINK IS RENDERED, under any input (§3). With `@verifiedBy` retired there is no
+// join key, so there is nothing honest to print — and a derived path would read as MORE
+// authoritative than an author-chosen string, not less. Silence here is consistent with
+// five shipped statements that a requirement carrying no test link is a legitimate
+// declared state; it is not a gap waiting to be filled by whoever notices it next.
+//
+// PROSE LIVES HERE, STRUCTURE LIVES IN THE TOON SIBLING. TOON quotes every comma-bearing
+// string, so statements and violations dilute it badly. The split is not stylistic.
+
+import type { RequirementRow } from "./requirements-view.js";
+
+/** `##` for a root-level requirement, deepening with nesting. `#` is the page title. */
+function heading(depth: number): string {
+  return "#".repeat(Math.min(depth + 2, 6));
+}
+
+/** The one-line fact bar: the attrs that are scannable rather than readable. */
+function facts(r: RequirementRow): string {
+  const parts: string[] = [`\`${r.subType}\``];
+  if (r.level !== undefined) parts.push(`**L${r.level}**`);
+  if (r.status !== undefined) parts.push(`status: \`${r.status}\``);
+  // Absent `@disposition` means UNDECIDED, which is a real state and not the same as
+  // "no gap" — so it is omitted rather than rendered as a default.
+  if (r.disposition !== undefined) parts.push(`disposition: \`${r.disposition}\``);
+  if (r.trackedBy.length > 0) parts.push(`tracked: ${r.trackedBy.join(", ")}`);
+  return parts.join(" · ");
+}
+
+function renderOne(r: RequirementRow): string {
+  const out: string[] = [`${heading(r.depth)} ${r.path}`, "", facts(r), ""];
+
+  if (r.statement !== undefined) out.push(r.statement, "");
+  // The prescriptive pair. A requirement MUST be violable, so the counterexample is not
+  // decoration — it is what makes the statement checkable, and it reads beside it.
+  if (r.counterexample !== undefined) out.push(`**Counterexample:** ${r.counterexample}`, "");
+  if (r.description !== undefined) out.push(r.description, "");
+
+  if (r.implementedBy.length > 0) {
+    out.push(`**Implemented by:** ${r.implementedBy.map((c) => `\`${c}\``).join(", ")}`, "");
+  }
+
+  return out.join("\n");
+}
+
+/**
+ * Render the ledger as one markdown index.
+ *
+ * Returns the EMPTY STRING for an empty ledger rather than a headed-but-empty page.
+ * The generator keys on that to emit no file at all, which is in turn what lets the
+ * surface default to on without changing output for any project lacking a ledger.
+ */
+export function renderRequirementsMarkdown(rows: readonly RequirementRow[]): string {
+  if (rows.length === 0) return "";
+
+  return [
+    "# Requirements",
+    "",
+    `${rows.length} declared requirement${rows.length === 1 ? "" : "s"}, in declaration order.`,
+    "",
+    ...rows.map(renderOne),
+  ].join("\n");
+}

package/src/generators/requirements-toon.ts

@@ -0,0 +1,64 @@
+// server/typescript/packages/codegen-ts/src/generators/requirements-toon.ts
+//
+// The machine-facing half of the `requirements` docs surface.
+//
+// Design: docs/superpowers/specs/2026-08-21-requirements-doc-surface-design.md §5
+//
+// CHOSEN FOR THE DECLARED-COUNT HEADER, NOT THE TOKEN SAVING. Measured with this same
+// encoder on 321 rows, TOON is 42.1% smaller than JSON but only 7.3% smaller than a
+// markdown table — a table is already header-once, so compression is close to a
+// non-argument. What it buys is the header:
+//
+//   requirements[321]{path,level,status,claims,statement}:
+//
+// A reader can verify it received all 321 rows. A documentation generator that silently
+// drops rows produces a document that looks complete and is not, and this is the one
+// cheap defence against that.
+//
+// PROSE IS DELIBERATELY THIN HERE. TOON quotes every comma-bearing string, so statements
+// dilute the format badly. The readable half lives in the markdown sibling; this file
+// carries structure. That split is the reason both are emitted rather than one.
+//
+// `notes` NEVER APPEARS — RequirementRow does not carry it (documentation.json charters
+// it internal-only). Nothing to strip, by construction.
+
+import { encode } from "@toon-format/toon";
+import type { RequirementRow } from "./requirements-view.js";
+
+/** The row shape the artifact declares. Field ORDER is the wire contract — a reader
+ *  diffing two runs sees a reordering as noise, so it is fixed here rather than left
+ *  to object-literal order elsewhere. */
+interface ToonRow {
+  readonly path: string;
+  readonly subType: string;
+  readonly level: number | string;
+  readonly status: string;
+  readonly disposition: string;
+  readonly claims: string;
+  readonly statement: string;
+}
+
+/** TOON is tabular: a field absent on one row and present on another breaks the uniform
+ *  header. So every optional value collapses to "" rather than being omitted — an empty
+ *  cell reads as absent without costing the header its shape. */
+function cell(v: string | undefined): string {
+  return v ?? "";
+}
+
+export function renderRequirementsToon(rows: readonly RequirementRow[]): string {
+  if (rows.length === 0) return "";
+
+  const table: ToonRow[] = rows.map((r) => ({
+    path: r.path,
+    subType: r.subType,
+    level: r.level ?? "",
+    status: cell(r.status),
+    disposition: cell(r.disposition),
+    // Joined rather than nested: a nested array per row would cost the tabular header,
+    // which is the entire reason this format was picked.
+    claims: r.implementedBy.join(" "),
+    statement: cell(r.statement),
+  }));
+
+  return encode({ requirements: table });
+}

package/src/generators/requirements-view.ts

@@ -0,0 +1,93 @@
+// server/typescript/packages/codegen-ts/src/generators/requirements-view.ts
+//
+// The projected row the `requirements` docs surface renders from.
+//
+// Design: docs/superpowers/specs/2026-08-21-requirements-doc-surface-design.md
+//
+// PROJECTS OVER `walkRequirements()`, NEVER RE-WALKS. That walk already resolves the
+// depth-first traversal, the dotted `path` (hierarchy IS nesting), and the
+// `@implementedBy` targets, and it is what `requirementTests()` is built on. Sharing it
+// means the doc view and the generated stubs agree about what the ledger contains by
+// construction; two walks kept in step by hand is exactly the drift this surface exists
+// to remove.
+//
+// `notes` IS DELIBERATELY ABSENT FROM THIS TYPE, not merely unread. `documentation.json`
+// charters it internal-only, never emitted to a user-facing doc surface, and the
+// original ask this design replaced wanted a "stripper" for precisely this. A renderer
+// cannot leak a field the projection never carries — which is a stronger guarantee than
+// asking every renderer to remember.
+//
+// RESOLVING ACCESSORS ONLY (ADR-0039). Every read below goes through MetaRequirement's
+// resolving accessors or the resolving `attr()`, so a requirement that `extends` an
+// abstract parent inherits its `@level` / `@status` / statement rather than projecting
+// them as undefined. No `own*()` call belongs in this file.
+
+import {
+  DOC_ATTR_DESCRIPTION,
+  REQUIREMENT_ATTR_STATEMENT,
+  REQUIREMENT_ATTR_COUNTEREXAMPLE,
+} from "@metaobjectsdev/metadata";
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { walkRequirements } from "../requirement-walk.js";
+
+/** One requirement, projected for rendering. Ordered depth-first, declaration order. */
+export interface RequirementRow {
+  /** Dotted child-name path from the root — the same address every other node uses. */
+  readonly path: string;
+  /** 0 for a root-level requirement. Derived from `path`, so it cannot disagree with it. */
+  readonly depth: number;
+  /** "functional" | "architectural" — the check-polarity axis. */
+  readonly subType: string;
+  /** Undefined on an unlevelled architectural requirement (the flat policy form). */
+  readonly level: number | undefined;
+  readonly status: string | undefined;
+  readonly disposition: string | undefined;
+  readonly trackedBy: readonly string[];
+  readonly statement: string | undefined;
+  readonly counterexample: string | undefined;
+  /** Chartered user-facing. `notes` has no counterpart here, by design. */
+  readonly description: string | undefined;
+  /** `@implementedBy` exactly as authored — provenance a reader can grep for. */
+  readonly implementedBy: readonly string[];
+  /** DISTINCT `type.subType` concerns among the targets that actually resolved. */
+  readonly claimedConcerns: readonly string[];
+}
+
+/** Reads a resolving string attr, normalising "declared but empty" to undefined so a
+ *  renderer has one absent-case to handle rather than two. */
+function stringAttr(node: MetaData, name: string): string | undefined {
+  // `attr()` is the RESOLVING accessor in TypeScript (ADR-0039). Note the cross-port
+  // naming inversion this repo records: Python's `attr()` is own-only, TS's resolves.
+  const raw = node.attr(name);
+  if (typeof raw !== "string") return undefined;
+  return raw.length > 0 ? raw : undefined;
+}
+
+/**
+ * Project every `requirement.*` node — nested ones included — into render-ready rows.
+ *
+ * Returns `[]` for a model declaring no requirements, which is what lets the surface
+ * emit NOTHING rather than an empty page, and is in turn what makes turning the surface
+ * on by default a no-op for every project without a ledger.
+ */
+export function requirementRows(root: MetaData): RequirementRow[] {
+  return walkRequirements(root).map((walked) => {
+    const { node, view, targets } = walked;
+    return {
+      path: view.path,
+      // Derived rather than threaded: a separately-tracked depth could drift from the
+      // path that renders beside it, and there is only one right answer.
+      depth: view.path.split(".").length - 1,
+      subType: view.subType,
+      level: view.level,
+      status: view.status,
+      disposition: node.disposition(),
+      trackedBy: node.trackedBy(),
+      statement: stringAttr(node, REQUIREMENT_ATTR_STATEMENT),
+      counterexample: stringAttr(node, REQUIREMENT_ATTR_COUNTEREXAMPLE),
+      description: stringAttr(node, DOC_ATTR_DESCRIPTION),
+      implementedBy: node.implementedBy(),
+      claimedConcerns: [...new Set(targets.map((t) => t.concern))],
+    };
+  });
+}