@event4u/agent-config 14.13.0 → 14.14.0

package/src/scripts/ai_council/information_gain.ts

@@ -0,0 +1,293 @@
+/**
+ * Expected information gain per cost — step 8.4.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` step 8.4: *"Score
+ * optional next calls by expected information gain per cost, deterministic and
+ * inspectable to start"*, verified by *"the score is reproducible from the
+ * recorded inputs"*.
+ *
+ * ## Every feature is one the tree already computes
+ *
+ * The gain terms are read from {@link DisagreementSignal}
+ * (`disagreement_signal.ts:134`), which 6.1 already established as **zero-cost
+ * and structural** — every input arrives from a verdict the run has already
+ * paid for. No new similarity measure, no new threshold, no model call to
+ * decide whether to make a model call. Forking a second feature set here would
+ * be the same defect 1A.1 forbids for the question hash: two answers to one
+ * question, and the second is the one nobody updates.
+ *
+ * ## "Deterministic and inspectable" is enforced, not promised
+ *
+ * - {@link scoreNextCall} is pure: same record in, same bytes out.
+ * - Terms are summed in a FIXED declared order, so floating-point association
+ *   cannot vary with input ordering.
+ * - The result carries every term's raw value, weight and contribution, so the
+ *   number can be re-derived by hand from what is printed.
+ * - The published figures are rounded to {@link SCORE_PRECISION} decimals, so a
+ *   record round-tripped through JSON reproduces bit-identically.
+ * - {@link reproduceScore} is the verify clause made executable: recompute from
+ *   a record's own inputs and compare.
+ *
+ * ## What an UNAVAILABLE component does, and why it is not zero
+ *
+ * A component the run could not observe is dropped from BOTH the numerator and
+ * the weight denominator. Treating it as 0 would read "not measured" as
+ * "measured, and it showed agreement" — the same NOT-RUN-is-not-a-null failure
+ * this roadmap records elsewhere. `basisComponents` reports how many terms the
+ * gain actually rests on, so a gain over one component is distinguishable from
+ * a gain over five, and {@link scoreNextCall} refuses to produce a gain at all
+ * when nothing is available.
+ *
+ * ## Honest scope
+ *
+ * This scores; it does not decide. 8.5 — stopping when the next call has low
+ * expected value — is explicitly gated on Phase 2 evidence
+ * (`blocker: phase-2-benchmark-cost`), and the weights below are **declared
+ * priors, not fitted values**: nothing has been benchmarked against them.
+ * `revisit-if`: the Phase 2 benchmark shows a term that does not predict a
+ * changed finding, or shows one that does and is absent here.
+ */
+import type { DisagreementSignal, SignalComponent } from './disagreement_signal.js';
+
+/** Decimals every published figure is rounded to. Makes JSON round-trip exact. */
+export const SCORE_PRECISION = 6;
+
+/**
+ * The gain terms, in the FIXED order they are summed.
+ *
+ * `direction` says how the raw component relates to expected gain:
+ *   `'rising'`  — the component rises with DISAGREEMENT, so it is used as-is;
+ *   `'falling'` — it rises with AGREEMENT, so `1 - value` is the gain.
+ *
+ * `weight` is a declared prior. The two divergence terms carry the most because
+ * an unresolved split is the one state where another call can still change the
+ * verdict; `selfSimilarity` is inverted and weighted low because high
+ * self-similarity is exhaustion, which 6.2 already treats as a stop condition
+ * rather than as a gain signal.
+ */
+export const GAIN_TERMS: readonly {
+    readonly key: keyof DisagreementSignal & string;
+    readonly weight: number;
+    readonly direction: 'rising' | 'falling';
+    readonly why: string;
+}[] = [
+    {
+        key: 'stanceDivergence',
+        weight: 0.30,
+        direction: 'rising',
+        why: 'an unresolved split is the one state where another call can still change the verdict',
+    },
+    {
+        key: 'contradictionCount',
+        weight: 0.25,
+        direction: 'rising',
+        why: 'an explicit disagree vote names a specific thing a rebuttal can settle',
+    },
+    {
+        key: 'rankUncertainty',
+        weight: 0.20,
+        direction: 'rising',
+        why: 'tied findings mean the ranking has not resolved and one more input may break it',
+    },
+    {
+        key: 'confidenceSpread',
+        weight: 0.15,
+        direction: 'rising',
+        why: 'a wide confidence range means the members disagree about how sure to be, not only about what',
+    },
+    {
+        key: 'findingOverlap',
+        weight: 0.07,
+        direction: 'falling',
+        why: 'high overlap means the members are already covering the same ground',
+    },
+    {
+        key: 'selfSimilarity',
+        weight: 0.03,
+        direction: 'falling',
+        why: 'high self-similarity is exhaustion, which 6.2 handles as a stop rather than as a gain',
+    },
+];
+
+/** `contradictionCount` is a count, not 0..1; this is its saturation point. */
+export const CONTRADICTION_SATURATION = 5;
+
+/** The cost half. Both figures come from the caller's own estimate. */
+export interface CallCost {
+    /** Provider calls the option would issue. Must be > 0 to be scorable. */
+    readonly calls: number;
+    /** Estimated spend in USD. */
+    readonly costUsd: number;
+}
+
+/** One scorable option, exactly as recorded. */
+export interface NextCallInputs {
+    /** Stable identifier for the option — `cross-exam:c-001`, `round-3`, … */
+    readonly optionId: string;
+    readonly signal: DisagreementSignal;
+    /** Open adversarial triggers. Rising with gain: an open objection is unfinished argument. */
+    readonly unresolvedAdversarialTriggers: number;
+    readonly cost: CallCost;
+}
+
+/** One term's full arithmetic, so the total can be re-derived by hand. */
+export interface TermBreakdown {
+    readonly key: string;
+    readonly available: boolean;
+    /** The component's raw value, or `null` when unavailable. */
+    readonly raw: number | null;
+    /** Why it is unavailable, verbatim from the signal. `null` when available. */
+    readonly reason: string | null;
+    /** Raw mapped into 0..1 gain space (direction applied, count saturated). */
+    readonly normalised: number | null;
+    readonly weight: number;
+    /** `normalised * weight`, or 0 when unavailable. */
+    readonly contribution: number;
+}
+
+export interface NextCallScore {
+    readonly optionId: string;
+    /** 0..1 expected gain, or `null` when NO component was observable. */
+    readonly gain: number | null;
+    /** How many terms the gain rests on. 0..6. */
+    readonly basisComponents: number;
+    /** Sum of the weights of the available terms — the gain's denominator. */
+    readonly weightUsed: number;
+    /** `gain / costUsd`, or `null` when gain is null or cost is not positive. */
+    readonly gainPerCost: number | null;
+    /** `gain / calls`, or `null` on the same conditions. */
+    readonly gainPerCall: number | null;
+    readonly cost: CallCost;
+    readonly terms: readonly TermBreakdown[];
+    /** The trigger bonus applied to the gain, already included in it. */
+    readonly triggerBonus: number;
+}
+
+/** Round to {@link SCORE_PRECISION}. `-0` normalised to `0` so JSON round-trips. */
+export function roundScore(v: number): number {
+    const f = 10 ** SCORE_PRECISION;
+    const r = Math.round(v * f) / f;
+    return Object.is(r, -0) ? 0 : r;
+}
+
+function _normalise(key: string, c: SignalComponent, direction: 'rising' | 'falling'): number {
+    const raw = (c as { value: number }).value;
+    // `contradictionCount` is the one count-valued component; everything else
+    // is already 0..1 by its own contract.
+    const scaled = key === 'contradictionCount' ? Math.min(1, raw / CONTRADICTION_SATURATION) : Math.min(1, Math.max(0, raw));
+    return direction === 'rising' ? scaled : 1 - scaled;
+}
+
+/**
+ * Score one option. Pure — no clock, no randomness, no file, no network.
+ *
+ * The trigger bonus is additive and capped: an unresolved adversarial trigger
+ * raises expected gain because an open objection is unfinished argument (6.2's
+ * own reasoning), but it may not by itself drive the gain to 1 — that would let
+ * one open trigger outvote every measured component.
+ */
+export function scoreNextCall(inputs: NextCallInputs): NextCallScore {
+    const terms: TermBreakdown[] = [];
+    let weighted = 0;
+    let weightUsed = 0;
+    let basisComponents = 0;
+
+    for (const t of GAIN_TERMS) {
+        const c = inputs.signal[t.key] as SignalComponent;
+        if (c !== undefined && c.available) {
+            const normalised = _normalise(t.key, c, t.direction);
+            const contribution = normalised * t.weight;
+            weighted += contribution;
+            weightUsed += t.weight;
+            basisComponents += 1;
+            terms.push({
+                key: t.key,
+                available: true,
+                raw: roundScore(c.value),
+                reason: null,
+                normalised: roundScore(normalised),
+                weight: t.weight,
+                contribution: roundScore(contribution),
+            });
+        } else {
+            terms.push({
+                key: t.key,
+                available: false,
+                raw: null,
+                reason: c === undefined ? 'component-absent' : c.reason,
+                normalised: null,
+                weight: t.weight,
+                contribution: 0,
+            });
+        }
+    }
+
+    const triggerBonus = roundScore(Math.min(0.2, 0.1 * Math.max(0, inputs.unresolvedAdversarialTriggers)));
+    const gain =
+        basisComponents === 0 ? null : roundScore(Math.min(1, weighted / weightUsed + triggerBonus));
+
+    const scorable = gain !== null;
+    return {
+        optionId: inputs.optionId,
+        gain,
+        basisComponents,
+        weightUsed: roundScore(weightUsed),
+        gainPerCost:
+            scorable && inputs.cost.costUsd > 0 ? roundScore((gain as number) / inputs.cost.costUsd) : null,
+        gainPerCall: scorable && inputs.cost.calls > 0 ? roundScore((gain as number) / inputs.cost.calls) : null,
+        cost: inputs.cost,
+        terms,
+        triggerBonus,
+    };
+}
+
+/** Inputs plus the score they produced — the thing 8.4 calls "the recorded inputs". */
+export interface NextCallRecord {
+    readonly inputs: NextCallInputs;
+    readonly score: NextCallScore;
+}
+
+export function recordNextCall(inputs: NextCallInputs): NextCallRecord {
+    return { inputs, score: scoreNextCall(inputs) };
+}
+
+/**
+ * The verify clause, executable: recompute the score from the record's OWN
+ * inputs and report whether it matches byte-for-byte under JSON.
+ */
+export function reproduceScore(record: NextCallRecord): { reproduced: boolean; recomputed: NextCallScore } {
+    const recomputed = scoreNextCall(record.inputs);
+    return { reproduced: JSON.stringify(recomputed) === JSON.stringify(record.score), recomputed };
+}
+
+/** Rank options by gain per USD, then by gain per call, then by id. Deterministic. */
+export function rankByGainPerCost(scores: readonly NextCallScore[]): NextCallScore[] {
+    return [...scores].sort(
+        (a, b) =>
+            (b.gainPerCost ?? -1) - (a.gainPerCost ?? -1) ||
+            (b.gainPerCall ?? -1) - (a.gainPerCall ?? -1) ||
+            (a.optionId < b.optionId ? -1 : a.optionId > b.optionId ? 1 : 0),
+    );
+}
+
+/** Inspectable rendering — every term's arithmetic, so the total is re-derivable by hand. */
+export function renderNextCallScore(s: NextCallScore): string {
+    const lines = [`option ${s.optionId}`];
+    for (const t of s.terms) {
+        lines.push(
+            t.available
+                ? `  ${t.key.padEnd(20)} raw ${String(t.raw).padEnd(10)} × w ${t.weight.toFixed(2)} = ${String(t.contribution)}`
+                : `  ${t.key.padEnd(20)} unavailable (${t.reason ?? '—'}) — excluded from numerator AND denominator`,
+        );
+    }
+    lines.push(
+        `  trigger bonus        ${String(s.triggerBonus)}`,
+        `  weight used          ${String(s.weightUsed)} over ${String(s.basisComponents)} component(s)`,
+        `  gain                 ${s.gain === null ? 'null (nothing observable)' : String(s.gain)}`,
+        `  cost                 ${String(s.cost.calls)} call(s), $${s.cost.costUsd.toFixed(4)}`,
+        `  gain per USD         ${s.gainPerCost === null ? 'null' : String(s.gainPerCost)}`,
+        `  gain per call        ${s.gainPerCall === null ? 'null' : String(s.gainPerCall)}`,
+        '',
+    );
+    return lines.join('\n');
+}

