peaks-loop 4.0.43 → 4.0.44

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

@@ -20,6 +20,160 @@ export declare class IncompleteFinalReviewError extends Error {
     readonly code: "INCOMPLETE_FINAL_REVIEW";
     constructor(message: string);
 }
+/**
+ * N4 — the reply carried no text block at all.
+ *
+ * Measured 2/3 on this repo's own machine, and it is NOT truncation: the
+ * provider answered with a response whose `content` has no `text` block (a
+ * reasoning-only turn, a refusal, or a content filter), so there is no JSON to
+ * parse and no budget to raise — an operator sent to "raise the budget" for
+ * this failure would be sent the wrong way. It gets its own class, its own
+ * `code`, and a message that says so, so it is diagnosable instead of being
+ * flattened into "not valid JSON".
+ */
+export declare class EmptyReviewReplyError extends Error {
+    readonly code: "EMPTY_FINAL_REVIEW_REPLY";
+    constructor(message: string);
+}
+/**
+ * How many times an empty reply is retried before it is reported. The failure
+ * was 2/3 on the observed machine — intermittent, not systematic — so a small
+ * bounded retry converts most of it into a completed review, while 3 attempts
+ * keeps a genuinely broken provider from being hammered.
+ */
+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
+ * 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.
+ */
+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;
+/**
+ * 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
+ * envelope skeleton plus a short paragraph per dimension.
+ */
+export declare const MIN_OUTPUT_TOKENS = 3000;
+/**
+ * Headroom for the part of the reply that is not the envelope.
+ *
+ * A Messages-API-compatible endpoint applies `max_tokens` to the WHOLE
+ * response, and a reasoning model spends it on hidden reasoning before it
+ * emits a single character of the 4-dim envelope. Measured on this repo's own
+ * machine (2026-09-12, rid `2026-09-12-codegraph-exclude-integrity`,
+ * `deepseek-flash[1M]` via `api.deepseek.com/anthropic`): `max_tokens=8192`
+ * came back with `output_tokens=8192` and only **574** visible characters —
+ * the entire budget went to reasoning. A bytes-per-token estimate of the
+ * visible output cannot see that cost, which is why the previous formula
+ * budgeted 7096 for a reply that needs 10108 — and why a 13240 budget still
+ * 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.
+ */
+export declare const REASONING_HEADROOM_TOKENS: number;
+/**
+ * Ceiling, 32_000: the value a real run on this machine was forced to in order
+ * to complete the envelope at all, and the largest this endpoint was observed
+ * to accept. 16384 was tried first and truncated 2/10 — a ceiling that is
+ * merely "above the last successful measurement" is not above the requirement,
+ * because the requirement moves with the model's reasoning spend.
+ *
+ * A model that caps output at 8192 will refuse this. That is still strictly
+ * better than shipping a budget measured to be too small, and the env lever
+ * below lets an operator pull it down without a code change.
+ */
+export declare const MAX_OUTPUT_TOKENS = 32000;
+/**
+ * Environment lever. The old failure message told the operator to "raise the
+ * budget" while the budget was a module constant with no CLI flag and no env
+ * var — an instruction that could not be carried out from any surface the
+ * operator has. This is that lever.
+ *
+ * The value is the output ceiling in tokens; it OVERRIDES the derivation below
+ * (it is not a bonus added to it). Unset/invalid/out-of-range handling is in
+ * `resolveOutputBudget`.
+ */
+export declare const MAX_OUTPUT_TOKENS_ENV = "PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS";
+/**
+ * Absolute upper bound the env lever may reach. An endpoint that accepts
+ * `max_tokens` at all accepts this; anything above it is a typo (a stray extra
+ * digit), not an intent, and clamping is safer than sending it.
+ */
+export declare const HARD_MAX_OUTPUT_TOKENS = 64000;
+/**
+ * Inlined bytes that buy one extra output token — 4:1.
+ *
+ * This term prices the visible envelope (4 x `summary` + `evidence[]` +
+ * `confidence` + `overallSummary`) against the evidence the model is required
+ * to cite. It was 8:1, which put the 32 KiB pack at 4096 tokens of visible
+ * output; the same pack has been observed to complete at 10108 and to truncate
+ * at 13240, so 8:1 was pricing the visible side BELOW its own measurement.
+ * 4:1 doubles it to 8192. It is still not treated as the whole budget — see
+ * `REASONING_HEADROOM_TOKENS`.
+ */
+export declare const EVIDENCE_BYTES_PER_OUTPUT_TOKEN = 4;
+/**
+ * Output ceiling for a call whose prompt carries `includedEvidenceBytes` bytes
+ * of inlined evidence. Pure, total, and clamped on both ends — the same
+ * evidence pack always yields the same budget.
+ */
+export declare function outputBudgetForEvidence(includedEvidenceBytes: number): number;
+/**
+ * The budget the call actually uses: the derived one, unless
+ * `PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS` overrides it.
+ *
+ * An override that is not a positive integer THROWS rather than being ignored:
+ * a silent fallback would leave an operator who passed a bad value with the
+ * exact experience this lever exists to remove — a budget they cannot move.
+ * Out-of-range values are clamped, not rejected, so a model needing more than
+ * `HARD_MAX_OUTPUT_TOKENS` (or a model needing less than `MIN_OUTPUT_TOKENS`)
+ * still gets a call made.
+ */
+export declare function resolveOutputBudget(includedEvidenceBytes: number, env?: NodeJS.ProcessEnv): number;
 export declare function prepareFinalReview(rid: string, opts: PrepareFinalReviewOptions): Promise<FinalReviewOutput>;
 export declare function decideFifthDimension(input: {
     readonly audit: CapabilityAuditResult | null;