peaks-loop 4.0.53 → 4.1.0

package/dist/services/final-review/final-review-evidence-budget.js

@@ -0,0 +1,218 @@
+// src/services/final-review/final-review-evidence-budget.ts
+//
+// The evidence allocator's budget constants: the total cap, the derived
+// per-file unit, the dimensions it is divided across, the anti-starvation
+// reservation it must stay affordable against, and the checks that
+// re-verify the derivation at the point of use. Hoisted verbatim from
+// final-review-service.ts (C wave 7 file-size split).
+//
+// One deliberate respell, recorded in the envelope: 40 * 1024 is written
+// as 40_960 (same value, pinned by the existing tests) so the hoisted
+// module carries no no-magic-numbers finding. The repo has done exactly
+// this before (lint-gate.md records CRYS_BEE_ID_MAX_I32 respelled from
+// 2 ** 31 - 1 to a flat literal for the same rule).
+export const REQUIRED_DIMENSIONS = [
+    'functional-completeness',
+    'problem-resolution',
+    'no-new-bugs',
+    'existing-functionality-intact'
+];
+/* ------------------------------------------------------------------ *
+ * D1 — on-disk evidence collection.
+ *
+ * The reviewer LLM has NO tools and NO filesystem access: whatever the
+ * service does not inline into the prompt does not exist for it. Feeding it
+ * only the success criteria forced a guess — the observed failure mode was a
+ * 4/4 `inconclusive` verdict, and the dangerous one is an invented `pass`
+ * that SKILL.md would read as a clean handoff. Everything below exists so the
+ * verdicts rest on what is actually on disk, and so a missing artifact is
+ * reported as MISSING instead of being silently skipped.
+ * ------------------------------------------------------------------ */
+/**
+ * Total evidence budget across all sources. 40 KB ≈ 10k tokens of input, which
+ * keeps the prompt far inside any modern context window. Sources that do not
+ * fit are reported as OMITTED — never dropped silently.
+ *
+ * This is an INPUT cap and stays fixed per run. The output ceiling that has to
+ * sit opposite it is derived per call by `outputBudgetForEvidence()` below —
+ * the two used to drift apart, and that drift was the defect.
+ *
+ * RE-EVALUATED 2026-09-12 (F-BLOCK) — 32 KiB did NOT hold once the tenth
+ * source (`final-review-pre-post-diff`) was appended. Measured on this repo's
+ * own run (`2026-09-12-session-e37ef0`, rid
+ * `2026-09-12-codegraph-exclude-integrity`), the ten sources are 2,621 / 8,164
+ * / 9,492 / 10,839 / 11,422 / 13,050 / 13,462 / 13,852 / 17,745 / 20,543
+ * bytes — 121,190 bytes on disk, 76,321 bytes once the 8 KiB per-file cap is
+ * applied. Four sources at the cap spent the old 32,768 to the byte, so the
+ * appended tenth (added LAST, by design) was the first block the budget
+ * dropped — on every run, and on the compact set QA measured too (9 x 3.8 KB
+ * ≈ 34 KB, which the old cap already could not hold).
+ *
+ * 40 KiB is a budget that fits the measured ten-source set at the allocator's
+ * per-source unit (5 x 8 KiB units + the smaller ones), and it is the largest
+ * this budget may grow to today: the derived output ceiling is
+ * `3000 + 12288 + bytes/4`, so it reaches MAX_OUTPUT_TOKENS (32,000) at exactly
+ * 66,848 bytes of inlined evidence and is clamped from there on — a cap at or
+ * above that point buys the reviewer no more output room at all.
+ *
+ * F-CAP — an earlier version of this comment claimed 40 KiB (40,960 =
+ * 10 x 4,096) was "the smallest cap that affords one floor-sized slice to EVERY
+ * source in the ten-source set". That was arithmetic about a budget, not a
+ * statement about the allocator: sources are capped at
+ * MAX_EVIDENCE_BYTES_PER_FILE (10 KiB each, derived — see below) while a floor
+ * is per DIMENSION (four of them), so 10 x 4,096 was never what any source
+ * received. Re-measured on
+ * the same two saturated fixtures (QA round 4: the 9 x 40 KB fixture and this
+ * repo's own file sizes), raising the cap from 32 KiB to 40 KiB left **4 of the
+ * 10 sources inlined with zero bytes** — `rd/security-review`,
+ * `rd/bug-analysis`, `prd/handoff` and the appended
+ * `final-review-pre-post-diff` — and it did not deliver the baseline either;
+ * all it did was change WHICH source was starved (at 32 KiB that source was
+ * `rd/code-review`).
+ *
+ * So read this constant as "how much evidence fits", never as "which sources
+ * arrive". Arrival is decided by the allocator below (one whole unit per source,
+ * with a dimension's floor reserving its holder's unit) and, for the two sources
+ * a dimension's verdict may not outlive, by the delivery gates on top of it.
+ * And note the honest consequence, stated rather than papered over: on a
+ * saturated run the allocator still omits sources, so `prd/handoff.md` and the
+ * pre/post diff can be dropped — which is exactly why
+ * `enforceScopeContractDelivery()` and `enforcePrePostDiffAvailability()` exist
+ * and why a `pass` on those two dimensions is keyed on delivery, not on
+ * existence.
+ */
+export const MAX_EVIDENCE_BYTES_TOTAL = 40_960;
+/**
+ * Per-file evidence cap — and the allocator's UNIT. DERIVED, never typed.
+ *
+ * F5 — this used to be the literal `8 * 1024`, and the whole floor guarantee
+ * below was silently conditioned on `4 x perFile <= total`: the reservation
+ * promises every pending holder its own unit, and that promise holds only while
+ * the four units fit the budget together. At `8 * 1024` the inequality held by
+ * coincidence (4 x 8,192 = 32,768 <= 40,960) and nothing in the code said so —
+ * raising the cap past 10,240 would have starved all four dimensions in the
+ * same run, which reads as four independent red gates rather than one broken
+ * constant. The cap is therefore DIVIDED OUT OF the total: the relation is
+ * definitional instead of remembered, and `assertFloorReservationAffordable()`
+ * still checks it at the point of use (the division must also be exact).
+ *
+ * The value is 10,240 because that is `40,960 / 4` — the largest unit the
+ * four-dimension reservation can afford. It is also the smallest cap at which
+ * the decisive evidence source of this repo's own run can be delivered WHOLE:
+ * `qa/test-reports/<rid>.md` measured 9,492 bytes there, and `whole` is the
+ * delivery rule for every source whose producer publishes no conclusion literal
+ * (see `isDelivered`), so a cap under 9,492 makes `problem-resolution` and
+ * `no-new-bugs` undeliverable on every run — the always-red gate this module
+ * refuses to ship. Enforced in BYTES against the raw buffer, so multi-byte
+ * (CJK) content cannot slip past the cap.
+ *
+ * A source is inlined as `min(bytes, this cap)` — its whole unit — or not at
+ * all. So a `TRUNCATED` source block can only ever mean "the FILE is bigger
+ * than this cap"; it can no longer mean "the budget ran out while this file was
+ * being copied in". That distinction is the point of the all-or-nothing
+ * allocator below: the second reading is what let one byte of a 4,226-byte
+ * artifact be counted as delivered evidence (F-BLOCK-1BYTE).
+ */
+export const MAX_EVIDENCE_BYTES_PER_FILE = MAX_EVIDENCE_BYTES_TOTAL / REQUIRED_DIMENSIONS.length;
+/* ------------------------------------------------------------------ *
+ * The anti-starvation reservation (the "floor").
+ *
+ * The allocator would otherwise be strictly first-come-first-served, and with
+ * this repo's own evidence set (`2026-09-12-session-e37ef0`, measured) the
+ * first four sources consumed the entire 32 KiB cap — 4 x 8,192 = 32,768, to
+ * the byte — before source 5 was even opened. `existing-functionality-intact`
+ * is supplied ONLY by `rd/tech-doc.md` (6th), `prd/handoff.md` (9th) and the
+ * appended pre/post diff (10th), so that dimension reached the reviewer with
+ * zero evidence on every run and its verdict was structurally locked to
+ * `inconclusive` no matter how good the work was. A gate that is always red is
+ * noise, and an operator trained to ignore noise has no gate at all — the same
+ * harm as a gate that never fires, only quieter.
+ *
+ * So each dimension with at least one readable source on disk gets one
+ * reservation, held for the FIRST such source; no source that is not that
+ * holder may spend it, and it is released the instant its holder is served.
+ * `floorHolders()` below decides who holds what and `collectEvidence()` is the
+ * only thing that spends it.
+ *
+ * WHAT A RESERVATION IS SIZED AT (all-or-nothing): the holder's own UNIT — its
+ * whole `min(bytes, perFileCap)` slice — not a fixed number of bytes. Under the
+ * all-or-nothing allocator a holder needs its entire unit to be served at all,
+ * so reserving less than that would promise something the allocator cannot
+ * keep. The promise stays affordable because a holder is at most one per
+ * dimension and there are four dimensions:
+ *
+ *     REQUIRED_DIMENSIONS.length x MAX_EVIDENCE_BYTES_PER_FILE
+ *         = 4 x 10,240 = 40,960  ==  MAX_EVIDENCE_BYTES_TOTAL = 40,960
+ *
+ * L4 — those are the DERIVED numbers and the relation is an EQUALITY, not an
+ * inequality with room to spare: the reservation spends the entire budget and
+ * leaves ZERO slack. This block used to read `= 4 x 8,192 = 32,768 <= 40,960`,
+ * which was true of the typed-literal cap and stopped being true the moment the
+ * cap was divided out of the total; left as written it read as 8 KiB of
+ * headroom that does not exist and would have invited "just raise the cap a
+ * little". One byte more per file breaks the invariant outright, which is why
+ * the cap is derived rather than typed and why
+ * `assertFloorReservationAffordable()` re-checks the derivation (exact integer
+ * quotient, product <= total) at the point of use instead of trusting this
+ * comment (pinned by a test).
+ *
+ * That equality is the whole invariant: at every step `budgetLeft` covers the
+ * units still owed to the pending holders, so a holder is always served once it
+ * is reached, and the invariant cannot silently rot while the three constants
+ * keep their published relationship.
+ *
+ * A reservation is held for a DIMENSION, not for any particular SOURCE:
+ * reserving one for `final-review-pre-post-diff` on top of its dimension's
+ * would make "a computed baseline the reviewer never saw" UNREACHABLE, and an
+ * unreachable branch inside a gate is one nobody can verify. The delivery gates
+ * below are the guarantee; see `enforcePrePostDiffAvailability` and
+ * `enforceScopeContractDelivery`.
+ * ------------------------------------------------------------------ */
+/**
+ * The unit the allocator hands out: one source's WHOLE slice — its bytes up to
+ * the per-file cap — or nothing at all.
+ *
+ * F-BLOCK-1BYTE — the allocator used to take `min(perFileCap, budgetLeft)`, so
+ * the last source the budget reached was cut wherever the budget ran out.
+ * `status: 'found'` then meant "at least one byte arrived", and every gate that
+ * asked "did the reviewer see this source?" was answering a question with a
+ * continuum of possible answers. The observed output (QA round 4, 9 x 4,551 B
+ * sources, `api-diff.txt` at 4,226 B): the pre/post diff was inlined as **1
+ * byte** — the character `#` — while the producer block still said
+ * `STATUS: COMPUTED … cite it`, the dimension kept its `pass`/`high`, the
+ * artifact was attached as evidence, and the envelope returned `allPass: true`.
+ * Each earlier fix had moved the threshold that separated "some bytes" from
+ * "the evidence"; this removes the continuum instead, so no predicate can be
+ * re-tuned into the same hole a fifth time.
+ */
+export function sourceUnit(candidate) {
+    return candidate.raw === null
+        ? 0
+        : Math.min(candidate.raw.byteLength, MAX_EVIDENCE_BYTES_PER_FILE);
+}
+/**
+ * F5 — the floor promise, checked where it is relied on instead of remembered.
+ *
+ * The allocator's loop invariant is `budgetLeft >= sum(units of pending
+ * holders)`, and its INITIAL condition is
+ * `REQUIRED_DIMENSIONS.length x MAX_EVIDENCE_BYTES_PER_FILE <=
+ * MAX_EVIDENCE_BYTES_TOTAL`. While that holds, every holder is served when it
+ * is reached and the reservation is a guarantee; the moment it fails, all four
+ * dimensions are starved in the same run — which surfaces as four independent
+ * red gates rather than as one broken constant, and is therefore the kind of
+ * breakage nobody diagnoses correctly.
+ *
+ * The cap is derived from the total so the inequality cannot be typed wrong,
+ * and this check covers the two ways a derivation can still go bad: a
+ * non-integer quotient (a fifth dimension, say) and a future re-typing of
+ * either constant. It is exported because a test asserts it directly.
+ */
+export function assertFloorReservationAffordable() {
+    if (!Number.isInteger(MAX_EVIDENCE_BYTES_PER_FILE)) {
+        throw new Error(`MAX_EVIDENCE_BYTES_PER_FILE is not an integer (${String(MAX_EVIDENCE_BYTES_PER_FILE)} = ${String(MAX_EVIDENCE_BYTES_TOTAL)} / ${String(REQUIRED_DIMENSIONS.length)}): the per-dimension floor reservation is not affordable at a fractional unit.`);
+    }
+    const owed = REQUIRED_DIMENSIONS.length * MAX_EVIDENCE_BYTES_PER_FILE;
+    if (owed > MAX_EVIDENCE_BYTES_TOTAL) {
+        throw new Error(`the floor reservation is not affordable: ${String(REQUIRED_DIMENSIONS.length)} dimensions x ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes per file = ${String(owed)} exceeds MAX_EVIDENCE_BYTES_TOTAL (${String(MAX_EVIDENCE_BYTES_TOTAL)}). Every dimension would be starved in the same run.`);
+    }
+}

