@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/probe_inputs.ts

@@ -0,0 +1,271 @@
+/**
+ * `probe_inputs` — what the UI-conformance probe read, in a form its reader can
+ * re-check without starting a browser.
+ *
+ * `ui-conformance.json` recorded `generated_at` and nothing about its inputs, so
+ * a probe run before the last UI edit was indistinguishable from one run after
+ * it. This module is the shared vocabulary that closes that: the probe writes an
+ * `inputs` block with a content digest per input, and the design-pass reader
+ * recomputes those digests and compares. ONE definition, imported by both sides,
+ * because a producer and a consumer with separate copies of a hash rule agree
+ * only until one of them is edited.
+ *
+ * DIGESTS, NOT MTIMES, AND THAT IS THE WHOLE DECISION (D1). The reader already
+ * applies an mtime rule to the ui-audit artefact, and reusing it here was the
+ * obvious move. It answers the wrong question: an mtime moves on a checkout, a
+ * `cp -p`-less copy, or a bare `touch`, so it would report movement on turns
+ * where no byte changed — and a reader who learns to ignore a false stale has
+ * learned to ignore a real one. A content digest reports exactly what is being
+ * asked: are the bytes the probe saw still the bytes on disk?
+ *
+ * THE TARGET DIGEST IS A TREE DIGEST, and this is the one place the roadmap's
+ * own text needed correcting. A UI surface is an entry document plus the styles
+ * and scripts beside it; a digest of `index.html` alone would be blind to a CSS
+ * edit, which is the single most common UI change there is — and the roadmap's
+ * own verify line for step 1.1 names exactly that case. So the record covers the
+ * directory the entry document sits in. It costs a small recursive read the
+ * probe does not otherwise perform (the browser, not Node, opens `styles.css`),
+ * which is a real cost the roadmap's Risk 3 mitigation did not anticipate. It is
+ * bounded: a few small text files against a run that launches Chromium and
+ * reloads the page dozens of times per node.
+ *
+ * NO BROWSER IS REACHABLE FROM HERE. This module imports `node:crypto`,
+ * `node:fs` and `node:path` and nothing else, which is what lets the hook decide
+ * staleness on a host with no browser binaries installed.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Schema of the `inputs` block. A reader that does not know it says unknown. */
+export const INPUTS_SCHEMA = 'ui-conformance-inputs/v1';
+
+/**
+ * The probe build that wrote the block. Bumped when a change to the probe makes
+ * an older artefact's findings incomparable with a newer run's; a reader seeing
+ * a value it does not know reports unknown rather than guessing.
+ */
+export const PROBE_VERSION = 'ui-conformance-probe/v1';
+
+/** The sibling file the probe reads for declared, approved deviations. */
+export const DECLARATIONS_BASENAME = 'conformance.declared.json';
+
+/**
+ * Bound on a tree digest. A surface directory is a handful of files; anything
+ * past this is a checkout root someone pointed the probe at by mistake, and
+ * hashing it would cost more than the probe run. Exceeding it is recorded as
+ * absent with a reason — never silently truncated, which would produce a digest
+ * that looks authoritative and covers an arbitrary subset.
+ */
+export const MAX_TREE_FILES = 2000;
+
+/** Directories never worth digesting, and ruinous to walk. */
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+export const INPUT_KEYS = ['target', 'reference', 'declarations'] as const;
+export type InputKey = (typeof INPUT_KEYS)[number];
+
+export interface InputRecord {
+    /**
+     * What was digested — a directory for `tree`, a file for `file`. `null` only
+     * when no path was supplied at all, which is itself recorded rather than
+     * omitted.
+     */
+    path: string | null;
+    kind: 'tree' | 'file';
+    /** `absent` carries a reason and a null digest. Never an omitted key. */
+    state: 'read' | 'absent';
+    /** `sha256:<hex>` when read, `null` when absent. */
+    digest: string | null;
+    /** Files folded into a tree digest. Absent on a `file` record. */
+    files?: number;
+    reason?: string;
+}
+
+export interface ProbeInputs {
+    schema: string;
+    probe: string;
+    target: InputRecord;
+    reference: InputRecord;
+    declarations: InputRecord;
+}
+
+const sha256 = (data: Buffer | string): string => `sha256:${createHash('sha256').update(data).digest('hex')}`;
+
+const why = (err: unknown): string => {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    return code ? String(code) : String(err);
+};
+
+/**
+ * The ONE definition of where a target's declarations file lives. The probe's
+ * CLI computed this inline; a second copy here would be a rule that agrees with
+ * the probe only until one of the two is edited.
+ */
+export function declarationsPathFor(targetEntryFile: string): string {
+    return path.join(path.dirname(targetEntryFile), DECLARATIONS_BASENAME);
+}
+
+/** Digest one file. Never throws — an unreadable input is a recorded fact. */
+export function digestFile(file: string | null, whenNull = 'no path was supplied'): InputRecord {
+    if (!file) return { path: null, kind: 'file', state: 'absent', digest: null, reason: whenNull };
+    try {
+        return { path: file, kind: 'file', state: 'read', digest: sha256(fs.readFileSync(file)) };
+    } catch (err) {
+        return { path: file, kind: 'file', state: 'absent', digest: null, reason: `unreadable: ${why(err)}` };
+    }
+}
+
+/**
+ * Digest a directory as one value: every file under it, sorted by relative path,
+ * folded path-and-content into a single hash. Sorted because a directory listing
+ * order is a filesystem detail, and a digest that moved with it would report
+ * movement nobody made.
+ *
+ * `exclude` drops names recorded as inputs in their own right — the declarations
+ * file — so an edit to it moves exactly one digest rather than two.
+ */
+export function digestTree(
+    dir: string | null,
+    exclude: readonly string[] = [],
+    whenNull = 'no path was supplied',
+): InputRecord {
+    if (!dir) return { path: null, kind: 'tree', state: 'absent', digest: null, reason: whenNull };
+    const skip = new Set(exclude);
+    const found: string[] = [];
+
+    const walk = (rel: string): string | null => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true });
+        } catch (err) {
+            return `unreadable: ${why(err)}`;
+        }
+        for (const e of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const child = rel ? `${rel}/${e.name}` : e.name;
+            if (rel === '' && skip.has(e.name)) continue;
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name)) continue;
+                const failed = walk(child);
+                if (failed) return failed;
+                continue;
+            }
+            if (!e.isFile()) continue;
+            found.push(child);
+            if (found.length > MAX_TREE_FILES) {
+                return `directory holds more than ${MAX_TREE_FILES} files — too large to digest`;
+            }
+        }
+        return null;
+    };
+
+    const failure = walk('');
+    if (failure) return { path: dir, kind: 'tree', state: 'absent', digest: null, reason: failure };
+
+    const h = createHash('sha256');
+    for (const rel of found.sort()) {
+        let body: Buffer;
+        try {
+            body = fs.readFileSync(path.join(dir, rel));
+        } catch (err) {
+            return { path: dir, kind: 'tree', state: 'absent', digest: null, reason: `unreadable: ${why(err)}` };
+        }
+        // The path is folded in alongside the bytes, so a rename moves the digest
+        // even when the content is byte-identical.
+        h.update(rel).update('\0').update(body).update('\0');
+    }
+    return {
+        path: dir,
+        kind: 'tree',
+        state: 'read',
+        digest: `sha256:${h.digest('hex')}`,
+        files: found.length,
+    };
+}
+
+/**
+ * The block the probe writes beside `generated_at`. A target or reference is
+ * digested as the surface directory it belongs to; the declarations file is
+ * digested on its own.
+ */
+export function collectInputs(targetEntryFile: string | null, referenceEntryFile: string | null): ProbeInputs {
+    const dirOf = (f: string | null): string | null => (f ? path.dirname(f) : null);
+    return {
+        schema: INPUTS_SCHEMA,
+        probe: PROBE_VERSION,
+        target: digestTree(dirOf(targetEntryFile), [DECLARATIONS_BASENAME], 'no --target was supplied'),
+        reference: digestTree(
+            dirOf(referenceEntryFile),
+            [DECLARATIONS_BASENAME],
+            'no --reference was given; nothing was compared against',
+        ),
+        declarations: targetEntryFile
+            ? digestFile(declarationsPathFor(targetEntryFile))
+            : digestFile(null, 'no --target was supplied, so no declarations file was looked for'),
+    };
+}
+
+export type InputComparison =
+    | { verdict: 'unknown'; reason: string; moved: readonly InputKey[] }
+    | { verdict: 'unchanged'; moved: readonly InputKey[] }
+    | { verdict: 'moved'; moved: readonly InputKey[] };
+
+const isRecord = (v: unknown): v is InputRecord =>
+    typeof v === 'object' && v !== null && 'state' in (v as object) && 'kind' in (v as object);
+
+/**
+ * Re-read each recorded input and say whether it moved.
+ *
+ * THREE verdicts, and `unknown` is not a hedge. An artefact written before the
+ * `inputs` block existed has nothing to compare, and calling that `moved` would
+ * report stale for every pre-existing run on the first turn after this change —
+ * Risk 1 of the roadmap. It is a version skew, not evidence of movement, and it
+ * is equally not evidence of freshness.
+ *
+ * `resolve` maps a recorded path to this host's filesystem; the caller owns that
+ * because the probe records the path it was given and only the reader knows the
+ * root it is reading from.
+ */
+export function compareInputs(recorded: unknown, resolve: (p: string) => string): InputComparison {
+    if (typeof recorded !== 'object' || recorded === null) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: 'the artefact carries no inputs block — it predates the input digests',
+        };
+    }
+    const r = recorded as Partial<ProbeInputs>;
+    if (r.schema !== INPUTS_SCHEMA) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: `inputs schema ${String(r.schema)} is not ${INPUTS_SCHEMA} — this reader cannot compare it`,
+        };
+    }
+    if (r.probe !== PROBE_VERSION) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: `written by ${String(r.probe)}, read by ${PROBE_VERSION} — findings across builds are not comparable`,
+        };
+    }
+
+    const moved: InputKey[] = [];
+    for (const key of INPUT_KEYS) {
+        const rec = r[key];
+        if (!isRecord(rec)) {
+            return {
+                verdict: 'unknown',
+                moved: [],
+                reason: `the inputs block carries no usable record for ${key}`,
+            };
+        }
+        // An input that was never supplied has nothing to move to or from.
+        if (rec.path === null) continue;
+        const here = rec.kind === 'tree'
+            ? digestTree(resolve(rec.path), [DECLARATIONS_BASENAME])
+            : digestFile(resolve(rec.path));
+        if (here.state !== rec.state || here.digest !== rec.digest) moved.push(key);
+    }
+    return moved.length ? { verdict: 'moved', moved } : { verdict: 'unchanged', moved: [] };
+}

