peaks-loop 4.0.43 → 4.0.45

package/dist/services/doctor/doctor-service/checks/codegraph-exclude-integrity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Check: codegraph exclude integrity (`capability:codegraph-exclude-integrity`).
+ *
+ * The companion to `capability:codegraph`. That check answers "is the
+ * upstream package resolvable at the pinned version"; this one answers
+ * "does the project's `.codegraph/config.json` exclude rules silently
+ * drop source files git tracks".
+ *
+ * Why it exists: upstream ships a default `exclude` template matched by
+ * *directory name*, and `config.json`'s `exclude` array replaces those
+ * defaults wholesale. Any default rule whose directory name collides
+ * with a real source directory drops tracked files from the index while
+ * `peaks codegraph status` still printed `[OK] Index is up to date`.
+ *
+ * Read-only by construction — it consumes the same inspector
+ * `peaks codegraph status` gates on and never writes the config.
+ *
+ * Failure posture:
+ *   - codegraph not initialized in the inspected root (no
+ *     `.codegraph/config.json`) → `ok: true`; there is nothing to
+ *     reconcile and a fresh clone must not fail the doctor.
+ *   - a confirmed gap → `ok: false` (blocking; the index is provably
+ *     incomplete and the fix is one command).
+ *   - could not evaluate (not a git work tree, malformed config) →
+ *     `ok: false, severity: 'warning'` so the doctor reports the blind
+ *     spot without flipping the exit code on an unrelated failure.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/codegraph-exclude-integrity.js

@@ -0,0 +1,88 @@
+/**
+ * Check: codegraph exclude integrity (`capability:codegraph-exclude-integrity`).
+ *
+ * The companion to `capability:codegraph`. That check answers "is the
+ * upstream package resolvable at the pinned version"; this one answers
+ * "does the project's `.codegraph/config.json` exclude rules silently
+ * drop source files git tracks".
+ *
+ * Why it exists: upstream ships a default `exclude` template matched by
+ * *directory name*, and `config.json`'s `exclude` array replaces those
+ * defaults wholesale. Any default rule whose directory name collides
+ * with a real source directory drops tracked files from the index while
+ * `peaks codegraph status` still printed `[OK] Index is up to date`.
+ *
+ * Read-only by construction — it consumes the same inspector
+ * `peaks codegraph status` gates on and never writes the config.
+ *
+ * Failure posture:
+ *   - codegraph not initialized in the inspected root (no
+ *     `.codegraph/config.json`) → `ok: true`; there is nothing to
+ *     reconcile and a fresh clone must not fail the doctor.
+ *   - a confirmed gap → `ok: false` (blocking; the index is provably
+ *     incomplete and the fix is one command).
+ *   - could not evaluate (not a git work tree, malformed config) →
+ *     `ok: false, severity: 'warning'` so the doctor reports the blind
+ *     spot without flipping the exit code on an unrelated failure.
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent } from '../../../codegraph/codegraph-exclude-integrity.js';
+const CHECK_ID = 'capability:codegraph-exclude-integrity';
+/** How many rules / offending files the message names before eliding. */
+const MAX_NAMED = 5;
+function defaultProbe() {
+    const projectRoot = process.cwd();
+    // No config → codegraph was never initialized here, so no exclude
+    // list is in play and there is nothing to report.
+    return isCodegraphExcludeConfigPresent(projectRoot)
+        ? inspectCodegraphExcludeIntegrity(projectRoot)
+        : null;
+}
+function renderGapMessage(excludedTrackedCount, trackedSourceCount, rulesToRemove, violations) {
+    const namedRules = rulesToRemove.slice(0, MAX_NAMED).join(', ');
+    const elidedRules = rulesToRemove.length > MAX_NAMED ? `, … (+${rulesToRemove.length - MAX_NAMED})` : '';
+    const namedFiles = violations
+        .slice(0, MAX_NAMED)
+        .map((violation) => `${violation.path} <- ${violation.matchedRule}`)
+        .join('; ');
+    const elidedFiles = violations.length > MAX_NAMED ? `; … (+${violations.length - MAX_NAMED})` : '';
+    return `codegraph index is incomplete: ${excludedTrackedCount} of ${trackedSourceCount} tracked source files are blocked by ${rulesToRemove.length} exclude rule(s) [${namedRules}${elidedRules}]. Blocked: ${namedFiles}${elidedFiles}. Run \`peaks codegraph repair-exclude --project <root>\` to drop them and rebuild the index.`;
+}
+function run({ options }) {
+    const probe = options.codegraphIntegrityProbe ?? defaultProbe;
+    let report;
+    try {
+        report = probe();
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `codegraph exclude integrity could not be evaluated: ${getErrorMessage(error)}`
+            }];
+    }
+    if (report === null) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: 'codegraph is not initialized in this project (no .codegraph/config.json); the exclude list is not in play yet'
+            }];
+    }
+    if (!report.gap) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `codegraph exclude list drops no tracked source file (${report.trackedSourceCount} tracked source file(s) admitted by include)`
+            }];
+    }
+    return [{
+            id: CHECK_ID,
+            ok: false,
+            message: renderGapMessage(report.excludedTrackedCount, report.trackedSourceCount, report.rulesToRemove, report.violations)
+        }];
+}
+export const check = {
+    name: 'codegraph-exclude-integrity',
+    run
+};

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -42,6 +42,7 @@ import { check as workspaceInit } from './checks/workspace-init.js';
 import { check as statuslineInstall } from './checks/statusline-install.js';
 import { check as statuslineRuntime } from './checks/statusline-runtime.js';
 import { check as codegraphCapability } from './checks/codegraph-capability.js';