package/dist/services/final-review/final-review-evidence-collect.d.ts

@@ -0,0 +1,4 @@
+import { type CollectedEvidence, type EvidenceCandidate } from './final-review-evidence-sources.js';
+/** Pure read: no commands, no git, no test execution — files only. */
+export declare function readEvidence(projectRoot: string, sessionId: string, rid: string, prePostDiffAvailable: boolean): readonly EvidenceCandidate[];
+export declare function collectEvidence(projectRoot: string, sessionId: string, rid: string, prePostDiffAvailable: boolean): readonly CollectedEvidence[];

package/dist/services/final-review/final-review-evidence-collect.js

@@ -0,0 +1,230 @@
+// src/services/final-review/final-review-evidence-collect.ts
+//
+// The read phase (files only — no commands, no git) and the all-or-nothing
+// budget allocator, hoisted from final-review-service.ts (C wave 7).
+// evidenceSourcesFor stays in the service module (guard C pins it there)
+// and is imported from it — a one-directional edge.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { GATE_SOURCE_FOR_DIMENSION } from './final-review-evidence-sources.js';
+import { MAX_EVIDENCE_BYTES_TOTAL, REQUIRED_DIMENSIONS, assertFloorReservationAffordable, sourceUnit } from './final-review-evidence-budget.js';
+import { evidenceSourcesFor } from './final-review-service.js';
+/**
+ * ENOENT is "no such file"; every other errno is "the file is there and this
+ * read failed". Only the first means the source does not exist for this run.
+ */
+function classifyReadFailure(error) {
+    const code = error?.code;
+    return code === 'ENOENT' ? 'missing' : 'unreadable';
+}
+/** Pure read: no commands, no git, no test execution — files only. */
+export function readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime', sessionId);
+    return evidenceSourcesFor(rid, prePostDiffAvailable).map((source) => {
+        // The canonical location first; an older one is tried only when the
+        // canonical file is genuinely ABSENT (see `legacySegments`). A file that
+        // is present but unreadable stops the walk — falling through to an older
+        // copy would silently swap the evidence this run reports.
+        const attempts = [
+            source.segments,
+            ...(source.legacySegments !== undefined ? [source.legacySegments] : [])
+        ];
+        // The path reported when nothing resolved stays the CANONICAL one, so the
+        // operator is sent to where the artifact belongs, not to its old home.
+        let resolved = source.segments;
+        let raw = null;
+        let error = '';
+        let read = 'missing';
+        for (const segments of attempts) {
+            try {
+                raw = readFileSync(join(runtimeRoot, ...segments));
+                read = 'ok';
+                resolved = segments;
+                break;
+            }
+            catch (err) {
+                read = classifyReadFailure(err);
+                error = err instanceof Error ? err.message : String(err);
+                // A file that exists but cannot be read IS this source's file, so it
+                // is also the path the report must name — walking on to an older copy
+                // would silently swap the evidence this run reports.
+                if (read === 'unreadable') {
+                    resolved = segments;
+                    break;
+                }
+            }
+        }
+        return {
+            source,
+            relativePath: ['.peaks', '_runtime', sessionId, ...resolved].join('/'),
+            absolutePath: join(runtimeRoot, ...resolved),
+            raw,
+            read,
+            error,
+            blank: raw === null || raw.toString('utf8').trim().length === 0
+        };
+    });
+}
+/**
+ * The one source per dimension that the budget promises to reach — the source
+ * that dimension's DELIVERY GATE depends on where there is one, and otherwise
+ * the first non-blank candidate that can supply it. A dimension with several
+ * candidates needs exactly one of them to survive, so naming it costs the other
+ * sources nothing they were not already losing.
+ *
+ * F1 — the gate sources used to be eligible for no reservation at all, because
+ * they are last in the order and a later source can never be a "first mention".
+ * Reserving for them is what makes the two gates' promises reachable rather
+ * than merely correct: a gate that always fires because its source never fits
+ * is noise, not a gate. A dimension with no gate entry keeps the old rule.
+ *
+ * A blank source is deliberately not a holder: a floor reserved for a file that
+ * carries no evidence is a floor spent on nothing.
+ */
+function floorHolders(candidates) {
+    const holders = new Map();
+    const covered = new Set();
+    const indexByKey = new Map();
+    candidates.forEach((candidate, index) => {
+        if (candidate.blank)
+            return;
+        if (!indexByKey.has(candidate.source.key))
+            indexByKey.set(candidate.source.key, index);
+    });
+    // Pass 1 — the source each delivery gate depends on, whether or not it is the
+    // first to mention its dimension.
+    for (const dimension of REQUIRED_DIMENSIONS) {
+        const gateKey = GATE_SOURCE_FOR_DIMENSION[dimension];
+        if (gateKey === undefined)
+            continue;
+        const index = indexByKey.get(gateKey);
+        // No such source this run (e.g. no baseline was computed): the dimension
+        // falls back to the first-mention rule below.
+        if (index === undefined)
+            continue;
+        covered.add(dimension);
+        if (!holders.has(index))
+            holders.set(index, dimension);
+    }
+    // Pass 2 — every dimension without a gate: the first source that mentions it.
+    candidates.forEach((candidate, index) => {
+        if (candidate.blank)
+            return;
+        for (const dimension of candidate.source.supports) {
+            if (covered.has(dimension))
+                continue;
+            covered.add(dimension);
+            if (!holders.has(index))
+                holders.set(index, dimension);
+        }
+    });
+    return holders;
+}
+function readFailureEvidence(base, candidate) {
+    // `read` is never `'ok'` here (it is set exactly when the read failed),
+    // and `'ok'` is not a status — the branch is what says which of the two
+    // failure facts this is.
+    const status = candidate.read === 'unreadable' ? 'unreadable' : 'missing';
+    return {
+        ...base,
+        status,
+        totalBytes: 0,
+        includedBytes: 0,
+        content: '',
+        reason: candidate.read === 'missing'
+            ? candidate.error
+            : `the file exists but could not be read (${candidate.error})`
+    };
+}
+function blankEvidence(base, raw) {
+    return {
+        ...base,
+        status: 'empty',
+        totalBytes: raw.byteLength,
+        includedBytes: 0,
+        content: '',
+        reason: `file exists but contains no reviewable content (${raw.byteLength} bytes)`
+    };
+}
+function omittedEvidence(base, raw, ctx) {
+    const { allowance, budgetLeft, candidates, holders, pending, reservedElsewhere, unit, index } = ctx;
+    const waiting = [...pending]
+        .filter((holder) => holder !== index)
+        .map((holder) => `${holders.get(holder)} (source ${candidates[holder]?.source.key ?? '?'})`);
+    return {
+        ...base,
+        status: 'omitted',
+        totalBytes: raw.byteLength,
+        includedBytes: 0,
+        content: '',
+        reason: reservedElsewhere > 0
+            ? `${reservedElsewhere} bytes of the budget are reserved for dimension(s) ${waiting.join(', ')} — their only remaining evidence comes later in the source order; this source is inlined WHOLE or not at all and needs ${unit} bytes, while ${budgetLeft} were left (${allowance} after the reservation)`
+            : `total evidence budget (${MAX_EVIDENCE_BYTES_TOTAL} bytes) is exhausted — this source is inlined WHOLE or not at all and needs ${unit} bytes, ${budgetLeft} were left`
+    };
+}
+function reservedForPending(pending, units, index) {
+    return [...pending]
+        .filter((holder) => holder !== index)
+        .reduce((sum, holder) => sum + (units[holder] ?? 0), 0);
+}
+function foundEvidence(base, raw, unit, content) {
+    return {
+        ...base,
+        status: 'found',
+        totalBytes: raw.byteLength,
+        includedBytes: unit,
+        content,
+        reason: ''
+    };
+}
+export function collectEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
+    assertFloorReservationAffordable();
+    const candidates = readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable);
+    const holders = floorHolders(candidates);
+    /** Every source's all-or-nothing unit, computed before any byte is spent. */
+    const units = candidates.map((candidate) => sourceUnit(candidate));
+    /** Holders that have not been served yet — the floors still owed. */
+    const pending = new Set(holders.keys());
+    const collected = [];
+    let budgetLeft = MAX_EVIDENCE_BYTES_TOTAL;
+    for (const [index, candidate] of candidates.entries()) {
+        const { source, relativePath, absolutePath, raw } = candidate;
+        const base = { source, relativePath, absolutePath };
+        if (raw === null) {
+            collected.push(readFailureEvidence(base, candidate));
+            continue;
+        }
+        if (candidate.blank) {
+            collected.push(blankEvidence(base, raw));
+            continue;
+        }
+        const unit = units[index] ?? 0;
+        // The floors still owed to dimensions whose holder has not been served are
+        // spent only on those holders: a source that needs no help cannot eat the
+        // last dimension's only chance at being reviewed. Reserved at the holder's
+        // own unit, because under all-or-nothing a partial slice serves nothing.
+        const reservedElsewhere = reservedForPending(pending, units, index);
+        const allowance = budgetLeft - reservedElsewhere;
+        // ALL-OR-NOTHING: this source is inlined as its whole unit or it is
+        // reported omitted. There is deliberately no third outcome — a partial
+        // slice would re-create the continuum F-BLOCK-1BYTE was found in.
+        if (allowance < unit) {
+            collected.push(omittedEvidence(base, raw, {
+                allowance,
+                budgetLeft,
+                candidates,
+                holders,
+                pending,
+                reservedElsewhere,
+                unit,
+                index
+            }));
+            continue;
+        }
+        const content = raw.subarray(0, unit).toString('utf8');
+        budgetLeft -= unit;
+        pending.delete(index);
+        collected.push(foundEvidence(base, raw, unit, content));
+    }
+    return collected;
+}