package/src/scripts/_lib/read_surface_scan.ts

@@ -0,0 +1,322 @@
+/**
+ * Read-surface scanner — derive the sanitize floor's coverage list from the
+ * imports, not from intent
+ * (road-to-a-sanitize-list-that-is-generated, Phase 1).
+ *
+ * WHY A SCANNER AND NOT A LIST
+ * ----------------------------
+ * `retrieval_sanitize.ts` used to carry a hand-maintained prose list of the
+ * read surfaces it covers, with its own header stating the rule for anything
+ * not on it: uncovered. That list went wrong in both directions — a path that
+ * reaches the outside world and IS sanitized was absent from it, and two paths
+ * carrying fetched bytes toward a model-facing surface were neither listed nor
+ * covered. The header already recorded the same failure happening once before,
+ * for the same reason: a list maintained by hand records what its author meant,
+ * and the tree records what the code does.
+ *
+ * This module derives the list. A row cannot disagree with the tree, because
+ * the tree is the only thing it reads.
+ *
+ * WHAT A ROW MEANS, AND WHAT IT DOES NOT
+ * --------------------------------------
+ * A row says a module matched an INBOUND shape — a recognised way outside bytes
+ * enter this process — and whether that module imports the sanitize floor. It
+ * does not say the floor is applied to the right string, at the right point, or
+ * at all: an import is evidence of intent, and only a read of the module
+ * establishes the rest. `covered` here means "the floor is in scope in this
+ * module", never "this module is safe".
+ *
+ * THE MISSING-ROW FAILURE, AND WHY `unclassified` EXISTS
+ * -----------------------------------------------------
+ * A generated table carries an authority a hand-written one never claimed, so
+ * its worst failure is not a wrong row — it is an ABSENT one. A fetch shape the
+ * scanner does not recognise produces no row, and a missing row reads as "no
+ * surface here".
+ *
+ * Two things push back. Inbound shapes are plural and named (a `fetch`, a
+ * `node:http(s)` request, a subprocess of a remote-fetching tool, a parse of
+ * markup arriving on stdin) rather than a single pattern. And a WEAK shape —
+ * a network call reached through an injected or computed callee, which the
+ * strong detectors cannot see — still emits a row, marked `unclassified`, so an
+ * unrecognised shape appears in the table as a visible gap instead of as
+ * silence. The residual is stated in the table's own header rather than left
+ * for a reader to discover: a module whose network access is reached through a
+ * shape matching neither set is still absent.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Coverage verdict for one read surface. */
+export type SurfaceCoverage = 'covered' | 'uncovered' | 'unclassified';
+
+/** One module that brings outside bytes in and hands a string onward. */
+export interface ReadSurfaceRow {
+    /** Path relative to `src/scripts/`, POSIX separators. */
+    readonly module: string;
+    /** Inbound shape id that matched. */
+    readonly inbound: string;
+    /** Emit shape id that matched, or `undecided`. */
+    readonly emit: string;
+    readonly coverage: SurfaceCoverage;
+    /** Why the row reads the way it does — one clause, no paraphrase. */
+    readonly evidence: string;
+}
+
+interface ShapeDetector {
+    readonly id: string;
+    /** True when this module's source carries the shape. */
+    readonly match: (src: string) => boolean;
+}
+
+/** True when the module imports node's HTTP client at all. */
+function _importsNodeHttp(src: string): boolean {
+    return /from\s+['"]node:https?['"]/.test(src);
+}
+
+/**
+ * Strong inbound shapes — a recognised way outside bytes enter this process.
+ *
+ * Each is deliberately narrow. `await fetch(` rather than `fetch(` keeps a
+ * fetch call named inside a string literal (a spawned one-liner, a doc example)
+ * out of the table; the node-HTTP shape requires the import as well as the call
+ * so a `.get(` on an unrelated object cannot produce a row.
+ */
+export const STRONG_INBOUND: readonly ShapeDetector[] = [
+    {
+        id: 'network-fetch',
+        match: (s) => /\bawait\s+fetch\s*\(/.test(s),
+    },
+    {
+        id: 'node-http-request',
+        match: (s) => _importsNodeHttp(s) && /\bhttps?\s*\.\s*(?:get|request)\s*\(/.test(s),
+    },
+    {
+        id: 'remote-subprocess',
+        match: (s) =>
+            /\b(?:spawnSync|spawn|execSync|execFileSync|execFile)\s*\(\s*\[?\s*['"`](?:curl|wget|gh)['"`]/.test(s),
+    },
+    {
+        id: 'stdin-markup-parse',
+        match: (s) =>
+            /\bprocess\s*\.\s*stdin\b/.test(s) && /&(?:amp|lt|gt|quot|nbsp|#x?[0-9a-f]+);/i.test(s),
+    },
+    {
+        id: 'declared',
+        match: (s) => _DECLARATION_RE.test(s),
+    },
+];
+
+/**
+ * A module may declare its own inbound shape when no syntactic one captures it.
+ *
+ * The shapes above are all things the scanner can SEE. A host primitive cannot
+ * be seen: a subagent reply, an MCP tool result and a host file-read arrive
+ * through a channel this package does not own, so no call site in this tree
+ * spells them. Risk 1 of the roadmap that produced this scanner names exactly
+ * that class, and the answer it demands is a visible row rather than silence.
+ *
+ * The marker is a comment at the site — `// read-surface: <shape-id>` — not a
+ * line in a central list, which is the arrangement this whole module exists to
+ * retire. A declaration says only "outside bytes arrive here"; the coverage
+ * verdict is still read from the imports, so declaring a surface cannot make it
+ * read `covered`.
+ */
+const _DECLARATION_RE = /\/\/\s*read-surface:\s*([a-z0-9-]+)/;
+
+/** `git` is deliberately NOT a remote command above. */
+export const LOCAL_VCS_EXCLUSION =
+    'a `git` subprocess reads local repository state, not outside bytes, so it is not an ' +
+    'inbound shape. `git fetch` and `git ls-remote` move refs rather than content and are ' +
+    'excluded with the rest — a branch name is attacker-influenceable in principle, and if ' +
+    'that ever reaches a model-facing surface it needs its own row, not a widened matcher ' +
+    'that would re-add every local `git status` wrapper in the tree.';
+
+/**
+ * Weak inbound shapes — a network call the strong detectors cannot resolve.
+ *
+ * `await this._fetch(url, …)` is a real HTTP request behind an injected
+ * dependency, which is exactly the shape a strong matcher on `await fetch(`
+ * misses. It produces a row rather than silence; the verdict is
+ * `unclassified`, because the scanner cannot tell an injected fetch from an
+ * injected stub without executing it.
+ */
+export const WEAK_INBOUND: readonly ShapeDetector[] = [
+    {
+        id: 'indirect-fetch',
+        match: (s) => /\bawait\s+(?:this|self|[a-z_$][\w$]*)\s*\.\s*_?fetch\s*\(/i.test(s),
+    },
+];
+
+/** Recognised ways a module hands a string onward. */
+export const EMIT_SHAPES: readonly ShapeDetector[] = [
+    { id: 'file-write', match: (s) => /\b(?:writeFileSync|appendFileSync|writeFile)\s*\(/.test(s) },
+    { id: 'stdout-write', match: (s) => /\bprocess\s*\.\s*stdout\s*\.\s*write\s*\(/.test(s) },
+    { id: 'exported-api', match: (s) => /^export\s+(?:async\s+)?function\s/m.test(s) },
+];
+
+/** The sanitize floor, as an import. One hop; a transitive import is not counted. */
+const _SANITIZE_IMPORT_RE =
+    /import\s*\{[^}]*\b(?:sanitize_text|sanitize_entry|sanitize_markup)\b[^}]*\}\s*from\s*['"][^'"]*retrieval_sanitize(?:\.js)?['"]/;
+
+/** Test files under `src/scripts/` — fixtures, not surfaces that ship bytes. */
+const _EXCLUDE_RE = /(?:^|\/)(?:__tests__|node_modules)\/|\.test\.ts$/;
+
+/**
+ * Modules that define or read the coverage rather than being a surface.
+ *
+ * The scanner and its gate quote every detector pattern above as a literal, so
+ * they match their own matchers. Excluding them by name is the honest fix: a
+ * row for the scanner would be an artefact of the scanner reading itself, and
+ * carrying it would train a reader to skip rows.
+ */
+const _SELF_MODULES: ReadonlySet<string> = new Set([
+    '_lib/retrieval_sanitize.ts',
+    '_lib/read_surface_scan.ts',
+    'check_read_surface_coverage.ts',
+]);
+
+/**
+ * Raised when a directory under the scan root cannot be read.
+ *
+ * The walk used to swallow the error and return, which made an INCOMPLETE scan
+ * indistinguishable from a complete one: a permission error on one subtree
+ * silently removed every module under it from the table, and the gate then
+ * reported the shortened list as matching the tree. An independent review named
+ * it; the direction is the same one `assertScanned` enforces at the corpus
+ * level, applied to the traversal that builds the corpus.
+ */
+export class ScanTraversalError extends Error {
+    constructor(readonly dir: string, cause: unknown) {
+        super(`read_surface_scan: cannot read ${dir} — the scan is incomplete, not clean (${String(cause)})`);
+        this.name = 'ScanTraversalError';
+    }
+}
+
+/**
+ * Directory reader, injectable for one reason: to test the failure.
+ *
+ * The fail-closed branch below can only be exercised by a `readdirSync` that
+ * throws, and on ESM `vi.spyOn(fs, 'readdirSync')` cannot redefine the
+ * namespace property. The alternative — chmod-000 on a real directory — is not
+ * portable, because under root the mode is no barrier and the test then fails
+ * in exactly the environment it was written to survive. A narrow seam is the
+ * honest shape: production passes nothing and gets `fs.readdirSync`.
+ */
+export type ReadDir = (dir: string) => fs.Dirent[];
+
+const _defaultReadDir: ReadDir = (dir) => fs.readdirSync(dir, { withFileTypes: true });
+
+function _walk(dir: string, base: string, out: string[], readDir: ReadDir): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = readDir(dir);
+    } catch (exc) {
+        throw new ScanTraversalError(dir, exc);
+    }
+    for (const e of entries) {
+        const abs = path.join(dir, e.name);
+        const rel = path.relative(base, abs).split(path.sep).join('/');
+        if (e.isDirectory()) {
+            _walk(abs, base, out, readDir);
+        } else if (e.isFile() && rel.endsWith('.ts') && !rel.endsWith('.d.ts') && !_EXCLUDE_RE.test(rel)) {
+            out.push(rel);
+        }
+    }
+}
+
+/** The scan root, repo-relative. Published so the gate can name it in an error. */
+export const SCAN_ROOT = 'src/scripts';
+
+/**
+ * Scan every TypeScript module under `src/scripts/` and return one row per
+ * module that both brings outside bytes in and hands a string onward.
+ *
+ * Rows are sorted by module path so the rendered table is stable across
+ * filesystems.
+ */
+export function scanReadSurfaces(repoRoot: string, readDir: ReadDir = _defaultReadDir): ReadSurfaceRow[] {
+    const base = path.join(repoRoot, SCAN_ROOT);
+    const files: string[] = [];
+    _walk(base, base, files, readDir);
+    files.sort();
+
+    const rows: ReadSurfaceRow[] = [];
+    for (const rel of files) {
+        if (_SELF_MODULES.has(rel)) continue;
+        let src: string;
+        try {
+            src = fs.readFileSync(path.join(base, rel), 'utf-8');
+        } catch {
+            continue;
+        }
+        const strong = STRONG_INBOUND.find((d) => d.match(src));
+        const weak = strong === undefined ? WEAK_INBOUND.find((d) => d.match(src)) : undefined;
+        if (strong === undefined && weak === undefined) continue;
+        // A declared surface reports the shape its own marker names, so the
+        // table says `ingested-corpus` rather than the detector's own id.
+        const strongId =
+            strong?.id === 'declared' ? (_DECLARATION_RE.exec(src)?.[1] ?? 'declared') : strong?.id;
+
+        const emit = EMIT_SHAPES.find((d) => d.match(src));
+        const sanitized = _SANITIZE_IMPORT_RE.test(src);
+
+        if (weak !== undefined) {
+            rows.push({
+                module: rel,
+                inbound: weak.id,
+                emit: emit?.id ?? 'undecided',
+                coverage: 'unclassified',
+                evidence: 'network access through a callee the scanner cannot resolve — read the module',
+            });
+            continue;
+        }
+        if (emit === undefined) {
+            rows.push({
+                module: rel,
+                inbound: strongId ?? 'unknown',
+                emit: 'undecided',
+                coverage: 'unclassified',
+                evidence: 'inbound bytes with no recognised emit — the onward path is undecided',
+            });
+            continue;
+        }
+        rows.push({
+            module: rel,
+            inbound: strongId ?? 'unknown',
+            emit: emit.id,
+            coverage: sanitized ? 'covered' : 'uncovered',
+            evidence: sanitized
+                ? 'imports the sanitize floor'
+                : 'no sanitize import — fetched bytes reach the emit unfiltered',
+        });
+    }
+    return rows;
+}
+
+/** Counts by verdict, for the gate's scanned line and for the table header. */
+export function tally(rows: readonly ReadSurfaceRow[]): Record<SurfaceCoverage, number> {
+    const out: Record<SurfaceCoverage, number> = { covered: 0, uncovered: 0, unclassified: 0 };
+    for (const r of rows) out[r.coverage] += 1;
+    return out;
+}
+
+/** Render the rows as the markdown table body committed to the contract doc. */
+export function renderTable(rows: readonly ReadSurfaceRow[]): string {
+    const lines = [
+        '| module (under `src/scripts/`) | inbound shape | emit shape | coverage | evidence |',
+        '|---|---|---|---|---|',
+    ];
+    for (const r of rows) {
+        lines.push(
+            `| \`${r.module}\` | \`${r.inbound}\` | \`${r.emit}\` | **${r.coverage}** | ${r.evidence} |`,
+        );
+    }
+    const t = tally(rows);
+    lines.push('');
+    lines.push(
+        `${String(rows.length)} read surface(s): ` +
+            `${String(t.covered)} covered, ${String(t.uncovered)} uncovered, ` +
+            `${String(t.unclassified)} unclassified.`,
+    );
+    return lines.join('\n');
+}