@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/_lib/activation_payload.ts

@@ -0,0 +1,247 @@
+/**
+ * The runtime activation payload — what a trigger match charges per fire.
+ *
+ * The third of the three numbers `road-to-the-delivery-flip-that-tells-the-truth`
+ * Phase 3 separates. The other two already have names and a record: ADR-270
+ * calls them `source_corpus` (what the source tree could deliver) and
+ * `host_payload` (what one host actually receives at rest), and requires them to
+ * be structurally separate fields because "until the two are named apart, every
+ * ceiling discussion risks comparing unlike quantities". After a per-host
+ * projection flip a third quantity diverges from both: the bytes a delivery
+ * concern injects when a rule's trigger fires. A standing reduction published
+ * without it is a saving published without its cost.
+ *
+ * MEASURED THROUGH THE CONCERN'S OWN SELECTION, never a second model of it.
+ * `matchTierRules` + `selectForInjection` are the functions the runtime concern
+ * calls; an offline figure computed by a different matcher would price a set the
+ * concern does not deliver. That is the same single-definition rule
+ * `_lib/rule_injection.ts` was written for, applied one layer out.
+ *
+ * THE CAP IS A PARAMETER, not an import. The value lives on the concern
+ * (`hooks/rule_inject_hook.ts::CAP_BYTES`) and every caller passes it, so this
+ * module stays free of the hook's import closure and can be read from a gate, a
+ * report, or a bundled path without dragging a hook into it.
+ *
+ * Moved here from `report_standing_payload_by_host.ts`, which had the only
+ * implementation and is still its largest caller — same move, and for the same
+ * reason, as `censusRuleDir` into `_lib/carrier_divergence.ts`: a second reader
+ * needed it and a second copy is how two numbers start disagreeing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { loadRouter, matchTierRules, selectForInjection } from './rule_injection.js';
+
+/** The frozen corpus every fire figure in this module is sampled from. */
+export const ROUTING_MATRIX_REL = path.join('tests', 'eval', 'routing-matrix');
+
+/** One positive prompt of the frozen corpus, with the open files it declares. */
+export interface CorpusPrompt {
+    prompt: string;
+    openFiles: string[] | null;
+}
+
+/**
+ * Every YAML shape inside `positives:` this hand parser cannot read.
+ *
+ * `readCorpusPositives` accepts only `- prompt: "…"` with a double-quoted
+ * same-line scalar and an inline `open_files: [...]`. Any other legal shape —
+ * single quotes, an unquoted scalar, a folded block, a block sequence for
+ * `open_files` — is SILENTLY SKIPPED, which drops fires out of the distribution
+ * a budget row is derived from. A measurement that governs a budget must fail
+ * loudly on a shape it cannot read rather than under-count, so callers refuse on
+ * a non-empty result here.
+ *
+ * Reported as a shape problem rather than fixed by widening the parser: this
+ * module must not grow a second YAML implementation, and the corpus is frozen,
+ * so the honest answer to an unreadable shape is to say which file carries it.
+ */
+export function corpusShapeProblems(root: string): string[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const problems: string[] = [];
+    if (!fs.existsSync(dir)) return problems;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let lineNo = 0;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            lineNo += 1;
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            if (/^\s*-\s*prompt:/u.test(raw) && !/^\s*-\s*prompt:\s*"(.*)"\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a \`- prompt:\` this parser cannot read — only a ` +
+                        `double-quoted same-line scalar is accepted: ${JSON.stringify(raw.trim())}`,
+                );
+                continue;
+            }
+            if (/^\s*-\s*/u.test(raw) && !/^\s*-\s*(prompt|command|open_files):/u.test(raw)
+                && raw.trim() !== '-' && raw.trim() !== '') {
+                // A bare sequence item under `positives:` is a shape with no
+                // `prompt:` key on its first line — folded or nested.
+                if (!/^\s{4,}/u.test(raw)) {
+                    problems.push(
+                        `${f}:${String(lineNo)}: a positives entry whose first line carries no ` +
+                            `\`prompt:\` key: ${JSON.stringify(raw.trim())}`,
+                    );
+                }
+            }
+            if (/^\s*open_files:\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a BLOCK-sequence \`open_files:\` — only the inline ` +
+                        '`[...]` form is read, so this entry\'s files would be dropped',
+                );
+            }
+        }
+    }
+    return problems;
+}
+
+/** Every positive prompt in the frozen routing-matrix corpus. Near-misses are not fires. */
+export function readCorpusPositives(root: string): CorpusPrompt[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const out: CorpusPrompt[] = [];
+    if (!fs.existsSync(dir)) return out;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let cur: CorpusPrompt | null = null;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            const p = /^\s*-\s*prompt:\s*"(.*)"\s*$/u.exec(raw);
+            if (p !== null) {
+                cur = { prompt: p[1] as string, openFiles: null };
+                out.push(cur);
+                continue;
+            }
+            const of = /^\s*open_files:\s*\[(.*)\]\s*$/u.exec(raw);
+            if (of !== null && cur !== null) {
+                cur.openFiles = (of[1] as string)
+                    .split(',')
+                    .map((x) => x.trim().replace(/^["']|["']$/gu, ''))
+                    .filter((x) => x !== '');
+            }
+        }
+    }
+    return out;
+}
+
+/** Nearest-rank percentile over an unsorted sample. Empty sample → 0. */
+export function percentile(xs: readonly number[], q: number): number {
+    if (xs.length === 0) return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor(q * (s.length - 1)))] as number;
+}
+
+export interface SlotFireSizes {
+    readonly slot: string;
+    readonly fires: number;
+    readonly p50: number;
+    readonly p90: number;
+    readonly max: number;
+}
+
+/**
+ * Gate-open per-fire emission sizes for the delivery concern, per slot.
+ *
+ * `pre_compact` is 0 by construction rather than by measurement: that branch of
+ * `rule_inject_hook` clears the seen-set and returns allow without writing to
+ * stdout, so there is no emission to sample.
+ */
+export function slotFireSizes(root: string, capBytes: number): SlotFireSizes[] {
+    const router = loadRouter(root);
+    const prompts = readCorpusPositives(root);
+    const sample = (mode: 'prompt' | 'file'): number[] => {
+        const out: number[] = [];
+        for (const r of prompts) {
+            if (mode === 'file' && (r.openFiles === null || r.openFiles.length === 0)) continue;
+            const matches =
+                mode === 'prompt'
+                    ? matchTierRules(router, r.prompt, null, null)
+                    : matchTierRules(router, '', r.openFiles, null);
+            if (matches.length === 0) continue;
+            const sel = selectForInjection(root, matches, capBytes);
+            if (sel.selected.length > 0) out.push(sel.bytes);
+        }
+        return out;
+    };
+    const row = (slot: string, xs: number[]): SlotFireSizes => ({
+        slot,
+        fires: xs.length,
+        p50: percentile(xs, 0.5),
+        p90: percentile(xs, 0.9),
+        max: xs.length === 0 ? 0 : Math.max(...xs),
+    });
+    return [
+        row('user_prompt_submit', sample('prompt')),
+        row('pre_tool_use', sample('file')),
+        row('pre_compact', []),
+    ];
+}
+
+/** The third labelled number, or the reason it could not be taken on this tree. */
+export interface ActivationPayload {
+    /** Always the literal `activation-payload` — the label a reader and a caller key on. */
+    readonly scope: 'activation-payload';
+    /** `false` when the corpus or the router is absent; every figure is then 0. */
+    readonly measured: boolean;
+    /** Why it is unmeasured, or `null`. Never an estimate in place of a number. */
+    readonly unmeasured_reason: string | null;
+    /** The cap the sampled selection was taken at — the concern's `CAP_BYTES`. */
+    readonly cap_bytes: number;
+    readonly corpus: string;
+    readonly slots: readonly SlotFireSizes[];
+    readonly basis: string;
+}
+
+/**
+ * The runtime activation payload, or an honestly unmeasured reading.
+ *
+ * Never throws and never estimates: a missing corpus or router yields
+ * `measured: false` with the reason named, because a fabricated distribution
+ * published beside a standing saving is the exact defect this number exists to
+ * prevent.
+ */
+export function measureActivationPayload(root: string, capBytes: number): ActivationPayload {
+    const basis =
+        'Gate-open per-fire emission of the `rule-inject` concern over the frozen ' +
+        '`tests/eval/routing-matrix` positives, measured through the same ' +
+        '`matchTierRules` + `selectForInjection` the runtime concern calls, at the ' +
+        'concern\'s own CAP_BYTES. Bytes per fire, never tokens — the unit ' +
+        '`hook-token-budget.json` enforces.';
+    const empty = (reason: string): ActivationPayload => ({
+        scope: 'activation-payload',
+        measured: false,
+        unmeasured_reason: reason,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots: [],
+        basis,
+    });
+    if (!fs.existsSync(path.join(root, ROUTING_MATRIX_REL))) {
+        return empty(`the frozen corpus ${ROUTING_MATRIX_REL} is absent under ${root}`);
+    }
+    const shape = corpusShapeProblems(root);
+    if (shape.length > 0) {
+        return empty(
+            `${String(shape.length)} corpus entry/entries are in a shape the reader cannot parse, ` +
+                `so the distribution would be under-counted — first: ${shape[0] as string}`,
+        );
+    }
+    let slots: SlotFireSizes[];
+    try {
+        slots = slotFireSizes(root, capBytes);
+    } catch (err) {
+        return empty(`the fire sample could not be taken: ${(err as Error).message}`);
+    }
+    return {
+        scope: 'activation-payload',
+        measured: true,
+        unmeasured_reason: null,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots,
+        basis,
+    };
+}