+import { check as codegraphExcludeIntegrity } from './checks/codegraph-exclude-integrity.js';
 import { check as distSourceVersion } from './checks/dist-source-version.js';
 import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
@@ -70,6 +71,7 @@ export const PLUGINS = [
     statuslineInstall, // id "statusline:install"
     statuslineRuntime, // id "statusline:runtime"
     codegraphCapability, // id "capability:codegraph"
+    codegraphExcludeIntegrity, // id "capability:codegraph-exclude-integrity"
     distSourceVersion, // id "build:dist-version-matches-source"
     multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"

package/dist/services/doctor/doctor-service/types.d.ts

@@ -75,6 +75,25 @@ export type CodegraphCapabilityProbe = {
      */
     managedPath: CodegraphManagedPathInfo | null;
 };
+/**
+ * Structural shape of the codegraph exclude-integrity report the
+ * `capability:codegraph-exclude-integrity` check gates on. Declared
+ * structurally (rather than imported from the codegraph service) to
+ * keep this type module dependency-free — the default probe returns a
+ * `CodegraphExcludeIntegrityReport`, which is assignable here.
+ */
+export type CodegraphExcludeIntegrityProbe = {
+    readonly configPath: string;
+    readonly gap: boolean;
+    readonly trackedSourceCount: number;
+    readonly excludedTrackedCount: number;
+    readonly rulesToRemove: readonly string[];
+    /** One entry per (file, rule) pair. */
+    readonly violations: readonly {
+        readonly path: string;
+        readonly matchedRule: string;
+    }[];
+};
 export type DistVersionComparison = {
     dist: string | null;
     source: string;
@@ -229,6 +248,14 @@ export type DoctorOptions = {
      * `process.cwd()`.
      */
     codegraphManagedPathProbe?: () => CodegraphManagedPathInfo | null;
+    /**
+     * Optional override for the `capability:codegraph-exclude-integrity`
+     * check. Returns the integrity report, or `null` when codegraph is
+     * not initialized in the inspected root (nothing to reconcile). When
+     * omitted, the check inspects `process.cwd()`. Throwing is allowed
+     * and reported as a non-blocking warning.
+     */
+    codegraphIntegrityProbe?: () => CodegraphExcludeIntegrityProbe | null;
     skillPresenceProbe?: () => DoctorSkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
     statusLineInstalledProbe?: () => boolean;

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

@@ -9,17 +9,350 @@ 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";
     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;
+/**
+ * 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 declare const MAX_EVIDENCE_BYTES_TOTAL: 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
+ * 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 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;
+/**
+ * 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;
+/**
+ * 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;
@@ -28,3 +361,4 @@ export declare function decideFifthDimension(input: {
     readonly verdict: 'pass' | 'fail' | 'inconclusive';
     readonly reason: string;
 };
+export {};