package/src/scripts/ai_council/leakage_corpus.ts

@@ -0,0 +1,385 @@
+/**
+ * Corpus assembler for the provider-recognition leakage bench.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence`,
+ * `blocker: leakage-bench-needs-assembler-and-design-forks`, todo item 1:
+ * `collectGuesses` and `scoreRecognition` in `provider_leakage_bench.ts` both
+ * take `items: readonly LeakageItem[]` as an INJECTED parameter, and nothing in
+ * this tree ever produced those items from real council output. That gap — not
+ * quota, and not the un-committability of the corpus — is what kept the bench
+ * at NOT RUN. This module closes it and nothing else.
+ *
+ * It reads a directory of council response records — the JSON shape
+ * `{ responses: [{ provider, model, text, error, ... }] }` written per council
+ * run — and emits one `LeakageItem` per usable response body, with the response
+ * author as ground truth.
+ *
+ * ── Why the directory is a parameter, not an import ─────────────────────────
+ * `session.ts` binds `RESPONSES_DIR` at module load against the running
+ * checkout's root (`session.ts:70-73`). Importing it would couple this loader
+ * to one root and make it untestable over a fixture tree — and the same
+ * root-binding is part of the retention defect this corpus is the subject of.
+ * So the directory arrives as `opts.responsesDir` and this module imports
+ * nothing from `session.ts`.
+ *
+ * ── What this module does NOT do ────────────────────────────────────────────
+ * It does NOT anonymise. The bodies in `LeakageCorpus.items` are RAW: whatever
+ * the provider wrote, including any self-identification in the prose. An
+ * anonymisation pass is a DECLARED OPEN DESIGN FORK in the blocker above and is
+ * not settled here, so `assembleLeakageCorpus` MUST NOT be fed to a live rater
+ * until that fork is settled — a rater shown a raw body may be reading a
+ * signature rather than a style, and the recognition rate would then measure
+ * the absence of anonymisation rather than its failure.
+ *
+ * The `anonymise` seam below exists so the settled fork has somewhere to land
+ * without changing this module's shape. Its default is `IDENTITY_ANONYMISE`,
+ * which returns its input unchanged — deliberately, and tested for it, so that
+ * "the default anonymiser" can never be mistaken for anonymisation having
+ * happened.
+ *
+ * It also does NOT decide, score, prompt, or dispatch. No CLI, no `main()`, no
+ * transport, no provider calls.
+ *
+ * ── Why nothing here deletes ────────────────────────────────────────────────
+ * This module contains no write, no `unlink` and no `rm`, and must never gain
+ * one. The corpus IS the measurement subject: pruning it destroys the
+ * instrument, and the over-retention of these bodies is itself a recorded
+ * finding rather than a mess to tidy. Retention is therefore REPORTED — both
+ * partitions, counted per family in the census — and enforced by nobody here.
+ * The caller chooses which partition it is willing to measure over.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { LeakageItem } from './provider_leakage_bench.js';
+
+/**
+ * The synthetic fixture's basename. Its own body states that "a live runner
+ * must refuse this file"; that refusal is implemented here rather than
+ * documented, because a recognition rate over hand-written fixture prose
+ * describes the fixture author and not a model.
+ */
+export const SYNTHETIC_FIXTURE_BASENAME = 'smoke-items.json';
+
+/** Any path segment containing this marker is the synthetic bench fixture dir. */
+export const SYNTHETIC_PATH_MARKER = 'council-provider-leakage';
+
+/** Mirrors the declared council retention window. Reported, never applied. */
+export const DEFAULT_RETENTION_DAYS = 7;
+
+const MS_PER_DAY = 86_400_000;
+
+/** Thrown when the assembler is pointed at data that cannot measure leakage. */
+export class SyntheticCorpusRefusal extends Error {
+    readonly source: string;
+    constructor(source: string, why: string) {
+        super(`refusing synthetic corpus data: ${source} — ${why}`);
+        this.name = 'SyntheticCorpusRefusal';
+        this.source = source;
+    }
+}
+
+/** Machine-readable exclusion buckets. A dropped body always names one. */
+export type ExclusionReason =
+    /** Not a `.json` file (the tree also holds `.md` notes and stray dirs). */
+    | 'not-json-file'
+    /** File exists but is not parseable JSON. */
+    | 'unparseable-json'
+    /** Parsed, but carries no top-level `responses` array. */
+    | 'no-responses-array'
+    /** A `responses` entry that is not an object. */
+    | 'not-an-object'
+    /** Entry has a non-falsy `error` — a failed call has no body to rate. */
+    | 'response-carried-error'
+    /** Entry has no non-empty `provider`, so there is no ground truth. */
+    | 'missing-provider'
+    /** Entry has no non-empty `text`, so there is nothing to show a rater. */
+    | 'empty-text';
+
+/** One thing that did not become an item, and why. Never a silent drop. */
+export interface ExcludedRecord {
+    /** Source path relative to `responsesDir`, POSIX-separated. */
+    readonly source: string;
+    /** Index within `responses`, or `null` for a whole-file exclusion. */
+    readonly index: number | null;
+    readonly reason: ExclusionReason;
+    /** One clause of detail, safe to print beside the reason. */
+    readonly detail: string;
+}
+
+/**
+ * A corpus item: a `LeakageItem` plus the provenance the SCORER may see and the
+ * rater may not.
+ */
+export interface CorpusItem extends LeakageItem {
+    /** Source path relative to `responsesDir`, POSIX-separated. */
+    readonly source_file: string;
+    readonly response_index: number;
+    /** Source file mtime in epoch ms — the only retention input. */
+    readonly mtime_ms: number;
+    /** Whether `mtime_ms` falls inside `retention_days` of `now`. Reported only. */
+    readonly within_retention: boolean;
+}
+
+/** Per-family counts. Keys are whatever providers were actually present. */
+export type FamilyCounts = Readonly<Record<string, number>>;
+
+export interface CorpusCensus {
+    readonly files_scanned: number;
+    readonly files_excluded: number;
+    readonly responses_seen: number;
+    readonly items_kept: number;
+    readonly items_excluded: number;
+    /** Echoed so a published census is self-describing. */
+    readonly retention_days: number;
+    readonly now_ms: number;
+    /** Kept items whose source mtime is inside the TTL, counted per family. */
+    readonly within_retention: FamilyCounts;
+    /** Kept items whose source mtime is older than the TTL, per family. */
+    readonly over_retention: FamilyCounts;
+    readonly within_retention_total: number;
+    readonly over_retention_total: number;
+}
+
+export interface LeakageCorpus {
+    readonly items: readonly CorpusItem[];
+    /** Sorted distinct families actually present. Never a hardcoded list. */
+    readonly families: readonly string[];
+    readonly excluded: readonly ExcludedRecord[];
+    readonly census: CorpusCensus;
+}
+
+export interface AssembleOptions {
+    /** Directory of council response records. Walked recursively. */
+    readonly responsesDir: string;
+    /** Epoch ms treated as "now" for the retention partition. */
+    readonly now?: number;
+    readonly retentionDays?: number;
+    /**
+     * The anonymisation seam. Defaults to `IDENTITY_ANONYMISE`, i.e. NO
+     * anonymisation — see the header. Supplying one does not make this module
+     * an anonymiser; it makes the fork's decision injectable.
+     */
+    readonly anonymise?: (text: string) => string;
+}
+
+/** The default `anonymise`: returns its argument unchanged. Not anonymisation. */
+export const IDENTITY_ANONYMISE = (text: string): string => text;
+
+/**
+ * Assemble a leakage corpus from a directory of council response records.
+ *
+ * Throws `SyntheticCorpusRefusal` — never excludes-and-continues — when the
+ * directory or any file in it is synthetic bench data. The blocker's wording is
+ * that a live runner must REFUSE it, and an exclusion is not a refusal: it
+ * would let a run proceed over a silently smaller corpus.
+ */
+export function assembleLeakageCorpus(opts: AssembleOptions): LeakageCorpus {
+    const now = opts.now ?? Date.now();
+    const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    const anonymise = opts.anonymise ?? IDENTITY_ANONYMISE;
+    const root = opts.responsesDir;
+
+    if (_posix(path.resolve(root)).includes(SYNTHETIC_PATH_MARKER)) {
+        throw new SyntheticCorpusRefusal(
+            root,
+            `the directory path contains "${SYNTHETIC_PATH_MARKER}", the synthetic bench fixture location`,
+        );
+    }
+
+    const excluded: ExcludedRecord[] = [];
+    const items: CorpusItem[] = [];
+    let filesScanned = 0;
+    let filesExcluded = 0;
+    let responsesSeen = 0;
+
+    // Sorted relative paths: two runs over the same tree emit byte-identical
+    // output, which a bench whose result gets published has to be able to claim.
+    for (const rel of _walkSorted(root)) {
+        const abs = path.join(root, rel);
+        const base = path.basename(rel);
+
+        if (base === SYNTHETIC_FIXTURE_BASENAME) {
+            throw new SyntheticCorpusRefusal(
+                rel,
+                `basename is the synthetic fixture "${SYNTHETIC_FIXTURE_BASENAME}", whose own body states a live runner must refuse it`,
+            );
+        }
+        if (!base.endsWith('.json')) {
+            excluded.push({ source: rel, index: null, reason: 'not-json-file', detail: 'no .json extension' });
+            filesExcluded += 1;
+            continue;
+        }
+
+        filesScanned += 1;
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+        } catch (err) {
+            excluded.push({
+                source: rel,
+                index: null,
+                reason: 'unparseable-json',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            filesExcluded += 1;
+            continue;
+        }
+
+        // A truthy top-level `synthetic` key is the fixture's self-declaration.
+        // Checked after the basename guard so a renamed fixture is still caught.
+        if (_isRecord(parsed) && Boolean(parsed['synthetic'])) {
+            throw new SyntheticCorpusRefusal(rel, 'the record carries a truthy top-level "synthetic" key');
+        }
+
+        const responses = _isRecord(parsed) ? parsed['responses'] : undefined;
+        if (!Array.isArray(responses)) {
+            excluded.push({
+                source: rel,
+                index: null,
+                reason: 'no-responses-array',
+                detail: 'no top-level `responses` array',
+            });
+            filesExcluded += 1;
+            continue;
+        }
+
+        const mtimeMs = fs.statSync(abs).mtimeMs;
+        const withinRetention = now - mtimeMs <= retentionDays * MS_PER_DAY;
+
+        for (let i = 0; i < responses.length; i += 1) {
+            responsesSeen += 1;
+            const entry: unknown = responses[i];
+            if (!_isRecord(entry)) {
+                excluded.push({ source: rel, index: i, reason: 'not-an-object', detail: `entry is ${typeof entry}` });
+                continue;
+            }
+            const error = entry['error'];
+            if (Boolean(error)) {
+                excluded.push({
+                    source: rel,
+                    index: i,
+                    reason: 'response-carried-error',
+                    detail: typeof error === 'string' ? error.slice(0, 120) : 'non-falsy error field',
+                });
+                continue;
+            }
+            const provider = _nonEmptyString(entry['provider']);
+            if (provider === null) {
+                excluded.push({ source: rel, index: i, reason: 'missing-provider', detail: 'no non-empty provider' });
+                continue;
+            }
+            const text = _nonEmptyString(entry['text']);
+            if (text === null) {
+                excluded.push({ source: rel, index: i, reason: 'empty-text', detail: 'no non-empty text' });
+                continue;
+            }
+            items.push({
+                id: leakageItemId(rel, i),
+                text: anonymise(text),
+                true_family: provider,
+                source_file: rel,
+                response_index: i,
+                mtime_ms: mtimeMs,
+                within_retention: withinRetention,
+            });
+        }
+    }
+
+    const within: Record<string, number> = {};
+    const over: Record<string, number> = {};
+    for (const item of items) {
+        const bucket = item.within_retention ? within : over;
+        bucket[item.true_family] = (bucket[item.true_family] ?? 0) + 1;
+    }
+
+    return {
+        items,
+        families: [...new Set(items.map((i) => i.true_family))].sort(),
+        excluded,
+        census: {
+            files_scanned: filesScanned,
+            files_excluded: filesExcluded,
+            responses_seen: responsesSeen,
+            items_kept: items.length,
+            items_excluded: excluded.filter((e) => e.index !== null).length,
+            retention_days: retentionDays,
+            now_ms: now,
+            within_retention: within,
+            over_retention: over,
+            within_retention_total: _sum(within),
+            over_retention_total: _sum(over),
+        },
+    };
+}
+
+/**
+ * Stable, collision-free, OPAQUE item id.
+ *
+ * The id is a digest of the source path plus the response index — NOT the
+ * basename — and that is load-bearing rather than stylistic: real filenames
+ * under `agents/runtime/council/responses/` include
+ * `anthropic-design-skills-integration.json` and several `claude-*.json`, so a
+ * basename-derived id would hand the rater the ground truth in the item's own
+ * identifier and the bench would measure reading, not recognition. The id must
+ * never embed the provider name, or any part of a path that might.
+ *
+ * Deterministic (a digest, not a counter) so two runs over the same tree
+ * produce the same ids, and index-suffixed so two bodies in one file cannot
+ * collide.
+ */
+export function leakageItemId(relPath: string, index: number): string {
+    const digest = crypto.createHash('sha1').update(_posix(relPath)).digest('hex').slice(0, 12);
+    return `item-${digest}-${String(index)}`;
+}
+
+/** Recursive file walk, returning `root`-relative POSIX paths in sorted order. */
+function _walkSorted(root: string): string[] {
+    const out: string[] = [];
+    const visit = (dirRel: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(path.join(root, dirRel), { withFileTypes: true });
+        } catch {
+            return;
+        }
+        const names = entries.map((e) => e.name).sort();
+        for (const name of names) {
+            const rel = dirRel === '' ? name : `${dirRel}/${name}`;
+            const abs = path.join(root, rel);
+            let stat: fs.Stats;
+            try {
+                stat = fs.statSync(abs);
+            } catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                // Real records nest: `<slug>.json/` directories hold per-round
+                // files. Recursing keeps those bodies eligible; the relative
+                // path keeps their ids distinct.
+                visit(rel);
+            } else if (stat.isFile()) {
+                out.push(rel);
+            }
+        }
+    };
+    visit('');
+    return out.sort();
+}
+
+function _posix(p: string): string {
+    return p.split(path.sep).join('/');
+}
+
+function _isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function _nonEmptyString(v: unknown): string | null {
+    return typeof v === 'string' && v.trim() !== '' ? v : null;
+}
+
+function _sum(counts: Readonly<Record<string, number>>): number {
+    return Object.values(counts).reduce((a, b) => a + b, 0);
+}