@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/_lib/adr_frontmatter.ts

@@ -0,0 +1,459 @@
+/**
+ * One ADR frontmatter reader, for the three call sites that each had their own.
+ *
+ * Before this file the tree carried three independent parsers:
+ * `check_adr_frontmatter.parse_frontmatter` (folded indented continuations into
+ * the parent scalar), `adr_cite_check.parse_frontmatter` (the same, plus
+ * stripping a bare `>-` fold marker), and `adr/regenerate_index.fm` (a
+ * `^([a-z_]+):[ \t]*(.+?)[ \t]*$` regex, so a key with an empty value matched
+ * nothing and an indented line matched nothing either).
+ *
+ * Three readers were survivable while every field was a scalar. `provenance`
+ * and `evidence` are nested and carry lists, so the divergence stops being
+ * cosmetic: the regex reader would have read both as absent — silently, on the
+ * surface that renders the public index — while the other two would have folded
+ * them into one unusable string. Adding an axis to three parsers also pays for
+ * it three times, which is the reason this extraction lands BEFORE the axes
+ * rather than after.
+ *
+ * ## Scalar compatibility is the contract
+ *
+ * `scalars` reproduces the previous behaviour key-for-key, including the fold
+ * of an indented continuation into its parent and the `>-` strip. That is
+ * deliberate: the three call sites read `fm.status`, `fm.review_trigger`,
+ * `fm.superseded_by` and friends, and a reader that changed any of those
+ * values would be a behaviour change wearing a refactor's clothes.
+ *
+ * The one intentional difference: a key whose own value is empty and whose
+ * indented children look like `key: value` (or `- item`) becomes a **nested**
+ * entry and is kept out of `scalars` entirely, rather than folded into the
+ * garbage string the old readers produced. Nothing read those strings.
+ */
+
+/** A frontmatter value that is not a scalar. */
+export type AdrFrontmatterNode = string | string[] | { [key: string]: AdrFrontmatterNode };
+
+export interface AdrFrontmatter {
+    /**
+     * Scalar keys, byte-identical to what the three previous parsers produced
+     * for every shape that existed before the nested axes.
+     */
+    scalars: Record<string, string>;
+    /** Keys whose value is a nested map or a list. */
+    nested: Record<string, AdrFrontmatterNode>;
+    /** Source order of every top-level key, for diagnostics. */
+    keyOrder: string[];
+}
+
+/** Fold indicators: the value is a multi-line scalar, never a nested map. */
+const FOLD_MARKERS = new Set(['>', '>-', '>+', '|', '|-', '|+']);
+
+/**
+ * Consume an indented block as prose, with no map/list discrimination.
+ *
+ * Used whenever the parent carried a fold marker. Routing a folded block
+ * through `parseBlock` looked equivalent and was not: real `review_trigger`
+ * prose contains colons ("Reopen when an `exec:` claim is found green"), so the
+ * map branch claimed the first line and then stopped at the first line without
+ * one — truncating four ADRs' triggers to their opening clause. The corpus
+ * equivalence test is what caught it; a single-line fixture round-tripped
+ * correctly and hid the bug.
+ */
+function consumeFolded(lines: Line[], start: number, parentIndent: number): [string, number] {
+    const parts: string[] = [];
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent <= parentIndent) break;
+        parts.push(line.text);
+        i += 1;
+    }
+    return [parts.join(' ').trim(), i];
+}
+
+const QUOTED = /^["'](.*)["']$/;
+
+function stripQuotes(value: string): string {
+    return value.replace(QUOTED, '$1');
+}
+
+/** `[a, b, c]` → `['a','b','c']`; a bare `[]` → `[]`. */
+function parseInlineList(raw: string): string[] | null {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return null;
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner
+        .split(',')
+        .map((part) => stripQuotes(part.trim()))
+        .filter((part) => part !== '');
+}
+
+interface Line {
+    indent: number;
+    text: string;
+}
+
+/** Split the `---` block into significant lines, dropping blanks and comments. */
+function significantLines(block: string): Line[] {
+    const out: Line[] = [];
+    for (const raw of block.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (line === '') continue;
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('#')) continue;
+        out.push({ indent: line.length - trimmed.length, text: trimmed });
+    }
+    return out;
+}
+
+/**
+ * Parse one indented block into a map, a list, or a folded scalar.
+ *
+ * The discriminator is the block's own first line, not the parent key: `- x`
+ * opens a list, `k: v` opens a map, anything else is prose to fold. Keying on
+ * the parent name would have meant a hard-coded field list, which is the thing
+ * three divergent parsers already demonstrated does not survive a new axis.
+ */
+function parseBlock(lines: Line[], start: number, parentIndent: number): [AdrFrontmatterNode, number] {
+    const first = lines[start];
+    if (first === undefined) return ['', start];
+
+    // A list.
+    if (first.text.startsWith('- ') || first.text === '-') {
+        const items: string[] = [];
+        let i = start;
+        while (i < lines.length) {
+            const line = lines[i] as Line;
+            if (line.indent <= parentIndent || !line.text.startsWith('-')) break;
+            items.push(stripQuotes(line.text.replace(/^-\s*/, '').trim()));
+            i += 1;
+        }
+        return [items, i];
+    }
+
+    // A map — every child line at this indent carries a `key:`.
+    const colon = first.text.indexOf(':');
+    if (colon > 0) {
+        const map: Record<string, AdrFrontmatterNode> = {};
+        let i = start;
+        while (i < lines.length) {
+            const line = lines[i] as Line;
+            if (line.indent <= parentIndent) break;
+            const idx = line.text.indexOf(':');
+            if (idx <= 0) break;
+            const key = line.text.slice(0, idx).trim();
+            const rest = line.text.slice(idx + 1).trim();
+            i += 1;
+            if (rest === '' || FOLD_MARKERS.has(rest)) {
+                const next = lines[i];
+                if (next !== undefined && next.indent > line.indent) {
+                    if (FOLD_MARKERS.has(rest)) {
+                        const [folded, consumed] = consumeFolded(lines, i, line.indent);
+                        map[key] = folded;
+                        i = consumed;
+                        continue;
+                    }
+                    const [child, consumed] = parseBlock(lines, i, line.indent);
+                    map[key] = child;
+                    i = consumed;
+                    continue;
+                }
+                map[key] = '';
+                continue;
+            }
+            const inline = parseInlineList(rest);
+            map[key] = inline ?? stripQuotes(rest);
+        }
+        return [map, i];
+    }
+
+    // Prose — fold it.
+    const parts: string[] = [];
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent <= parentIndent) break;
+        parts.push(line.text);
+        i += 1;
+    }
+    return [parts.join(' ').trim(), i];
+}
+
+/**
+ * Flatten a node back to the single string the old fold produced.
+ *
+ * A list renders as its inline literal (`[a, b]`) rather than as joined items,
+ * because that is what the previous parsers put in the scalar map for
+ * `protected_dimensions: [purpose]` and the corpus-equivalence test holds this
+ * reader to that byte-for-byte.
+ */
+function foldToString(node: AdrFrontmatterNode): string {
+    if (typeof node === 'string') return node;
+    if (Array.isArray(node)) return `[${node.join(', ')}]`;
+    return Object.entries(node)
+        .map(([k, v]) => `${k}: ${foldToString(v)}`)
+        .join(' ')
+        .trim();
+}
+
+/**
+ * Read the leading `---` block of an ADR.
+ *
+ * Returns `null` when there is no frontmatter at all — which is the honest
+ * answer for the seven per-area records, whose metadata lives in a blockquote
+ * line instead. `adr_cite_check` already declares them partial coverage for
+ * exactly this reason; this reader does not paper over it.
+ */
+export function readAdrFrontmatter(text: string): AdrFrontmatter | null {
+    if (!text.startsWith('---\n')) return null;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return null;
+
+    const lines = significantLines(text.slice(4, end));
+    const scalars: Record<string, string> = {};
+    const nested: Record<string, AdrFrontmatterNode> = {};
+    const keyOrder: string[] = [];
+
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent > 0) {
+            // Orphan indented line with no parent — the old readers dropped
+            // these too (no key to fold into). Skip rather than invent one.
+            i += 1;
+            continue;
+        }
+        const idx = line.text.indexOf(':');
+        if (idx <= 0) {
+            i += 1;
+            continue;
+        }
+        const key = line.text.slice(0, idx).trim();
+        const rest = line.text.slice(idx + 1).trim();
+        keyOrder.push(key);
+        i += 1;
+
+        const next = lines[i];
+        const hasBlock = next !== undefined && next.indent > 0;
+
+        if (FOLD_MARKERS.has(rest) && hasBlock) {
+            const [folded, consumed] = consumeFolded(lines, i, 0);
+            scalars[key] = folded;
+            i = consumed;
+            continue;
+        }
+
+        if (rest === '' && hasBlock) {
+            const [child, consumed] = parseBlock(lines, i, 0);
+            i = consumed;
+            if (typeof child === 'string') {
+                scalars[key] = child;
+            } else {
+                nested[key] = child;
+            }
+            continue;
+        }
+
+        const inline = parseInlineList(rest);
+        if (inline !== null) {
+            nested[key] = inline;
+            continue;
+        }
+
+        // A plain scalar with continuation lines — prose, as the old readers
+        // treated it. The same colon hazard applies here.
+        if (hasBlock) {
+            const [folded, consumed] = consumeFolded(lines, i, 0);
+            scalars[key] = `${stripQuotes(rest)} ${folded}`.trim();
+            i = consumed;
+            continue;
+        }
+        scalars[key] = stripQuotes(rest).replace(/^>-?$/, '');
+    }
+
+    return { scalars, nested, keyOrder };
+}
+
+/**
+ * The scalar-only view, for the call sites that want exactly what they had.
+ *
+ * A nested key is rendered back into its folded string here so a caller that
+ * only knows about scalars still sees *something* for `provenance` rather than
+ * `undefined` — which matters for the index reader, where an absent key and an
+ * empty key print differently.
+ */
+export function readAdrFrontmatterScalars(text: string): Record<string, string> | null {
+    const parsed = readAdrFrontmatter(text);
+    if (parsed === null) return null;
+    const out: Record<string, string> = { ...parsed.scalars };
+    for (const [key, node] of Object.entries(parsed.nested)) {
+        out[key] = foldToString(node);
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Typed accessors for the two axes. Deliberately tolerant: a census proposal
+// and a hand-authored record both flow through here, and a malformed value has
+// to be reportable rather than fatal.
+// ---------------------------------------------------------------------------
+
+export const PROVENANCE_KINDS = ['human', 'agentic', 'mixed', 'unknown'] as const;
+export type ProvenanceKind = (typeof PROVENANCE_KINDS)[number];
+
+export const AGENTIC_MODES = ['single', 'council', 'delegated'] as const;
+export const EVIDENCE_STRENGTHS = ['E0', 'E1', 'E2', 'E3', 'E4'] as const;
+export type EvidenceStrength = (typeof EVIDENCE_STRENGTHS)[number];
+
+export const DISCOVERY_STATES = ['complete', 'incomplete'] as const;
+export const AUTHORITY_BASES = ['evidence', 'owner_intent'] as const;
+
+export interface AdrProvenance {
+    kind: string | null;
+    decisionMakers: string[];
+    humanDirected: string | null;
+    agenticMode: string | null;
+}
+
+export interface AdrEvidence {
+    strength: string | null;
+    discovery: string | null;
+    basis: string[];
+}
+
+function asString(node: AdrFrontmatterNode | undefined): string | null {
+    if (typeof node === 'string') return node === '' ? null : node;
+    return null;
+}
+
+function asList(node: AdrFrontmatterNode | undefined): string[] {
+    if (Array.isArray(node)) return node;
+    if (typeof node === 'string' && node !== '') return [node];
+    return [];
+}
+
+export function provenanceOf(fm: AdrFrontmatter): AdrProvenance | null {
+    const node = fm.nested.provenance;
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) return null;
+    return {
+        kind: asString(node.kind),
+        decisionMakers: asList(node.decision_makers),
+        humanDirected: asString(node.human_directed),
+        agenticMode: asString(node.agentic_mode),
+    };
+}
+
+export function evidenceOf(fm: AdrFrontmatter): AdrEvidence | null {
+    const node = fm.nested.evidence;
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) return null;
+    return {
+        strength: asString(node.strength),
+        discovery: asString(node.discovery),
+        basis: asList(node.basis),
+    };
+}
+
+export function authorityBasisOf(fm: AdrFrontmatter): string | null {
+    return fm.scalars.authority_basis ?? null;
+}
+
+/**
+ * Does this record's own metadata say a cite-time reader must NOT treat it as
+ * establishing that the alternatives remain invalid?
+ *
+ * True for an accepted record graded E0 or E1, whatever its provenance.
+ *
+ * **Provenance was in this predicate and has been removed** (neutral review,
+ * 2026-08-21). It required `kind === 'agentic'`, so an identical E0 record made
+ * by a human printed no notice at all. That was wrong on the claim's own terms:
+ * "this record does not by itself establish that alternatives remain invalid"
+ * is a statement about the strength of the EVIDENCE, and a human snapshot is
+ * exactly as thin as an agent snapshot. Gating it on who decided also sat one
+ * step sideways from `adr-layout`'s own line that a record's historical
+ * decision-maker does not determine how it is treated on citation.
+ *
+ * `authority_basis: owner_intent` is the one exemption, and it is the RIGHT
+ * discriminator where provenance was the wrong one. An owner purpose statement
+ * is legitimately E0 — that is the honest form — and its alternatives ARE
+ * foreclosed, by ownership rather than by evidence. Printing "this does not
+ * establish that alternatives remain invalid" over it would be false. The
+ * declared field says which kind of authority a record rests on, so it is the
+ * field that decides, and the burden table already reads `owner_intent` as
+ * binding until the owner changes it.
+ *
+ * That is also why the earlier provenance gate was subtly wrong rather than
+ * simply wrong: it was reaching for this exemption and grabbing a correlate.
+ * Most owner-intent records are human-made, so `kind === 'agentic'` approximated
+ * it — and silently withheld the notice from every thin HUMAN record that
+ * carried no owner claim at all.
+ *
+ * The name says `lowEvidence` rather than `provisionalAuthority` for a second
+ * reason from the same review: ADR-239 and the roadmap both explicitly REJECT
+ * the word "provisional" for this output, because it asserts a permission that
+ * does not exist. Identifiers carrying the rejected vocabulary would have been
+ * the doctrine contradicted in its own implementation.
+ *
+ * What the caller prints is `authority_effect: disabled-shadow-mode` — a
+ * DISABLED effect, not a provisional permission. No grade authorizes anything.
+ */
+export function isLowEvidenceAccepted(fm: AdrFrontmatter): boolean {
+    if ((fm.scalars.status ?? '') !== 'accepted') return false;
+    if (authorityBasisOf(fm) === 'owner_intent') return false;
+    const evidence = evidenceOf(fm);
+    return evidence?.strength === 'E0' || evidence?.strength === 'E1';
+}
+
+// ---------------------------------------------------------------------------
+// Index cells. The two nested axes rendered as two flat table cells, in ONE
+// place, because two generated tables print them (`adr/regenerate_index.ts`
+// and `audit_adr_coverage.render_area_readme`) and both are byte-compared by a
+// `--check` gate — a second copy of the em-dash-on-absent convention would be
+// two gates disagreeing about one record.
+// ---------------------------------------------------------------------------
+
+/** The placeholder both generated tables already use for an absent scalar. */
+const CELL_ABSENT = '—';
+
+/**
+ * Reserved row keys the index generators spread over their frontmatter scalars.
+ *
+ * Named apart from the frontmatter keys they derive from (`provenance`,
+ * `evidence`), which `readAdrFrontmatterScalars` also emits as folded strings —
+ * a folded `kind: agentic decision_makers: [...]` is not a table cell, and
+ * colliding with those keys would put it in one.
+ */
+export interface AdrAxisCells {
+    provenance_kind: string;
+    evidence_grade: string;
+}
+
+/**
+ * `provenance.kind` and `evidence.strength` as table cells.
+ *
+ * `discovery` rides in the evidence cell rather than in a third column: a bare
+ * `E0` collapses the five states `adr-layout § evidence.discovery` separates,
+ * so an index that printed the grade alone would re-create exactly the
+ * conflation the axis exists to undo.
+ *
+ * Most of the corpus carries neither axis and is not expected to — the backfill
+ * is deliberately out of this roadmap — so `—` is the common answer and means
+ * "not assessed", never "assessed as weak".
+ */
+export function readAdrAxisCells(text: string): AdrAxisCells {
+    const fm = readAdrFrontmatter(text);
+    if (fm === null) return { provenance_kind: CELL_ABSENT, evidence_grade: CELL_ABSENT };
+    const provenance = provenanceOf(fm);
+    const evidence = evidenceOf(fm);
+    const strength = evidence?.strength ?? null;
+    const discovery = evidence?.discovery ?? null;
+    return {
+        provenance_kind: provenance?.kind ?? CELL_ABSENT,
+        evidence_grade:
+            strength === null
+                ? CELL_ABSENT
+                : discovery === null
+                  ? strength
+                  : `${strength} (${discovery})`,
+    };
+}

