@event4u/agent-config 9.21.0 → 9.23.0

package/src/scripts/_lib/bench_ab_activation.ts

@@ -0,0 +1,368 @@
+/**
+ * Measurement-integrity primitives for the bench:ab v2 paired sweep.
+ *
+ * Implements deltas #1–#4 of the S0.3 harness-feasibility spike
+ * (`agents/evidence/investigations/solution-minimalism-phase0-spikes.md`
+ * § "Deltas required before a paid run") — the four cheap ones the roadmap's
+ * Phase-3 halt note says "land before any spend".
+ *
+ * Why this exists at all: the sweep has ALREADY produced a full set of invalid
+ * nulls once. Clones lived inside the repo, so the `vanilla` arm inherited the
+ * package through project scope and every prior null was void
+ * (`bench_ab_v2_run.ts` § arm-isolation note). The fix at the time was a `/tmp`
+ * path constant with no runtime assertion behind it, and the only activation
+ * field on a trial record — `injected_chars` — is the `String.length` of a file
+ * the harness itself wrote. It proves nothing about the model, and it is `0` by
+ * construction for the `package` arm, which arrives through global settings.
+ * If the plugin were disabled or version-drifted mid-sweep, every treatment run
+ * would silently degrade to `vanilla` and the report would look identical.
+ *
+ * Everything here is pure and host-free so it can be unit-tested without a
+ * model call. The sweep wires it in `bench_ab_v2_run.ts`.
+ */
+
+/** Four-bucket usage split as reported by the Claude CLI JSON envelope. */
+export interface TokensBreakdown {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+}
+
+/** Per-1M-token rates for one pricing tier (mirrors `_lib/bench_cost.TierRates`). */
+export interface TierRates {
+    input: number;
+    output: number;
+    cache_write: number;
+    cache_read: number;
+}
+
+/**
+ * How an arm is supposed to reach the model.
+ *
+ * - `plugin` — the package rides global settings (`setting_sources: null`).
+ *   Invisible to `injected_chars`; only the prompt footprint can see it.
+ * - `text`   — an `--append-system-prompt-file` injection the harness wrote.
+ * - `none`   — the baseline: settings scoped away AND no text injection.
+ */
+export type ExpectedInjection = 'plugin' | 'text' | 'none';
+
+/**
+ * `unknown` is deliberately not a violation: an errored or budget-capped run
+ * carries a zeroed usage block, so its footprint says nothing. Attrition is
+ * reported separately (delta #5) rather than laundered into an integrity fail.
+ */
+export type ActivationVerdict = 'ok' | 'violation' | 'unknown';
+
+export interface Activation {
+    expected: ExpectedInjection;
+    prompt_tokens: number;
+    injected_chars: number;
+    verdict: ActivationVerdict;
+    reason: string;
+}
+
+export interface ActivationViolation {
+    task_id: string;
+    seed: number;
+    arm: string;
+    kind: 'text-injection-missing' | 'text-injection-unexpected' | 'collapsed-to-baseline' | 'model-mismatch';
+    detail: string;
+}
+
+export interface ActivationAudit {
+    checked: number;
+    skipped: number;
+    violations: ActivationViolation[];
+}
+
+/**
+ * Minimum prompt-footprint ratio a plugin-bearing arm must hold over the paired
+ * baseline run before the pair is believed.
+ *
+ * Calibrated DOWNWARD from the three stored sweeps in S0.3's cost sheet, whose
+ * observed treatment/vanilla total-token ratios were 4.68× (sonnet, `package`),
+ * 1.71× (haiku, `rules-kernel-dc`) and 6.79× (haiku, `package`). 1.2 sits below
+ * the smallest of those by a wide margin on purpose: this flags a COLLAPSE to
+ * baseline — a disabled or drifted plugin — never ordinary run-to-run variance.
+ * Raising it toward the observed values would start failing legitimate runs;
+ * lowering it toward 1.0 would stop catching the failure it exists for.
+ */
+export const ACTIVATION_MIN_LIFT_RATIO = 1.2;
+
+/**
+ * The footprint an injection actually moves: everything the model was fed.
+ *
+ * Output tokens are excluded — they measure how much the model wrote, which a
+ * bigger system prompt does not reliably change, so including them would blur
+ * the very signal this audit reads.
+ */
+export function prompt_tokens(b: TokensBreakdown | Record<string, never> | null | undefined): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return _int(t.input_tokens) + _int(t.cache_read_input_tokens) + _int(t.cache_creation_input_tokens);
+}
+
+/** Classify an arm spec into the injection channel it is supposed to use. */
+export function expected_injection(spec: { setting_sources: string | null; inject: string | null }): ExpectedInjection {
+    if (spec.inject) {
+        return 'text';
+    }
+    return spec.setting_sources === null ? 'plugin' : 'none';
+}
+
+/**
+ * Per-trial verdict — the direction that IS decidable from one run.
+ *
+ * A text injection is checked both ways: an arm that declares one must carry
+ * it, and an arm that declares none must not. The plugin direction needs the
+ * paired baseline and is handled by `audit_activation`.
+ */
+export function activation_verdict(args: {
+    expected: ExpectedInjection;
+    tokens_breakdown: TokensBreakdown | Record<string, never> | null | undefined;
+    injected_chars: number;
+    errored: boolean;
+}): Activation {
+    const pt = prompt_tokens(args.tokens_breakdown);
+    const base = { expected: args.expected, prompt_tokens: pt, injected_chars: args.injected_chars };
+    if (args.errored || pt === 0) {
+        return { ...base, verdict: 'unknown', reason: 'errored or zero usage — footprint unreadable' };
+    }
+    if (args.expected === 'text' && args.injected_chars <= 0) {
+        return { ...base, verdict: 'violation', reason: 'text arm carried no injection' };
+    }
+    if (args.expected !== 'text' && args.injected_chars > 0) {
+        return {
+            ...base,
+            verdict: 'violation',
+            reason: `${args.expected} arm carried a ${args.injected_chars}-char injection`,
+        };
+    }
+    return { ...base, verdict: 'ok', reason: 'expected channel present' };
+}
+
+/**
+ * Cross-arm audit over a finished (or partial) record set — the plugin
+ * direction plus every per-trial verdict already stamped on the records.
+ *
+ * A pair is only judged when BOTH sides are readable; unreadable pairs are
+ * counted as `skipped`, never silently passed.
+ */
+export function audit_activation(
+    records: readonly Record<string, unknown>[],
+    opts: { baseline_arm: string; lift_arms: readonly string[]; min_ratio?: number },
+): ActivationAudit {
+    const minRatio = opts.min_ratio ?? ACTIVATION_MIN_LIFT_RATIO;
+    const violations: ActivationViolation[] = [];
+    let checked = 0;
+    let skipped = 0;
+
+    for (const rec of records) {
+        const taskId = String(rec['id'] ?? '');
+        const arms = _dict(rec['arms']);
+
+        for (const [arm, runsRaw] of Object.entries(arms)) {
+            for (const run of _list(runsRaw)) {
+                const act = _dict(run['activation']);
+                if (act['verdict'] === 'violation') {
+                    const reason = String(act['reason'] ?? '');
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: reason.includes('no injection') ? 'text-injection-missing' : 'text-injection-unexpected',
+                        detail: reason,
+                    });
+                }
+                const mc = _dict(run['model_check']);
+                if ('ok' in mc && !_truthy(mc['ok'])) {
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: 'model-mismatch',
+                        detail: String(mc['reason'] ?? ''),
+                    });
+                }
+            }
+        }
+
+        const baseBySeed = new Map<number, number>();
+        for (const run of _list(arms[opts.baseline_arm])) {
+            const pt = _runPromptTokens(run);
+            if (!_truthy(run['errored']) && pt > 0) {
+                baseBySeed.set(_int(run['seed']), pt);
+            }
+        }
+
+        for (const arm of opts.lift_arms) {
+            for (const run of _list(arms[arm])) {
+                const seed = _int(run['seed']);
+                const basePt = baseBySeed.get(seed);
+                const armPt = _runPromptTokens(run);
+                if (_truthy(run['errored']) || basePt === undefined || armPt === 0) {
+                    skipped += 1;
+                    continue;
+                }
+                checked += 1;
+                if (armPt < basePt * minRatio) {
+                    violations.push({
+                        task_id: taskId,
+                        seed,
+                        arm,
+                        kind: 'collapsed-to-baseline',
+                        detail:
+                            `prompt footprint ${armPt} vs baseline ${basePt} ` +
+                            `(ratio ${(armPt / basePt).toFixed(2)} < ${minRatio}) — ` +
+                            'the treatment surface may not have reached the model',
+                    });
+                }
+            }
+        }
+    }
+
+    return { checked, skipped, violations };
+}
+
+// ── delta #3 — model-id verification ────────────────────────────────────────
+
+/**
+ * Aliases the Claude CLI resolves server-side to whatever is current.
+ *
+ * A stored report already contains the bare alias `"sonnet"`, which makes that
+ * report unreproducible: nothing in it records which model actually answered.
+ */
+export const BARE_MODEL_ALIASES: readonly string[] = ['default', 'haiku', 'opus', 'sonnet', 'sonnet[1m]'];
+
+/** True when `model` is an alias rather than a pinned, reproducible id. */
+export function is_bare_alias(model: string): boolean {
+    return BARE_MODEL_ALIASES.includes(model.trim().toLowerCase());
+}
+
+/** Drop a trailing `-YYYYMMDD` build stamp so `claude-x-1` == `claude-x-1-20250101`. */
+export function normalize_model_id(model: string): string {
+    return model.trim().toLowerCase().replace(/-\d{8}$/, '');
+}
+
+/**
+ * Compare the requested model against the ids the CLI actually billed.
+ *
+ * `models_seen` comes from the envelope's `modelUsage` keys — the only place
+ * the run states which model answered. An empty list is `ok`: some envelopes
+ * omit the block, and refusing there would fail runs for a reporting gap
+ * rather than a real mismatch.
+ */
+export function verify_model_id(requested: string, models_seen: readonly string[]): { ok: boolean; reason: string } {
+    if (is_bare_alias(requested)) {
+        return { ok: false, reason: `requested model "${requested}" is a bare alias — pin a full model id` };
+    }
+    if (models_seen.length === 0) {
+        return { ok: true, reason: 'envelope reported no model usage — nothing to contradict' };
+    }
+    const want = normalize_model_id(requested);
+    const seen = models_seen.map(normalize_model_id);
+    if (seen.every((s) => s === want)) {
+        return { ok: true, reason: `billed model matches ${requested}` };
+    }
+    return {
+        ok: false,
+        reason: `requested ${requested} but envelope billed ${[...new Set(models_seen)].sort().join(', ')}`,
+    };
+}
+
+// ── delta #4 — sweep-level cost ─────────────────────────────────────────────
+
+/** Map a full model id onto a `pricing.yaml` tier, or null when unrecognised. */
+export function tier_for_model(model: string): string | null {
+    const m = model.toLowerCase();
+    for (const tier of ['haiku', 'sonnet', 'opus']) {
+        if (m.includes(tier)) {
+            return tier;
+        }
+    }
+    return null;
+}
+
+/**
+ * Price one run's four buckets separately.
+ *
+ * The buckets differ in price by up to 125×, so a single blended rate over the
+ * summed total is not an approximation — it is a different number.
+ */
+export function cost_usd(b: TokensBreakdown | Record<string, never> | null | undefined, rates: TierRates): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return (
+        (_int(t.input_tokens) * rates.input +
+            _int(t.output_tokens) * rates.output +
+            _int(t.cache_creation_input_tokens) * rates.cache_write +
+            _int(t.cache_read_input_tokens) * rates.cache_read) /
+        1_000_000
+    );
+}
+
+/**
+ * Cumulative sweep spend with a hard cap.
+ *
+ * `--max-budget-usd` is per RUN (default 1.0), so a 30×4×3 sweep at `--budget
+ * 3.5` has a $1,260 ceiling with nothing to stop it. This is the sweep-level
+ * counterpart: the first run that pushes cumulative spend over the cap aborts
+ * the sweep instead of discovering the overrun on the invoice.
+ */
+export class SweepBudget {
+    private _spent = 0;
+
+    constructor(
+        readonly cap_usd: number | null,
+        private readonly rates: TierRates | null,
+    ) {}
+
+    get spent_usd(): number {
+        return this._spent;
+    }
+
+    /** Add one run's cost; return an abort reason when the cap is crossed. */
+    add(b: TokensBreakdown | Record<string, never> | null | undefined): string | null {
+        if (!this.rates) {
+            return null;
+        }
+        this._spent += cost_usd(b, this.rates);
+        if (this.cap_usd !== null && this._spent > this.cap_usd) {
+            return `sweep budget abort: cumulative $${this._spent.toFixed(2)} > cap $${this.cap_usd.toFixed(2)}`;
+        }
+        return null;
+    }
+}
+
+// ── internals ───────────────────────────────────────────────────────────────
+
+function _int(v: unknown): number {
+    return typeof v === 'number' && Number.isFinite(v) ? Math.trunc(v) : 0;
+}
+
+function _dict(v: unknown): Record<string, unknown> {
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+function _list(v: unknown): Record<string, unknown>[] {
+    return Array.isArray(v) ? (v as Record<string, unknown>[]) : [];
+}
+
+function _truthy(v: unknown): boolean {
+    return Boolean(v);
+}
+
+/**
+ * Prompt footprint of one trial record — the stamped `activation` block when
+ * the sweep wrote one, else recomputed from the preserved breakdown (delta #2),
+ * so the audit also reads reports written before the stamp existed.
+ */
+function _runPromptTokens(run: Record<string, unknown>): number {
+    const stamped = _int(_dict(run['activation'])['prompt_tokens']);
+    return stamped > 0 ? stamped : prompt_tokens(run['tokens_breakdown'] as TokensBreakdown | undefined);
+}

package/src/scripts/_lib/gate_ledger.ts

@@ -0,0 +1,295 @@
+/**
+ * Completeness accounting — "planned work reaches exactly one terminal outcome".
+ *
+ * WHY THIS EXISTS. `_lib/scan_scope.ts` closed one half of the false-green
+ * class: a gate whose *root* is dead now fails instead of printing a green
+ * checkmark over zero files. It cannot close the other half. A gate with a live
+ * root that enumerates 300 targets, `continue`s past 280 of them on assorted
+ * unwritten conditions, and checks 20, still exits 0 — and its output is
+ * indistinguishable from a gate that checked all 300. Absence of findings and
+ * absence of scanning look alike, which is the exact failure this repository
+ * has recorded four separate times from its own history.
+ *
+ * The ledger makes the per-target accounting explicit and mechanical:
+ *
+ * 1. The gate **plans** every target it intends to consider.
+ * 2. Every planned target must reach exactly ONE terminal outcome —
+ *    {@link GateLedger.complete}, {@link GateLedger.fail},
+ *    {@link GateLedger.skip}, or {@link GateLedger.outOfScope}.
+ * 3. {@link GateLedger.finalize} throws when any planned target reached none.
+ *
+ * A planned target with no terminal outcome is a silent `continue` — the defect
+ * this module exists to catch. Naming it costs one call at the top of the loop
+ * body and one at each exit.
+ *
+ * **Why skip reasons are a closed union rather than a free string.** Every gate
+ * in this tree already skips targets, and every one of them explains itself in
+ * prose that no reader can aggregate: "excluded dir", "too big", "binary?",
+ * "(no creds)". A closed vocabulary makes the skips countable and comparable
+ * across the estate, and — the load-bearing part — makes an unlisted reason a
+ * *typecheck* failure rather than a code review someone has to notice. Adding a
+ * genuinely new reason is a visible one-line diff to {@link SKIP_REASON_MESSAGE},
+ * which is the review surface a free string never gets.
+ *
+ * Scope note: this is deliberately not a scan-root guard. Use
+ * {@link import('./scan_scope.js').assertScanned} for the root, and this for
+ * the items under it. The two are complementary and a gate wants both.
+ */
+import process from 'node:process';
+
+/**
+ * The closed vocabulary of reasons a planned target may go unchecked.
+ *
+ * Seeded from the reasons this repository's own gates already emit in prose, so
+ * the first adopters translate rather than invent. Every code carries a
+ * one-sentence message in {@link SKIP_REASON_MESSAGE}; a code without one does
+ * not typecheck, because the record type is keyed on this union.
+ */
+export type GateSkipReason =
+    | 'excluded_directory'
+    | 'size_limit'
+    | 'binary_content'
+    | 'missing_credentials'
+    | 'rules_unavailable'
+    | 'manifest_absent'
+    | 'no_applicable_files'
+    | 'disabled_by_configuration'
+    | 'generated_artifact'
+    | 'dead_scan_root'
+    | 'declared_exemption'
+    | 'not_applicable_kind';
+
+/**
+ * One sentence per skip code, printed verbatim in the ledger's own output.
+ *
+ * The sentence is the audit surface: a reader who sees `size_limit ×41` in a
+ * gate's report should be able to decide, without opening the gate, whether 41
+ * unchecked targets is expected.
+ */
+export const SKIP_REASON_MESSAGE: Record<GateSkipReason, string> = {
+    excluded_directory: 'the target sits under a directory this gate deliberately does not walk',
+    size_limit: 'the target exceeds the size ceiling this gate reads within',
+    binary_content: 'the target is not decodable text, so the check does not apply to it',
+    missing_credentials: 'the check needs a credential that is not present in this environment',
+    rules_unavailable: 'the rule or policy corpus this check compares against could not be loaded',
+    manifest_absent: 'the manifest that declares what to check for this target does not exist',
+    no_applicable_files: 'the target resolved to zero files the check applies to',
+    disabled_by_configuration: 'a setting in this repository turns this check off for the target',
+    generated_artifact: 'the target is generated output whose source is checked instead',
+    dead_scan_root: 'the root this target was enumerated from no longer exists',
+    declared_exemption: 'the target carries an explicit, reviewable exemption from this check',
+    not_applicable_kind: 'the target is a kind of artifact this check does not apply to',
+};
+
+/** Terminal outcomes a planned target can reach. Exactly one, exactly once. */
+export type GateOutcomeKind = 'completed' | 'failed' | 'skipped' | 'out_of_scope';
+
+/** What {@link GateLedger.finalize} returns once every planned target is accounted for. */
+export interface GateLedgerTally {
+    planned: number;
+    completed: number;
+    skipped: number;
+    failed: number;
+    out_of_scope: number;
+    /** Planned targets that reached no terminal outcome. Non-zero means `finalize` threw. */
+    unaccounted: number;
+    /** Skip counts per code, for the report line and for downstream auditing. */
+    skips_by_reason: Partial<Record<GateSkipReason, number>>;
+}
+
+/** Raised when planned work did not reach a terminal outcome. */
+export class UnaccountedTargetsError extends Error {
+    readonly gate: string;
+    readonly targets: readonly string[];
+
+    constructor(gate: string, targets: readonly string[]) {
+        const shown = targets.slice(0, 20);
+        const more = targets.length - shown.length;
+        super(
+            `${gate}: ${String(targets.length)} planned target(s) reached no terminal outcome — ` +
+                'the gate enumerated them and then neither checked, failed, skipped, nor ' +
+                'excluded them, so its green result covers less than it appears to. ' +
+                `Unaccounted: ${shown.join(', ')}${more > 0 ? ` … and ${String(more)} more` : ''}`,
+        );
+        this.name = 'UnaccountedTargetsError';
+        this.gate = gate;
+        this.targets = targets;
+    }
+}
+
+/**
+ * Raised when the ledger is used incorrectly.
+ *
+ * A double terminal outcome, or an outcome for a target that was never planned,
+ * means the accounting itself is wrong — and an accounting bug that passes
+ * quietly would restore exactly the blind spot this module removes. So these
+ * throw rather than warn.
+ */
+export class LedgerUsageError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'LedgerUsageError';
+    }
+}
+
+interface Resolution {
+    kind: GateOutcomeKind;
+    reason: string;
+}
+
+/**
+ * Per-target completeness ledger for one gate run.
+ *
+ * ```ts
+ * const ledger = new GateLedger('lint_example');
+ * ledger.plan(files);
+ * for (const file of files) {
+ *     if (isGenerated(file)) { ledger.outOfScope(file, 'generated_artifact'); continue; }
+ *     if (tooBig(file)) { ledger.skip(file, 'size_limit'); continue; }
+ *     const finding = check(file);
+ *     if (finding) ledger.fail(file, finding); else ledger.complete(file);
+ * }
+ * ledger.report();          // throws if anything was left unaccounted
+ * ```
+ */
+export class GateLedger {
+    readonly gate: string;
+    /** Insertion-ordered so the unaccounted list reads in enumeration order. */
+    private readonly planned = new Map<string, Resolution | undefined>();
+
+    constructor(gate: string) {
+        this.gate = gate;
+    }
+
+    /** Declare one or more targets this run intends to consider. */
+    plan(target: string | readonly string[]): void {
+        const targets = typeof target === 'string' ? [target] : target;
+        for (const t of targets) {
+            if (this.planned.has(t)) {
+                throw new LedgerUsageError(
+                    `${this.gate}: target planned twice: ${t}. A duplicate plan makes the ` +
+                        'denominator wrong in the direction that hides work.',
+                );
+            }
+            this.planned.set(t, undefined);
+        }
+    }
+
+    /** The target was checked and satisfied the gate. */
+    complete(target: string): void {
+        this.resolve(target, { kind: 'completed', reason: '' });
+    }
+
+    /** The target was checked and violated the gate. `reason` is the finding text. */
+    fail(target: string, reason: string): void {
+        this.resolve(target, { kind: 'failed', reason });
+    }
+
+    /** The target was NOT checked; `reason` names why, from the closed vocabulary. */
+    skip(target: string, reason: GateSkipReason): void {
+        this.resolve(target, { kind: 'skipped', reason });
+    }
+
+    /** The target does not belong to this gate's corpus; `reason` names why. */
+    outOfScope(target: string, reason: GateSkipReason): void {
+        this.resolve(target, { kind: 'out_of_scope', reason });
+    }
+
+    private resolve(target: string, resolution: Resolution): void {
+        if (!this.planned.has(target)) {
+            throw new LedgerUsageError(
+                `${this.gate}: ${resolution.kind} recorded for an unplanned target: ${target}. ` +
+                    'Every target reaching an outcome must first be planned, or the ' +
+                    'denominator understates the work.',
+            );
+        }
+        const existing = this.planned.get(target);
+        if (existing !== undefined) {
+            throw new LedgerUsageError(
+                `${this.gate}: target resolved twice (${existing.kind} then ${resolution.kind}): ${target}.`,
+            );
+        }
+        this.planned.set(target, resolution);
+    }
+
+    /** Planned targets that have not yet reached a terminal outcome, in enumeration order. */
+    unaccountedTargets(): string[] {
+        const out: string[] = [];
+        for (const [target, resolution] of this.planned) {
+            if (resolution === undefined) {
+                out.push(target);
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Close the ledger and return the tally.
+     *
+     * @throws {UnaccountedTargetsError} when any planned target reached no outcome.
+     */
+    finalize(): GateLedgerTally {
+        const unaccounted = this.unaccountedTargets();
+        if (unaccounted.length > 0) {
+            throw new UnaccountedTargetsError(this.gate, unaccounted);
+        }
+        const tally: GateLedgerTally = {
+            planned: this.planned.size,
+            completed: 0,
+            skipped: 0,
+            failed: 0,
+            out_of_scope: 0,
+            unaccounted: 0,
+            skips_by_reason: {},
+        };
+        for (const resolution of this.planned.values()) {
+            if (resolution === undefined) {
+                continue;
+            }
+            if (resolution.kind === 'completed') {
+                tally.completed += 1;
+            } else if (resolution.kind === 'failed') {
+                tally.failed += 1;
+            } else {
+                if (resolution.kind === 'skipped') {
+                    tally.skipped += 1;
+                } else {
+                    tally.out_of_scope += 1;
+                }
+                const code = resolution.reason as GateSkipReason;
+                tally.skips_by_reason[code] = (tally.skips_by_reason[code] ?? 0) + 1;
+            }
+        }
+        return tally;
+    }
+
+    /**
+     * Finalize and print the denominator on the success path.
+     *
+     * The line goes to stdout unconditionally, exactly as
+     * {@link import('./scan_scope.js').reportScanned} does and for the same
+     * recorded reason: CI passes `--quiet`, and a count only visible without it
+     * is not a count. It is deliberately NOT the `scanned: <N>` line
+     * `check_gate_coverage` parses — that stays the single machine-read
+     * coverage signal, and this is the human-auditable completeness breakdown
+     * beside it.
+     *
+     * @throws {UnaccountedTargetsError} via {@link finalize}.
+     */
+    report(write: (chunk: string) => unknown = process.stdout.write.bind(process.stdout)): GateLedgerTally {
+        const tally = this.finalize();
+        const checked = tally.completed + tally.failed;
+        const parts = [
+            `scanned=${String(checked)}`,
+            `planned=${String(tally.planned)}`,
+            `skipped=${String(tally.skipped + tally.out_of_scope)}`,
+        ];
+        write(`${this.gate} ledger: ${parts.join(' ')}\n`);
+        const codes = Object.keys(tally.skips_by_reason).sort() as GateSkipReason[];
+        for (const code of codes) {
+            const n = tally.skips_by_reason[code] ?? 0;
+            write(`  ${code} ×${String(n)} — ${SKIP_REASON_MESSAGE[code]}\n`);
+        }
+        return tally;
+    }
+}