package/src/scripts/_lib/agent_settings.ts

@@ -53,6 +53,7 @@ import { fileURLToPath } from 'node:url';
 
 import * as user_global_paths from './user_global_paths.js';
 import { carveOutKeys } from '../../shared/settingsCarveOut.js';
+import { applyRenamedKeys } from './settings_renamed_keys.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -956,9 +957,9 @@ export function load_agent_settings(
     // precedence here is the inverse of the server family's, so the order of
     // these three statements is the whole contract.
     const merged: SettingsDict = template_defaults(template_path ?? undefined);
-    _deep_merge(merged, user_global_filtered);
+    _deep_merge(merged, applyRenamedKeys(user_global_filtered));
     for (const p of cascade) {
-        const layer = _read_yaml(p) ?? {};
+        const layer = applyRenamedKeys(_read_yaml(p) ?? {});
         if (Object.keys(layer).length > 0) {
             _deep_merge(merged, layer);
         }
@@ -967,6 +968,7 @@ export function load_agent_settings(
     return merged;
 }
 
+
 /**
  * Settings keys this package has DELETED. A leftover value from an older
  * install is ignored — never applied by any reader — and surfaced with ONE

package/src/scripts/_lib/authority_path.ts

@@ -0,0 +1,102 @@
+/**
+ * The strictest path, reserved for authority —
+ * `road-to-adversarial-verification-and-long-runs` 11.1.
+ *
+ * An authority-expanding change takes four independent passes — an independent
+ * TEST author, an independent GOVERNANCE reviewer, a COUNCIL pass, and a
+ * PROVIDER-DIVERSE reviewer — plus the ratification artefact. Until the artefact
+ * carries `verdict: ratified`, the new authority is **inert**.
+ *
+ * ```
+ * NEW AUTHORITY IS INERT UNTIL RATIFIED. AN AGENT MAY AUTHOR THE CHANGE
+ * AND MAY NEVER RATIFY ITS OWN INCREASE IN POWER (ADR-268 § 4).
+ * FOUR PASSES, ALL FOUR, AND THEY MAY NOT BE THE SAME REVIEWER TWICE.
+ * ```
+ *
+ * **Inert-until-ratified is the property that makes the rest safe.** Without it
+ * the four passes are a process an author could complete and then merge; with it
+ * the change can land, be read, and still do nothing — so the ratification is a
+ * separate act on a separate turn by a party that is not the author.
+ *
+ * Pure.
+ */
+
+/** The four passes. All four, and the list is closed. */
+export const REQUIRED_PASSES = [
+    'independent-test-author',
+    'independent-governance-reviewer',
+    'council',
+    'provider-diverse-reviewer',
+] as const;
+export type Pass = (typeof REQUIRED_PASSES)[number];
+
+export interface PassRecord {
+    readonly pass: Pass;
+    /** Who performed it. Two passes by the same identity is not two passes. */
+    readonly by: string;
+    /** The provider, so provider-diversity is checkable rather than asserted. */
+    readonly provider: string;
+}
+
+export interface RatificationArtefact {
+    /** Anything other than `ratified` leaves the authority inert. */
+    readonly verdict: string;
+    readonly passes: readonly PassRecord[];
+    /** The author of the change under ratification. */
+    readonly author: string;
+}
+
+export type AuthorityState = 'inert' | 'active';
+
+export interface AuthorityVerdict {
+    readonly state: AuthorityState;
+    readonly blockers: readonly string[];
+}
+
+/**
+ * Is the new authority active yet?
+ *
+ * Returns EVERY blocker rather than the first: the artefact is a checklist a
+ * human completes, and handing them one item at a time turns four passes into
+ * four round trips.
+ */
+export function authorityState(a: RatificationArtefact | null): AuthorityVerdict {
+    if (a === null) {
+        return { state: 'inert', blockers: ['no ratification artefact exists'] };
+    }
+    const blockers: string[] = [];
+
+    for (const required of REQUIRED_PASSES) {
+        if (!a.passes.some((p) => p.pass === required)) {
+            blockers.push(`missing pass: ${required}`);
+        }
+    }
+
+    // The author may perform NONE of the four. This is the ADR-268 § 4 clause
+    // and the one a process can satisfy on paper while violating in substance.
+    for (const p of a.passes) {
+        if (p.by === a.author) {
+            blockers.push(`${p.pass} was performed by the author (${p.by}) — an agent may not ratify its own increase in power`);
+        }
+    }
+
+    // Provider diversity is a property of the SET, so it is checked over the set
+    // rather than trusted from the pass that carries the name.
+    const providers = new Set(a.passes.map((p) => p.provider));
+    if (a.passes.length > 1 && providers.size < 2) {
+        blockers.push(
+            `every pass ran on one provider (${[...providers].join(', ')}) — provider-diverse means at least two`,
+        );
+    }
+
+    if (a.verdict !== 'ratified') {
+        blockers.push(`verdict is "${a.verdict}", not "ratified"`);
+    }
+
+    return { state: blockers.length === 0 ? 'active' : 'inert', blockers };
+}
+
+/** `true` only for an artefact that clears everything. */
+export function isRatified(a: RatificationArtefact | null): boolean {
+    return authorityState(a).state === 'active';
+}

package/src/scripts/_lib/base_ref_payload.ts

@@ -0,0 +1,315 @@
+/**
+ * Read a prefix-stable surface set out of a git ref, into a scratch tree.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `road-to-delivery-for-every-host` 4.4 replaces a STORED standing-payload
+ * ceiling with a MEASURED one: `max(design_ceiling, payload_at_base_ref)`. An
+ * AI council (2/2, 2026-09-10) converged on that formula and on the reason — a
+ * stored ceiling stays where it was put until a human lowers it, so payload a
+ * merge removed can be added straight back into the space it freed. A measured
+ * ceiling captures every merged reduction automatically.
+ *
+ * To measure the base ref, the base tree has to exist somewhere. This module is
+ * that step and nothing else: it materialises the declared prefix-stable roots
+ * at a ref and hands back a directory. What to measure, and what to do with the
+ * number, belong to the caller.
+ *
+ * WHY NOT `git archive`, WHICH IS THE OBVIOUS TOOL
+ * ------------------------------------------------
+ * Because it silently drops declared surfaces. `git archive` honours
+ * `export-ignore`, and `.gitattributes` in this repository marks `/CLAUDE.md`
+ * export-ignore so release tarballs stay clean. `CLAUDE.md` is ALSO a declared
+ * prefix-stable surface worth 746 tok. Measured while building this module:
+ * `git archive HEAD -- CLAUDE.md | tar -t` emits **zero entries and exits 0**,
+ * so an archive-based base reading came back at 137,667 against a direct
+ * reading of 138,413 — 746 tok light, on a tree nobody had changed. A light
+ * base reading is a TIGHT ceiling, so every pull request would have reddened by
+ * 746 tokens it did not add.
+ *
+ * That is a packaging concern leaking into a measurement, and the two must not
+ * share a switch. `git ls-tree` + `git cat-file` read the object graph directly
+ * and have no notion of `export-ignore`, so the surface set measured here is
+ * the surface set the registry declares — which is the only definition this
+ * gate may use.
+ *
+ * SYMLINKED SURFACES ARE CLOSED OVER
+ * -----------------------------------
+ * `CLAUDE.md` is a git symlink (mode 120000) to `AGENTS.md`, which is not
+ * itself a declared surface. Materialising only the declared roots would leave
+ * a dangling link, which the census reads as an absent file — the same silent
+ * 746-token shortfall by a second route. Link targets are resolved at the git
+ * layer (a 120000 blob's content IS its target) and materialised alongside, to
+ * a fixpoint.
+ *
+ * FAILURE IS A VALUE, NEVER AN EXCEPTION AND NEVER A ZERO
+ * -------------------------------------------------------
+ * Every failure path returns `tree: null` with a stated reason. A census over a
+ * tree that could not be built returns a small number rather than an error, and
+ * a small base reading is a tight ceiling — the direction that reds honest
+ * work. The caller decides whether an unreadable base skips or refuses; this
+ * module refuses to guess on its behalf.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { prefixStableRoots } from './prefix_stable_surfaces.js';
+
+/** Injection seam: run git, capture stdout as a buffer plus the exit status. */
+export type GitBufferRunner = (
+    args: readonly string[],
+    cwd: string,
+    stdin?: string,
+) => { ok: boolean; stdout: Buffer };
+
+export const realGitBuffer: GitBufferRunner = (args, cwd, stdin) => {
+    const r = spawnSync('git', [...args], {
+        cwd,
+        maxBuffer: 512 * 1024 * 1024,
+        ...(stdin === undefined ? {} : { input: stdin }),
+    });
+    return { ok: r.status === 0, stdout: r.stdout ?? Buffer.alloc(0) };
+};
+
+interface TreeEntry {
+    mode: string;
+    sha: string;
+    /** Repo-relative path. */
+    rel: string;
+}
+
+export interface TreeAtRef {
+    /** Absolute path of the scratch tree, or `null` when it could not be built. */
+    tree: string | null;
+    /** Why it could not be built. `null` on success. */
+    note: string | null;
+    /** Repo-relative paths materialised. Empty on failure. */
+    files: string[];
+    /** Call when done. Safe to call on a failed reading. */
+    dispose: () => void;
+}
+
+/** How deep a chain of symlinked surfaces is followed before it is left alone. */
+const MAX_LINK_DEPTH = 4;
+
+function normalise(p: string): string {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/**
+ * Every blob under the given paths at `ref`.
+ *
+ * `-z` because a path may contain a character `git` would otherwise quote, and
+ * a quoted path silently names a file that does not exist.
+ */
+function listTree(git: GitBufferRunner, repoRoot: string, ref: string, paths: readonly string[]): TreeEntry[] | null {
+    const r = git(['ls-tree', '-r', '-z', '--full-tree', ref, '--', ...paths], repoRoot);
+    if (!r.ok) return null;
+    const out: TreeEntry[] = [];
+    for (const record of r.stdout.toString('utf-8').split('\0')) {
+        if (record === '') continue;
+        // `<mode> <type> <sha>\t<path>`
+        const tab = record.indexOf('\t');
+        if (tab === -1) continue;
+        const meta = record.slice(0, tab).split(' ');
+        const mode = meta[0];
+        const sha = meta[2];
+        if (mode === undefined || sha === undefined) continue;
+        out.push({ mode, sha, rel: normalise(record.slice(tab + 1)) });
+    }
+    return out;
+}
+
+/**
+ * Blob contents for a list of entries, in one `git cat-file --batch` call.
+ *
+ * One request line per ENTRY rather than per distinct sha: two files with
+ * identical content share a sha, and de-duplicating would misalign responses
+ * against entries for no measurable gain at this size (728 blobs).
+ */
+function readBlobs(git: GitBufferRunner, repoRoot: string, entries: readonly TreeEntry[]): Buffer[] | null {
+    if (entries.length === 0) return [];
+    const r = git(['cat-file', '--batch'], repoRoot, entries.map((e) => e.sha).join('\n') + '\n');
+    if (!r.ok) return null;
+    const buf = r.stdout;
+    const out: Buffer[] = [];
+    let at = 0;
+    for (let i = 0; i < entries.length; i += 1) {
+        const nl = buf.indexOf(0x0a, at);
+        if (nl === -1) return null;
+        // `<sha> <type> <size>` — a missing object answers `<name> missing`.
+        const header = buf.subarray(at, nl).toString('utf-8').split(' ');
+        const size = Number(header[2]);
+        if (!Number.isFinite(size)) return null;
+        const start = nl + 1;
+        out.push(buf.subarray(start, start + size));
+        // Each payload is followed by a single trailing newline.
+        at = start + size + 1;
+    }
+    return out;
+}
+
+/**
+ * Materialise the declared prefix-stable roots at `ref` into a scratch tree.
+ *
+ * `roots` defaults to the canonical registry rather than a literal list here:
+ * `prefix_stable_surfaces.ts` is the one place that boundary is declared, and a
+ * second copy is the drift shape this repository has already paid for.
+ */
+export function extractSurfacesAtRef(opts: {
+    repoRoot: string;
+    ref: string;
+    roots?: readonly string[];
+    git?: GitBufferRunner;
+}): TreeAtRef {
+    const git = opts.git ?? realGitBuffer;
+    const declared = (opts.roots ?? prefixStableRoots()).map(normalise).filter((r) => r !== '');
+    const noop = (): void => undefined;
+    if (declared.length === 0) {
+        return {
+            tree: null,
+            files: [],
+            note: 'no prefix-stable roots are declared, so there is nothing to read at the base ref',
+            dispose: noop,
+        };
+    }
+
+    const entries = listTree(git, opts.repoRoot, ref(opts.ref), declared);
+    if (entries === null) {
+        return {
+            tree: null,
+            files: [],
+            note: `'${opts.ref}' could not be read as a tree here — the ref is unreachable in this checkout`,
+            dispose: noop,
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            tree: null,
+            files: [],
+            note:
+                `no declared prefix-stable root exists at ${opts.ref} — ` +
+                'the surfaces moved, or the ref predates them',
+            dispose: noop,
+        };
+    }
+
+    // Close over symlinked surfaces: a dangling link measures as an absent file.
+    const seen = new Set(entries.map((e) => e.rel));
+    let frontier = entries.filter((e) => e.mode === '120000');
+    for (let depth = 0; depth < MAX_LINK_DEPTH && frontier.length > 0; depth += 1) {
+        const blobs = readBlobs(git, opts.repoRoot, frontier);
+        if (blobs === null) break;
+        const wanted: string[] = [];
+        frontier.forEach((e, i) => {
+            const target = (blobs[i] ?? Buffer.alloc(0)).toString('utf-8').trim();
+            if (target === '' || path.isAbsolute(target)) return;
+            const resolved = normalise(path.posix.join(path.posix.dirname(e.rel), target));
+            if (resolved.startsWith('..') || seen.has(resolved)) return;
+            wanted.push(resolved);
+        });
+        if (wanted.length === 0) break;
+        const extra = listTree(git, opts.repoRoot, ref(opts.ref), wanted);
+        if (extra === null || extra.length === 0) break;
+        const fresh = extra.filter((e) => !seen.has(e.rel));
+        for (const e of fresh) {
+            seen.add(e.rel);
+            entries.push(e);
+        }
+        frontier = fresh.filter((e) => e.mode === '120000');
+    }
+
+    const blobs = readBlobs(git, opts.repoRoot, entries);
+    if (blobs === null) {
+        return {
+            tree: null,
+            files: [],
+            note: `the blobs at ${opts.ref} could not be read back — git cat-file returned an unusable stream`,
+            dispose: noop,
+        };
+    }
+
+    let tmp: string;
+    try {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'payload-at-ref-'));
+    } catch (err) {
+        return {
+            tree: null,
+            files: [],
+            note: `a scratch directory could not be created: ${(err as Error).message}`,
+            dispose: noop,
+        };
+    }
+    const dispose = (): void => {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    };
+
+    try {
+        entries.forEach((e, i) => {
+            const dest = path.join(tmp, e.rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            const body = blobs[i] ?? Buffer.alloc(0);
+            if (e.mode === '120000') {
+                // Written as a real symlink so the census resolves it exactly as
+                // it does in the working tree — the target is materialised too.
+                fs.symlinkSync(body.toString('utf-8').trim(), dest);
+            } else {
+                fs.writeFileSync(dest, body);
+            }
+        });
+    } catch (err) {
+        dispose();
+        return {
+            tree: null,
+            files: [],
+            note: `writing the scratch tree for ${opts.ref} failed: ${(err as Error).message}`,
+            dispose: noop,
+        };
+    }
+
+    return { tree: tmp, files: entries.map((e) => e.rel), note: null, dispose };
+}
+
+/** `git ls-tree` needs a tree-ish; `<ref>` alone is one, but guard the empty case. */
+function ref(r: string): string {
+    return r.trim();
+}
+
+export interface PayloadAtRef {
+    ref: string;
+    /** Total tokens at the ref, or `null` when the tree could not be read. */
+    tokens: number | null;
+    note: string | null;
+}
+
+/**
+ * Measure the payload at `ref` with the caller's own census.
+ *
+ * The census is injected rather than imported so this module carries none of
+ * the gate's measurement code, and so a test can prove the materialisation
+ * independently of what is counted. The CALLER passing its own census is also
+ * what makes base and head the same measurement — the property that keeps a
+ * measured ceiling from drifting against the number it bounds.
+ */
+export function measurePayloadAtRef(opts: {
+    repoRoot: string;
+    ref: string;
+    measure: (treeRoot: string) => number;
+    git?: GitBufferRunner;
+}): PayloadAtRef {
+    if (opts.ref.trim() === '') {
+        return { ref: opts.ref, tokens: null, note: 'no base ref was resolved, so there is no tree to measure' };
+    }
+    const gitOpt = opts.git === undefined ? {} : { git: opts.git };
+    const t = extractSurfacesAtRef({ repoRoot: opts.repoRoot, ref: opts.ref, ...gitOpt });
+    if (t.tree === null) return { ref: opts.ref, tokens: null, note: t.note };
+    try {
+        return { ref: opts.ref, tokens: opts.measure(t.tree), note: null };
+    } catch (err) {
+        return { ref: opts.ref, tokens: null, note: `the census failed on the base tree: ${(err as Error).message}` };
+    } finally {
+        t.dispose();
+    }
+}