@event4u/agent-config 14.5.0 → 14.7.0

package/src/scripts/_lib/bench_ab_pinned_repo.ts

@@ -0,0 +1,162 @@
+/**
+ * Delta #9 — a corpus task may name an EXTERNAL repository pinned at a SHA.
+ *
+ * Until this module, every v2 task resolved to a self-contained fixture tree
+ * under `internal/bench/ab/`, so the harness could only measure trap tasks this
+ * repository authored. Phase 3 of `road-to-solution-minimalism` asks for the
+ * opposite: a public repo nobody chose for the purpose, so a size effect cannot
+ * be an artefact of fixtures written by the same hand as the rule.
+ *
+ * ## Why a SHA and not a ref
+ *
+ * `sha` is a full 40-hex commit id, and a branch or tag name is REFUSED rather
+ * than resolved. A ref moves, so a report pinned to one records which repository
+ * answered but not which tree — and F7 of that roadmap forbids exactly that
+ * class of unreproducible number. The refusal is loud (a throw) because the
+ * quiet alternative, resolving the ref at run time, produces a report that looks
+ * pinned and is not.
+ *
+ * ## Materialisation, and what needs the network
+ *
+ * `ensure_pinned_tree` warms a cache ONCE per SHA — `git init` + a `--depth 1`
+ * fetch of that exact commit + `git archive` into a `.git`-free tree. Every
+ * per-trial workspace is then a local copy of that tree, so a sweep touches the
+ * network once per pinned task and never on the metered path. `is_materialised`
+ * answers the warm/cold question without touching the network, which is what
+ * lets `--mode selftest` and the offline complexity re-scorer report an honest
+ * "not materialised locally" instead of either hanging or scoring zero.
+ *
+ * The tree is `.git`-free on purpose. `changed_files` already skips `.git`, so
+ * carrying it would not corrupt a diff — it would just copy a repository per
+ * trial, and a sweep is 5 arms x 3 seeds per task.
+ *
+ * ## What this module deliberately does NOT do
+ *
+ * No sub-directory scoping, no submodules, no LFS, no authenticated remotes:
+ * `repo` must be an `https://` URL. Each of those is a real feature and none is
+ * needed to pin one task to one commit, which is the whole of delta #9.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** A task's pinned-repo coordinates, already validated. */
+export interface PinnedSpec {
+    repo: string;
+    sha: string;
+}
+
+/** A malformed or contradictory pin. Never swallowed into a fixture fallback. */
+export class PinnedRepoError extends Error {}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const REPO_URL_RE = /^https:\/\/[A-Za-z0-9._~:/?#@!$&'()*+,;=%-]+$/;
+const CACHE_ROOT = path.join(os.tmpdir(), 'agent-config-bench-v2-repos');
+/** Written into a warm cache entry so a half-finished fetch never reads as warm. */
+const STAMP = '.pinned-repo.json';
+
+type Dict = Record<string, unknown>;
+
+/**
+ * The pin declared by `task`, or `null` when it is an ordinary fixture task.
+ *
+ * Throws rather than returning `null` on a task that is *trying* to be pinned
+ * and failing: a half-declared pin silently treated as a fixture task is how a
+ * sweep would run the wrong tree and report it as the right one.
+ */
+export function pinnedSpecFor(task: Dict): PinnedSpec | null {
+    const repoRaw = task['repo'];
+    const shaRaw = task['sha'];
+    const id = task['id'] === undefined ? '<unknown>' : String(task['id']);
+    if (repoRaw === undefined && shaRaw === undefined) return null;
+    if (repoRaw === undefined || shaRaw === undefined) {
+        throw new PinnedRepoError(`task ${id}: \`repo\` and \`sha\` must be declared together`);
+    }
+    if (task['fixture'] !== undefined) {
+        throw new PinnedRepoError(`task ${id}: a pinned task must not also declare \`fixture\``);
+    }
+    const repo = String(repoRaw);
+    const sha = String(shaRaw);
+    if (!REPO_URL_RE.test(repo)) {
+        throw new PinnedRepoError(`task ${id}: \`repo\` must be an https:// URL, got ${repo}`);
+    }
+    if (!SHA_RE.test(sha)) {
+        throw new PinnedRepoError(
+            `task ${id}: \`sha\` must be a full 40-hex commit id, got ${sha} — ` +
+                'a branch or tag is refused because it moves and the report would not be reproducible',
+        );
+    }
+    return { repo, sha };
+}
+
+/** Cache directory for one pin. Keyed by the SHA — a commit id is content. */
+export function pinned_tree_dir(spec: PinnedSpec): string {
+    return path.join(CACHE_ROOT, spec.sha, 'tree');
+}
+
+/** True when this pin's tree is already on disk and complete. */
+export function is_materialised(spec: PinnedSpec): boolean {
+    const stampPath = path.join(CACHE_ROOT, spec.sha, STAMP);
+    if (!fs.existsSync(stampPath) || !fs.existsSync(pinned_tree_dir(spec))) return false;
+    try {
+        const stamp = JSON.parse(fs.readFileSync(stampPath, 'utf-8')) as Dict;
+        return String(stamp['repo']) === spec.repo && String(stamp['sha']) === spec.sha;
+    } catch {
+        return false;
+    }
+}
+
+function _git(cwd: string, args: readonly string[]): void {
+    execFileSync('git', [...args], { cwd, stdio: 'pipe' });
+}
+
+/**
+ * Materialise the pinned tree, fetching over the network only on a cold cache.
+ *
+ * Returns the tree path. A failed fetch leaves NO stamp, so the next call
+ * retries from scratch rather than reading a partial checkout as warm.
+ */
+export function ensure_pinned_tree(spec: PinnedSpec): string {
+    const tree = pinned_tree_dir(spec);
+    if (is_materialised(spec)) return tree;
+    const base = path.join(CACHE_ROOT, spec.sha);
+    fs.rmSync(base, { recursive: true, force: true });
+    const gitdir = path.join(base, 'src');
+    fs.mkdirSync(gitdir, { recursive: true });
+    fs.mkdirSync(tree, { recursive: true });
+    _git(gitdir, ['init', '-q', '.']);
+    _git(gitdir, ['remote', 'add', 'origin', spec.repo]);
+    _git(gitdir, ['fetch', '-q', '--depth', '1', 'origin', spec.sha]);
+    const tar = execFileSync('git', ['archive', '--format=tar', 'FETCH_HEAD'], {
+        cwd: gitdir,
+        maxBuffer: 512 * 1024 * 1024,
+    });
+    const tarPath = path.join(base, 'tree.tar');
+    fs.writeFileSync(tarPath, tar);
+    execFileSync('tar', ['-x', '-f', tarPath, '-C', tree], { stdio: 'pipe' });
+    fs.rmSync(tarPath, { force: true });
+    fs.rmSync(gitdir, { recursive: true, force: true });
+    fs.writeFileSync(path.join(base, STAMP), JSON.stringify({ repo: spec.repo, sha: spec.sha }), 'utf-8');
+    return tree;
+}
+
+/**
+ * Absolute path to a task's pristine tree — fixture or pinned repo.
+ *
+ * `offlineOnly` is for readers that must not reach the network (the offline
+ * re-scorer, `--mode selftest`): a cold cache returns `null` there, which every
+ * caller reports as "not measured" rather than as a zero.
+ */
+export function pristine_tree_for(
+    task: Dict,
+    opts: { fixturesRoot: string; offlineOnly?: boolean },
+): string | null {
+    const spec = pinnedSpecFor(task);
+    if (spec !== null) {
+        if (opts.offlineOnly === true) return is_materialised(spec) ? pinned_tree_dir(spec) : null;
+        return ensure_pinned_tree(spec);
+    }
+    if (task['fixture'] === undefined) return null;
+    return path.join(opts.fixturesRoot, String(task['fixture']));
+}

package/src/scripts/_lib/bench_ab_workspace.ts

@@ -35,6 +35,8 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+
+import { pristine_tree_for } from './bench_ab_pinned_repo.js';
 import { fileURLToPath } from 'node:url';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -99,7 +101,14 @@ export function workspace_dir(task_id: string, arm: string, seed: number): strin
  * directory that is, never whether it is clean.
  */
 export function reset_fixture(task: Dict, arm: string, seed: number): [string, string] {
-    const fixture = path.join(FIXTURES_ROOT, String(task['fixture']));
+    // Delta #9: a task may pin an external repo at a SHA instead of naming an
+    // in-repo fixture. `pristine_tree_for` returns the tree either way, so the
+    // per-trial copy below — and every endpoint that diffs against the pristine
+    // tree — is unchanged by which kind of task this is.
+    const fixture = pristine_tree_for(task, { fixturesRoot: FIXTURES_ROOT });
+    if (fixture === null) {
+        throw new Error(`task ${String(task['id'])} declares neither a \`fixture\` nor a pinned \`repo\`/\`sha\``);
+    }
     const dest = workspace_dir(String(task['id']), arm, seed);
     if (fs.existsSync(dest)) {
         fs.rmSync(dest, { recursive: true, force: true });

package/src/scripts/_lib/envelope_grounding.ts

@@ -18,6 +18,7 @@ import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePathFor } from '../before_complete_hook.js';
 import { git_common_dir } from './git_common_dir.js';
 import { gitEnv } from './git_env.js';
 
@@ -114,10 +115,9 @@ export interface Grounding extends RepoAnchor {
     last_verify: string | null;
 }
 
-const VERIFY_STATE_REL = path.join('agents', 'runtime', 'state', 'verify-before-complete.json');
 
 /**
- * The last verification this workspace recorded, as one line.
+ * The last verification THIS SESSION recorded, as one line.
  *
  * **What this is not:** an exit code. The roadmap step asked for "last verify
  * exit", and nothing in the tree records one — `before_complete_hook` stores
@@ -125,10 +125,34 @@ const VERIFY_STATE_REL = path.join('agents', 'runtime', 'state', 'verify-before-
  * worse than emitting less, so the field carries the command and its
  * timestamp and says so, rather than implying a pass/fail the source never
  * held.
+ *
+ * **Why the session id is a required parameter, not an optional one.** This
+ * function resolved `agents/runtime/state/verify-before-complete.json` for its
+ * whole life and returned `null` every time: the producer never wrote that
+ * path — pre-split it wrote `agents/state/verify-before-complete.json`, and
+ * after the per-session split it writes
+ * `agents/state/verify-before-complete/<digest>.json`. The `runtime/` segment
+ * was never a directory this state used, so the reader was dead on arrival
+ * rather than made dead by the split.
+ *
+ * The producer's state is now per-session, so a reader without a session id
+ * cannot address it — and there is no defensible fallback. Reading "whatever
+ * file is newest in the directory" would attribute a NEIGHBOURING session's
+ * verification to this envelope, which is the exact cross-session read the
+ * split exists to stop, and it would do it on the field a successor session
+ * uses to decide whether work was verified. So an absent id yields `null`, and
+ * the parameter is required so no caller can reach the dead behaviour by
+ * omission.
+ *
+ * The path comes from the producer's own builder (`statePathFor`), never from
+ * a literal repeated here: a copied path constant is what went stale, and
+ * copying it again with the correct value would only reset the clock on the
+ * same failure.
  */
-export function readLastVerify(root: string): string | null {
+export function readLastVerify(root: string, session_id: string | null): string | null {
+    if (typeof session_id !== 'string' || session_id.trim() === '') return null;
     try {
-        const raw = fs.readFileSync(path.join(root, VERIFY_STATE_REL), 'utf-8');
+        const raw = fs.readFileSync(path.join(root, statePathFor(session_id)), 'utf-8');
         const state = JSON.parse(raw) as Record<string, unknown>;
         const lv = state['last_verification'];
         if (typeof lv !== 'object' || lv === null || Array.isArray(lv)) return null;
@@ -142,8 +166,14 @@ export function readLastVerify(root: string): string | null {
     }
 }
 
-/** Collect every scripted field. Never throws — an unreadable fact is `null`. */
-export function collectGrounding(root: string): Grounding {
+/**
+ * Collect every scripted field. Never throws — an unreadable fact is `null`.
+ *
+ * `session_id` is required and forwarded to `readLastVerify` — see the reason
+ * stated there. A caller with no id in hand passes `null` and gets a `null`
+ * `last_verify`, which is the honest answer rather than a neighbour's.
+ */
+export function collectGrounding(root: string, session_id: string | null): Grounding {
     const anchor = collectRepoAnchor(root);
     const porcelain = git(root, ['status', '--porcelain']);
     if (porcelain === null) {
@@ -151,7 +181,7 @@ export function collectGrounding(root: string): Grounding {
         // this the one field in the module that asserts something it never
         // read — and it would assert it exactly when every sibling field is
         // null, so `describeDrift` is silent and nothing challenges it.
-        return { ...anchor, uncommitted_paths: [], status_summary: null, last_verify: readLastVerify(root) };
+        return { ...anchor, uncommitted_paths: [], status_summary: null, last_verify: readLastVerify(root, session_id) };
     }
     const lines = porcelain.split('\n').filter((l) => l.trim().length > 0);
     const paths = lines
@@ -165,7 +195,7 @@ export function collectGrounding(root: string): Grounding {
             lines.length === 0
                 ? 'clean working tree'
                 : `${lines.length} uncommitted path(s)${lines.length > MAX_PATHS ? `, first ${MAX_PATHS} listed` : ''}`,
-        last_verify: readLastVerify(root),
+        last_verify: readLastVerify(root, session_id),
     };
 }
 

package/src/scripts/_lib/installed_lock.ts

@@ -44,6 +44,13 @@ export interface LockfileData {
   agent_config_version?: string;
   installed_at?: string;
   tools: string[];
+  /**
+   * Content fingerprint of the host artefact layers this install wrote
+   * (`hostLayerFingerprint.fingerprintLayers`). Absent on every lockfile
+   * written before the single-delivery partition, which is why the partition
+   * predicate treats absence as "not verified" and keeps the full projection.
+   */
+  host_layer_fingerprint?: string;
 }
 
 export const LOCKFILE_ENV = "AGENT_CONFIG_INSTALLED_LOCK";
@@ -65,6 +72,7 @@ const _VERSION_RE = /^\s*agent_config_version\s*:\s*"?([^"\s]+)"?\s*$/;
 const _SCHEMA_RE = /^\s*schema_version\s*:\s*(\d+)\s*$/;
 const _LAYOUT_RE = /^\s*install_layout_version\s*:\s*(\d+)\s*$/;
 const _INSTALLED_AT_RE = /^\s*installed_at\s*:\s*"?([^"\s]+)"?\s*$/;
+const _FINGERPRINT_RE = /^\s*host_layer_fingerprint\s*:\s*"?([0-9a-f]{64})"?\s*$/;
 const _TOOL_RE = /^\s*-\s*([A-Za-z0-9_\-.]+)\s*$/;
 
 /** Expand a leading `~` like Python's `Path.expanduser()`. */
@@ -158,6 +166,12 @@ export function read_lockfile(path?: string | null): LockfileData | null {
       in_tools = false;
       continue;
     }
+    const fp_m = _FINGERPRINT_RE.exec(raw_line);
+    if (fp_m) {
+      data.host_layer_fingerprint = fp_m[1]!;
+      in_tools = false;
+      continue;
+    }
     if (raw_line.trim().startsWith("tools:")) {
       in_tools = true;
       continue;
@@ -186,14 +200,24 @@ function splitlines(text: string): string[] {
   return parts;
 }
 
-function _render(version: string, tools: string[], installed_at: string): string {
+function _render(
+  version: string,
+  tools: string[],
+  installed_at: string,
+  fingerprint?: string | null,
+): string {
   const lines = [
     `schema_version: ${SCHEMA_VERSION}`,
     `install_layout_version: ${INSTALL_LAYOUT_VERSION}`,
     `agent_config_version: "${version}"`,
     `installed_at: "${installed_at}"`,
-    "tools:",
   ];
+  // Written BEFORE `tools:` so the sequence block stays last and the parser's
+  // in_tools state machine needs no extra exit condition.
+  if (fingerprint) {
+    lines.push(`host_layer_fingerprint: "${fingerprint}"`);
+  }
+  lines.push("tools:");
   for (const tool of tools) {
     lines.push(`  - ${tool}`);
   }
@@ -204,12 +228,26 @@ function _render(version: string, tools: string[], installed_at: string): string
 export function write_lockfile(
   version: string,
   tools: string[],
-  options: { path?: string | null; now?: Date | null } = {},
+  options: {
+    path?: string | null;
+    now?: Date | null;
+    /**
+     * Host-layer content fingerprint. Omit to write no fingerprint line at
+     * all — never write a placeholder: absence means "not verified" to the
+     * partition predicate, and a placeholder would mean "verified, wrongly".
+     */
+    host_layer_fingerprint?: string | null;
+  } = {},
 ): string {
   const target = options.path ?? lockfile_path();
   fs.mkdirSync(path.dirname(target), { recursive: true });
   const stamp = strftime_iso_z(options.now ?? new Date());
-  const rendered = _render(version, sorted_unique(tools), stamp);
+  const rendered = _render(
+    version,
+    sorted_unique(tools),
+    stamp,
+    options.host_layer_fingerprint ?? null,
+  );
   // Atomic write: tempfile in the same dir + rename. The same-dir constraint
   // keeps the rename atomic across all POSIX filesystems and Windows when the
   // file already exists.
@@ -316,7 +354,14 @@ export function migrate_layout(
   const version = existing.agent_config_version || current_package_version();
   const tools = [...(existing.tools ?? [])];
   const when = options.now ?? _parse_installed_at(existing.installed_at);
-  write_lockfile(version, tools, { path: target, now: when });
+  // Carry the fingerprint across the migration. Dropping it would silently
+  // demote a verified host layer to "not verified" and turn the partition off
+  // on the next build — a layout migration must not change delivery.
+  write_lockfile(version, tools, {
+    path: target,
+    now: when,
+    host_layer_fingerprint: existing.host_layer_fingerprint ?? null,
+  });
   return {
     from: from_v,
     to: INSTALL_LAYOUT_VERSION,

package/src/scripts/_lib/layer_overlap_notice.ts

@@ -0,0 +1,85 @@
+/**
+ * The overlap notice `task generate-tools` prints after writing the project layer.
+ *
+ * Extracted from `condense.ts` rather than left inline: it added exactly 60 lines
+ * there and `check_source_size_budget` is a **shrink-only** ratchet, so the legal
+ * repair is extraction and never a re-pinned baseline. It also belongs here on its
+ * own terms — the notice is about the RELATIONSHIP between two host layers, not
+ * about condensation.
+ *
+ * WHY THE NOTICE EXISTS. `generate-tools` writes ONE of the two layers Claude Code
+ * loads and was silent about the other existing, while the installer's overlap gate
+ * runs at install time and cannot see a layer written afterwards. So the overlap is
+ * created by whichever producer runs LAST, and neither said so. Measured 2026-08-19
+ * on a freshly regenerated maintainer projection: 110 rules delivered twice, plus
+ * 290 skills and 40 commands sharing a name across layers of different payload
+ * shape. Invariant: ADR-236. Full census:
+ * `agents/evidence/analysis/single-delivery-partition-census.md`.
+ *
+ * ADVISORY, NEVER FAILING. `generate-tools` is the normal build step. Failing it on
+ * a topology the operator may not be able to change today would make the build
+ * unusable rather than the duplication visible. The check that can refuse is
+ * `check_single_delivery --enforce`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Artefact types both host layers can carry.
+ *
+ * All four, matching `check_single_delivery` (R2 finding): this notice read three
+ * where the gate reads four, so a subagent duplicated across layers was invisible
+ * on one surface and reported on the other — two surfaces disagreeing about the
+ * same question is worse than one surface being silent.
+ */
+const TYPES = ['rules', 'skills', 'commands', 'agents'] as const;
+
+/**
+ * Count shared entry names per artefact type between the two layers.
+ *
+ * A type whose layers are not both readable is SKIPPED rather than reported as
+ * zero: one layer absent means nothing is doubled there, and that is the topology
+ * this notice wants, so a warning would be noise on the success case.
+ */
+export function overlapFindings(homeDir: string, projectRoot: string): string[] {
+    const findings: string[] = [];
+    for (const type of TYPES) {
+        let g: string[];
+        let p: string[];
+        try {
+            g = fs.readdirSync(path.join(homeDir, '.claude', type));
+            p = fs.readdirSync(path.join(projectRoot, '.claude', type));
+        } catch {
+            continue;
+        }
+        const gset = new Set(g);
+        const both = p.filter((n) => gset.has(n)).length;
+        if (both > 0) findings.push(`${type}=${both}`);
+    }
+    return findings;
+}
+
+/** Render the notice, or `null` when there is nothing to say. */
+export function overlapNotice(homeDir: string, projectRoot: string): string | null {
+    const findings = overlapFindings(homeDir, projectRoot);
+    if (findings.length === 0) return null;
+    return (
+        `  ⚠️  a global layer holds the same names (${findings.join(' ')}) — the host loads both` +
+        ' with no dedup, so these are delivered twice per session.' +
+        '\n      Detail: ./scripts-run src/scripts/check_single_delivery · invariant: ADR-236'
+    );
+}
+
+/**
+ * Print the notice through the caller's own writer.
+ *
+ * The writer is injected so this stays testable and so it uses `condense.ts`'s
+ * summary channel rather than reaching for `process.stdout` behind its back.
+ */
+export function warnLayerOverlap(projectRoot: string, write: (s: string) => void): void {
+    const home = process.env['HOME'];
+    if (home === undefined || home === '') return;
+    const notice = overlapNotice(home, projectRoot);
+    if (notice !== null) write(notice);
+}

package/src/scripts/_lib/md_section.ts

@@ -0,0 +1,129 @@
+/**
+ * Structural markdown section edits — anchored on a LINE, never on a substring.
+ *
+ * WHY THIS EXISTS. Measured 2026-08-20, and it was the single costliest error
+ * of that session. A script located a section with
+ * `text.index('## Acceptance criteria')` and sliced there. The first match was
+ * not the heading: it was a **quotation of that heading inside a step's prose**,
+ * one paragraph earlier. The slice cut mid-step, the document silently lost its
+ * risk register, and it took two calls to notice and two more to rebuild.
+ *
+ * Three properties made it expensive, and all three are generic:
+ *
+ *   1. the anchor was a substring, so content that *mentions* a heading is
+ *      indistinguishable from the heading;
+ *   2. the edit was destructive rather than checked — one match was assumed;
+ *   3. nothing verified the document's shape afterwards, so the loss was silent.
+ *
+ * This module closes all three. It refuses on zero matches and on more than
+ * one, because "take the first" is exactly the behaviour that failed. And
+ * `headings()` plus `assertShapePreserved()` make a dropped section loud.
+ */
+
+export class SectionError extends Error {}
+
+/** Every ATX heading in the document, in order, as `## Title` including hashes. */
+export function headings(text: string): string[] {
+    return text.split('\n').filter((l) => /^#{1,6}\s+\S/.test(l));
+}
+
+/** Line indices of a heading matched at LINE START and exactly. */
+function headingLines(lines: readonly string[], heading: string): number[] {
+    const want = heading.trim();
+    const out: number[] = [];
+    lines.forEach((l, i) => {
+        if (l.trim() === want) {
+            out.push(i);
+        }
+    });
+    return out;
+}
+
+/** The heading's own level, e.g. 2 for `## X`. */
+function levelOf(heading: string): number {
+    const m = /^(#{1,6})\s/.exec(heading.trim());
+    if (m === null) {
+        throw new SectionError(`not an ATX heading: ${JSON.stringify(heading)}`);
+    }
+    return (m[1] as string).length;
+}
+
+/**
+ * `[start, end)` line range of the section, from its heading up to the next
+ * heading of the same or a higher level (or EOF).
+ *
+ * Throws when the heading appears zero times or more than once — the caller
+ * decides what to do, and neither case may be silently resolved by taking the
+ * first hit.
+ */
+export function sectionRange(text: string, heading: string): [number, number] {
+    const lines = text.split('\n');
+    const hits = headingLines(lines, heading);
+    if (hits.length === 0) {
+        throw new SectionError(`heading not found at line start: ${JSON.stringify(heading)}`);
+    }
+    if (hits.length > 1) {
+        throw new SectionError(
+            `heading is ambiguous — ${String(hits.length)} occurrences at lines ` +
+                `${hits.map((h) => String(h + 1)).join(', ')}: ${JSON.stringify(heading)}`,
+        );
+    }
+    const start = hits[0] as number;
+    const level = levelOf(heading);
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i] as string;
+        const m = /^(#{1,6})\s+\S/.exec(l);
+        if (m !== null && (m[1] as string).length <= level) {
+            end = i;
+            break;
+        }
+    }
+    return [start, end];
+}
+
+/** The section's text, heading line included. */
+export function extractSection(text: string, heading: string): string {
+    const [s, e] = sectionRange(text, heading);
+    return text.split('\n').slice(s, e).join('\n');
+}
+
+/** Replace the section's body, heading line included, with `replacement`. */
+export function replaceSection(text: string, heading: string, replacement: string): string {
+    const lines = text.split('\n');
+    const [s, e] = sectionRange(text, heading);
+    return [...lines.slice(0, s), ...replacement.split('\n'), ...lines.slice(e)].join('\n');
+}
+
+/**
+ * Assert that an edit did not lose a section it was not meant to touch.
+ *
+ * `allowedRemoved` / `allowedAdded` name the headings the edit intends to
+ * change; anything else disappearing or appearing throws. This is the check
+ * that would have caught the measured failure at the moment it happened rather
+ * than two calls later.
+ */
+export function assertShapePreserved(
+    before: string,
+    after: string,
+    opts: { allowedRemoved?: readonly string[]; allowedAdded?: readonly string[] } = {},
+): void {
+    const norm = (h: string): string => h.trim();
+    const b = headings(before).map(norm);
+    const a = headings(after).map(norm);
+    const allowedRemoved = new Set((opts.allowedRemoved ?? []).map(norm));
+    const allowedAdded = new Set((opts.allowedAdded ?? []).map(norm));
+
+    const removed = b.filter((h) => !a.includes(h) && !allowedRemoved.has(h));
+    const added = a.filter((h) => !b.includes(h) && !allowedAdded.has(h));
+    if (removed.length > 0 || added.length > 0) {
+        const parts: string[] = [];
+        if (removed.length > 0) {
+            parts.push(`lost ${String(removed.length)}: ${removed.join(' · ')}`);
+        }
+        if (added.length > 0) {
+            parts.push(`gained ${String(added.length)}: ${added.join(' · ')}`);
+        }
+        throw new SectionError(`document shape changed unexpectedly — ${parts.join('; ')}`);
+    }
+}