peaks-loop 4.0.44 → 4.0.46

package/dist/services/final-review/final-review-service.d.ts

@@ -9,12 +9,18 @@ export interface LlmRunner {
         };
     }>;
 }
-import type { FinalReviewOutput } from './final-review-types.js';
+import type { DimensionKind, FinalReviewOutput } from './final-review-types.js';
 import type { CapabilityAuditResult } from '../capability-audit-service/types.js';
 export interface PrepareFinalReviewOptions {
     readonly projectRoot: string;
     readonly sessionId: string;
     readonly llmRunner: LlmRunner;
+    /**
+     * Explicit base ref for the pre/post baseline diff. Unset ⇒ the producer
+     * resolves the merge-base with the upstream default branch itself, and
+     * reports the dimension `unavailable` when it cannot.
+     */
+    readonly baseRef?: string;
 }
 export declare class IncompleteFinalReviewError extends Error {
     readonly code: "INCOMPLETE_FINAL_REVIEW";
@@ -43,52 +49,91 @@ export declare class EmptyReviewReplyError extends Error {
  */
 export declare const MAX_EMPTY_REPLY_ATTEMPTS = 3;
 /**
- * Per-file evidence cap. Real evidence artifacts in this repo run 11–18 KB
- * (`rd/tech-doc.md`, `rd/code-review.md`, `qa/*-findings-*.md`); 8 KB keeps the
- * head of every file (header + verdict + first tables) without letting one
- * verbose artifact crowd out the other sources. Enforced in BYTES against the
- * raw buffer, so multi-byte (CJK) content cannot slip past the cap.
- */
-export declare const MAX_EVIDENCE_BYTES_PER_FILE: number;
-/**
- * Total evidence budget across all sources. 32 KB ≈ 8k tokens of input, which
+ * 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. 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.
+ * 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 declare const MAX_EVIDENCE_BYTES_TOTAL: number;
 /**
- * Reserved floor per dimension — the anti-starvation guarantee.
- *
- * The allocator below used to be strictly first-come-first-served: each source
- * took `min(perFileCap, budgetLeft)` in source order. With this repo's own
- * 9-source evidence set (`2026-09-12-session-e37ef0`, measured) sources 1-4
- * consumed the whole 32 KiB — 4 x 8,192 = 32,768, the cap to the byte — before
- * source 5 was even opened. `existing-functionality-intact` is supplied ONLY by
- * `rd/tech-doc.md` (6th) and `prd/handoff.md` (9th), so that one 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 floor
- * reserved for the FIRST such source, and no source that is not that holder may
- * spend it. The reservation is a floor, never a quota: it is released the
- * instant its holder is served, and whatever the holder does not use flows back
- * into the sequential allocation unchanged.
- *
- * Why 4 KiB: the per-file cap exists to keep the "header + verdict + first
- * tables" — the part a reviewer actually cites. Measured on the same run's
- * artifacts (9 files, 8,164-20,543 bytes each): every one of them states its
- * verdict inside the first ~700 bytes. 4 KiB is ~5x that, so a floor holder is
- * not there for depth — it is there so its dimension is not blind. Four
- * dimensions x 4 KiB = 16 KiB of the 32 KiB cap, so at least half the budget
- * still flows through the sequential path below.
- */
-export declare const MIN_EVIDENCE_BYTES_PER_DIMENSION: number;
+ * 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 declare const MAX_EVIDENCE_BYTES_PER_FILE: number;
 /**
  * Floor — also the value that shipped before this fix, so no evidence set can
  * end up with a smaller budget than it had. ~3000 tokens is enough for the
@@ -110,9 +155,12 @@ export declare const MIN_OUTPUT_TOKENS = 3000;
  * truncated on 2 of 10 real runs.
  *
  * 12288 (12 KiB) is sized so the largest evidence pack the input caps allow
- * lands at 23480 (see the formula below) — about 1.8x the largest value ever
- * OBSERVED to truncate (13240), which is the margin the observed variance
- * asks for. The numbers are in the block comment above.
+ * lands at 25528 (see the formula below; the input cap is 40 KiB as of the
+ * F-BLOCK re-evaluation, and this floor was checked against the raised cap, not
+ * against the 32 KiB the measurements above were taken at — a 12 KiB headroom
+ * under a bigger cap is the conservative direction) — about 1.9x the largest
+ * value ever OBSERVED to truncate (13240), which is the margin the observed
+ * variance asks for. The numbers are in the block comment above.
  */
 export declare const REASONING_HEADROOM_TOKENS: number;
 /**
@@ -174,6 +222,137 @@ export declare function outputBudgetForEvidence(includedEvidenceBytes: number):
  * still gets a call made.
  */
 export declare function resolveOutputBudget(includedEvidenceBytes: number, env?: NodeJS.ProcessEnv): number;
+/**
+ * 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;
+};
+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[];
+    /** 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;
+}
+/**
+ * `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".
+ */
+type EvidenceStatus = 'found' | 'empty' | 'missing' | 'unreadable' | 'omitted';
+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;
+}
+/**
+ * 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 declare function assertFloorReservationAffordable(): void;
+/**
+ * H2 — the reason a dimension is red PERMANENTLY, as opposed to merely unfed on
+ * this run. Reported per source, so the arithmetic is checkable by the reader.
+ */
+export interface UndeliverableDimensionEvidence {
+    readonly dimension: DimensionKind;
+    readonly sources: readonly {
+        readonly key: string;
+        readonly relativePath: string;
+        readonly totalBytes: number;
+    }[];
+}
+/**
+ * H2 — every required dimension whose verdict is locked to `inconclusive` by
+ * BYTE ARITHMETIC rather than by the reviewer's judgement.
+ *
+ * The defect this exists for: `qa/test-reports/<rid>.md` measured 9,492 bytes
+ * on this repo's own run and is the ONLY source on disk for `problem-resolution`
+ * and `no-new-bugs` (the other sources that support them are absent), against a
+ * per-file cap of 10,240 — a 748-byte margin on a file that is REWRITTEN every
+ * round and only grows. The moment it crosses 10,240 both dimensions go
+ * permanently red, and NOTHING said so: `assertFloorReservationAffordable()`
+ * only checks the constant-level relation (`4 x cap <= total`), never whether
+ * any actual source fits the cap it must live under, so the red handoff read as
+ * "the reviewer was unsure" instead of "no evidence can ever reach the
+ * reviewer". A gate that is always red and never explains itself is noise, and
+ * this is the same "always red" harm the floor reservation was built to remove
+ * — one layer down.
+ *
+ * The conditions, all three of which must hold, are chosen so the report cannot
+ * be noise:
+ *   1. NOTHING on disk can back the dimension (no `isDelivered`), and
+ *   2. there IS something on disk to deliver (a source that was never written
+ *      is not a delivery failure — same reasoning as the scope-contract gate's
+ *      `missing` exemption: a run with no QA phase has no report to lose), and
+ *   3. EVERY one of those on-disk sources is structurally undeliverable — a
+ *      single source that merely did not fit TODAY (budget-exhausted `omitted`)
+ *      is a different, self-correcting state and is left to the allocator.
+ *
+ * The report is consumed by the prompt (stated to the reviewer), by the
+ * envelope (a marker on each dimension's summary) and by `needsAttention`
+ * (which also clears `allPass`) — see `enforceDeliveryReachability` and
+ * `renderDeliveryReachabilityStatus`. It is a LOUD STATEMENT, not a silent
+ * downgrade, and it is deliberately not a throw: a crash would destroy the
+ * evidence for the three dimensions that ARE deliverable, and the honest fact
+ * here is per-dimension, so it is reported per-dimension.
+ */
+export declare function undeliverableDimensions(collected: readonly CollectedEvidence[]): readonly UndeliverableDimensionEvidence[];
 export declare function prepareFinalReview(rid: string, opts: PrepareFinalReviewOptions): Promise<FinalReviewOutput>;
 export declare function decideFifthDimension(input: {
     readonly audit: CapabilityAuditResult | null;
@@ -182,3 +361,4 @@ export declare function decideFifthDimension(input: {
     readonly verdict: 'pass' | 'fail' | 'inconclusive';
     readonly reason: string;
 };
+export {};