package/src/scripts/_lib/base_tree.ts

@@ -0,0 +1,175 @@
+/**
+ * Materialise one subtree of a git ref into a scratch directory, so a gate can
+ * MEASURE the base side with the same function it measures HEAD with.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A ratchet needs a "before" number the change under review cannot rewrite. The
+ * cheapest way to get one is to commit it — and that is what
+ * `src/config/estate-count-budget.json` did until ADR-243. A committed number is
+ * also a file every branch edits, which made it the most-conflicted non-generated
+ * path in this repository: 7 of 7 `CONFLICTING` open PRs on 2026-08-21, and 39 of
+ * 43 non-merge commits in a 60-day window moving it.
+ *
+ * The number does not have to be stored. Where the metric is a function of the
+ * tree, the base ref's own tree IS the "before" side — it is committed, and the
+ * change under review cannot rewrite it either. What is missing is a way to run
+ * a filesystem parser over a ref without checking it out.
+ *
+ * WHY NOT `git archive`
+ * ---------------------
+ * Measured, not assumed: `git archive origin/main agents/roadmaps | tar -x`
+ * produces an EMPTY archive in this repository, because `.gitattributes` carries
+ * `/agents export-ignore` (line 15) and `git archive` honours it. That is correct
+ * for the npm tarball it was written for and fatal here, and it fails silently —
+ * an empty extraction reads as "the estate measured zero", which is the shape of
+ * a floor of 0 that passes everything.
+ *
+ * `git ls-tree` + `git cat-file --batch` reads the object store directly and
+ * ignores export-ignore entirely. Cost, measured on 703 files: 0.22 s, two
+ * spawns total.
+ *
+ * WHY NOT `git worktree add`
+ * --------------------------
+ * It checks out the whole tree — 9177 files here — for a subtree of 703, and it
+ * mutates `.git/worktrees`, so a crashed gate leaves administrative state behind.
+ *
+ * THE EMPTY CASE IS AN ERROR, NEVER A MEASUREMENT
+ * -----------------------------------------------
+ * `materialiseSubtree` returns the file count and callers MUST treat 0 as "the
+ * base side could not be established", never as a measurement. An absent subtree,
+ * a typo in the path, a ref that predates the directory and an export-ignore
+ * silently eating the content are indistinguishable from each other and all
+ * produce zero — and for a shrink-only gate, a floor of zero is a green light for
+ * unbounded growth. This is stated here because the caller cannot see which of
+ * those happened either, and the safe reading of all four is the same.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** Ceiling on the blob stream. The roadmap corpus is ~2 MB; this is headroom. */
+const BATCH_MAX_BUFFER = 256 * 1024 * 1024;
+
+export interface MaterialisedTree {
+    /** Absolute path to a directory that now holds `<subtree>/...` from `ref`. */
+    root: string;
+    /** How many blobs were written. `0` means the base side is UNAVAILABLE. */
+    files: number;
+    /** Set when the read failed outright; `files` is then 0. */
+    error: string | null;
+}
+
+/** One entry of `git ls-tree -r -z`: `<mode> SP <type> SP <sha> TAB <path>`. */
+interface TreeEntry {
+    sha: string;
+    rel: string;
+}
+
+/**
+ * Parse `git ls-tree -r -z` output.
+ *
+ * The `-z` form is used rather than `--format`, which needs git ≥ 2.36: this runs
+ * on contributor machines and on runners, and a gate that fails on an older git
+ * is a gate that gets turned off.
+ */
+function parseLsTree(stdout: string): TreeEntry[] {
+    const out: TreeEntry[] = [];
+    for (const record of stdout.split('\0')) {
+        if (record === '') continue;
+        const tab = record.indexOf('\t');
+        if (tab === -1) continue;
+        const meta = record.slice(0, tab).split(' ');
+        const sha = meta[2];
+        const type = meta[1];
+        const rel = record.slice(tab + 1);
+        // Blobs only. A submodule entry is a `commit` and has no content here;
+        // writing its sha as a file would be a silent corruption of the measured
+        // tree rather than a missing file the caller could notice.
+        if (type !== 'blob' || sha === undefined || sha === '' || rel === '') continue;
+        out.push({ sha, rel });
+    }
+    return out;
+}
+
+/**
+ * Walk a `git cat-file --batch` stream, invoking `sink` per object.
+ *
+ * Wire format per object: `<sha> SP <type> SP <size> LF`, then exactly `size`
+ * bytes, then one LF. Sizes are read from the header rather than inferred from
+ * the next header, so a blob containing a line that looks like a header cannot
+ * desynchronise the parse — the failure mode that makes a line-oriented reading
+ * of this stream wrong.
+ */
+function walkBatch(buf: Buffer, sink: (sha: string, body: Buffer) => void): void {
+    let pos = 0;
+    while (pos < buf.length) {
+        const nl = buf.indexOf('\n', pos);
+        if (nl === -1) return;
+        const header = buf.subarray(pos, nl).toString('utf-8');
+        const parts = header.split(' ');
+        if (parts.length < 3) return; // `<sha> missing` — a bad ref; stop cleanly.
+        const size = Number.parseInt(parts[2] ?? '', 10);
+        if (!Number.isFinite(size) || size < 0) return;
+        const start = nl + 1;
+        sink(parts[0] ?? '', buf.subarray(start, start + size));
+        pos = start + size + 1;
+    }
+}
+
+/**
+ * Write `<subtree>` as it exists at `ref` into a fresh temp directory.
+ *
+ * The returned `root` is the caller's to remove — callers hold it in a `finally`.
+ * `subtree` is a repo-relative POSIX path (`agents/roadmaps`), because that is
+ * what git pathspecs take; a `path.sep`-joined value works on POSIX and silently
+ * matches nothing on Windows, so callers pass the POSIX form explicitly.
+ */
+export function materialiseSubtree(repoRoot: string, ref: string, subtree: string): MaterialisedTree {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'base-tree-'));
+    const list = spawnSync('git', ['ls-tree', '-r', '-z', ref, '--', subtree], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        maxBuffer: BATCH_MAX_BUFFER,
+    });
+    if (list.status !== 0) {
+        return { root, files: 0, error: `git ls-tree ${ref} -- ${subtree} failed: ${(list.stderr ?? '').trim()}` };
+    }
+    const entries = parseLsTree(list.stdout ?? '');
+    if (entries.length === 0) {
+        return { root, files: 0, error: `${subtree} holds no blobs at ${ref}` };
+    }
+
+    const batch = spawnSync('git', ['cat-file', '--batch'], {
+        cwd: repoRoot,
+        input: `${entries.map((e) => e.sha).join('\n')}\n`,
+        maxBuffer: BATCH_MAX_BUFFER,
+    });
+    if (batch.status !== 0 || batch.stdout === null) {
+        return { root, files: 0, error: `git cat-file --batch failed: ${String(batch.stderr ?? '').trim()}` };
+    }
+
+    // One sha may appear under several paths (identical file content), so the
+    // stream is keyed by sha and every path carrying that sha is written. Keying
+    // by position would break on exactly that case, and it is not hypothetical:
+    // roadmap stubs share boilerplate.
+    const bySha = new Map<string, Buffer>();
+    walkBatch(batch.stdout, (sha, body) => {
+        if (!bySha.has(sha)) bySha.set(sha, body);
+    });
+
+    let files = 0;
+    for (const entry of entries) {
+        const body = bySha.get(entry.sha);
+        if (body === undefined) continue;
+        const dest = path.join(root, ...entry.rel.split('/'));
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, body);
+        files += 1;
+    }
+    if (files !== entries.length) {
+        return { root, files: 0, error: `wrote ${String(files)} of ${String(entries.length)} blobs from ${ref}` };
+    }
+    return { root, files, error: null };
+}