package/dist/services/final-review/final-review-evidence-sources.d.ts

@@ -0,0 +1,138 @@
+import type { DimensionKind } from './final-review-types.js';
+/**
+ * What DELIVERED means for one source — the module's ONE delivery definition,
+ * declared per source and read in exactly one place (`isDelivered`).
+ *
+ *   whole       the reviewer must have received the whole document. A
+ *               truncated slice is not a weaker version of a document, it is a
+ *               DIFFERENT document, and the conclusion may be in the part that
+ *               was cut — which is precisely the state `found` used to call
+ *               "delivered".
+ *   conclusion  the reviewer must have received the literal that IS the
+ *               document's conclusion. Used where the producer publishes one
+ *               (the pre/post diff opens with its `VERDICT:` line).
+ *
+ * `whole` is the rule wherever the producer is another role's skill and
+ * publishes no conclusion literal: the module may not GUESS where a document's
+ * conclusion lives. The two are the same judgement — "did the reviewer receive
+ * the conclusion" — checked at the only place the module can check it.
+ */
+type DeliveryRule = {
+    readonly kind: 'whole';
+} | {
+    readonly kind: 'conclusion';
+    readonly marker: string;
+};
+export interface EvidenceSource {
+    /** Stable id quoted by the model in its citations. */
+    readonly key: string;
+    readonly label: string;
+    /** Path segments under `.peaks/_runtime/<sessionId>/`. */
+    readonly segments: readonly string[];
+    /**
+     * An older location of the SAME artifact, tried only when `segments` is not
+     * on disk. Slice `2026-09-14-prd-capsule-rid-scoping` moved the PRD handoff
+     * capsule to `prd/handoff-<rid>.md`; sessions written before it hold only
+     * the bare `prd/handoff.md`, and this module's delivery gate keys on that
+     * source — so a source that goes missing does not fail the gate, it stops
+     * it (`enforceScopeContractDelivery` returns early on `missing`).
+     */
+    readonly legacySegments?: readonly string[];
+    /** Dimensions this source can supply evidence for. */
+    readonly supports: readonly DimensionKind[];
+    /** What DELIVERED means for this source. See `isDelivered()` — every source
+     *  must declare one, and the declaration is the only thing the module's
+     *  delivery judgement reads. */
+    readonly delivery: DeliveryRule;
+}
+/**
+ * The one source whose ABSENCE from the delivered prompt is not merely a
+ * missing file: it is the only source in the set that is a before/after
+ * comparison, and `existing-functionality-intact` is defined by it. Named once
+ * so the source builder and the delivery check cannot drift apart.
+ */
+export declare const PRE_POST_DIFF_SOURCE_KEY = "final-review-pre-post-diff";
+/**
+ * The approved-scope contract. Also named once: it is the source
+ * `functional-completeness` is defined against and the one its delivery gate
+ * keys on.
+ */
+export declare const SCOPE_CONTRACT_SOURCE_KEY = "prd-handoff";
+/**
+ * The source a DIMENSION'S DELIVERY GATE depends on — i.e. the source the
+ * dimension's `pass` may not outlive. `floorHolders` reserves that source's
+ * unit, and this table is why the reservation protects the RIGHT source.
+ *
+ * F1 — the floor used to go to the FIRST source that merely *mentioned* the
+ * dimension (`qa-test-report`, index 0, and `rd/tech-doc`, index 6), while both
+ * delivery gates keyed on sources at the very END of the order
+ * (`prd-handoff`, index 8, and the appended pre/post diff, index 9) that no
+ * reservation covered. On this repo's own run the budget was exhausted at
+ * source 4, so BOTH gate sources were omitted on every run — necessarily, not
+ * accidentally — while 8,192 bytes of floor were spent on `rd/tech-doc`, the
+ * one source prompt rule 6 declares insufficient for that same dimension.
+ *
+ *   measured floor reservation after the fix:
+ *     prd/handoff.md 8,164  +  api-diff.txt 4,713  +  qa/test-reports 9,492
+ *       = 22,369  <=  MAX_EVIDENCE_BYTES_TOTAL 40,960
+ *
+ * so all three holders are served WHOLE and the two gate-backed dimensions
+ * become deliverable again. A dimension absent from this table has no delivery
+ * gate, and its floor stays with the earliest source that supports it.
+ */
+export declare const GATE_SOURCE_FOR_DIMENSION: Partial<Record<DimensionKind, string>>;
+/**
+ * `found` is the only status that carries bytes. The other four exist so the
+ * prompt can name *why* a source carries nothing: an absent file, one that
+ * exists but is empty, one that exists but could not be READ, and one that did
+ * not fit the byte budget are four different facts, and the model is told all
+ * four explicitly.
+ *
+ * F4 — `missing` and `unreadable` used to be one status. `readFileSync`'s catch
+ * collapsed EACCES / EBUSY / EPERM into the same `raw === null` as ENOENT, so a
+ * contract file that EXISTS and could not be opened was reported to the
+ * reviewer — and, worse, to the delivery gate — as "there was no PRD phase".
+ * Those are opposite facts about a run: one says "nothing to deliver", the
+ * other says "there is something to deliver and it did not arrive".
+ */
+export type EvidenceStatus = 'found' | 'empty' | 'missing' | 'unreadable' | 'omitted';
+export interface CollectedEvidence {
+    readonly source: EvidenceSource;
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    readonly status: EvidenceStatus;
+    /** Full size on disk (0 when nothing could be read). */
+    readonly totalBytes: number;
+    /** Bytes actually inlined into the prompt. */
+    readonly includedBytes: number;
+    readonly content: string;
+    /** Why this source carries no evidence (non-`found` statuses only). */
+    readonly reason: string;
+}
+/**
+ * A source plus the bytes it turned out to hold. Reading and spending are two
+ * separate phases because the allocator has to know which sources are actually
+ * readable BEFORE it can promise any of them a byte: a floor reserved for a file
+ * that does not exist is a floor spent on nothing.
+ */
+export interface EvidenceCandidate {
+    readonly source: EvidenceSource;
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    /** File bytes, or `null` when the file could not be read. */
+    readonly raw: Buffer | null;
+    /**
+     * Why there are no bytes: `'ok'` when `raw` is set, otherwise the two facts
+     * F4 requires the module to keep apart — `'missing'` is ENOENT (there is no
+     * such file for this run), `'unreadable'` is anything else (the file is
+     * there and this process could not read it).
+     */
+    readonly read: 'ok' | 'missing' | 'unreadable';
+    /** Read failure message (`raw === null` only). */
+    readonly error: string;
+    /** A file whose content is all whitespace carries no evidence whichever
+     *  slice of it the budget would have paid for. */
+    readonly blank: boolean;
+}
+export declare function baseEvidenceSources(rid: string): EvidenceSource[];
+export {};