peaks-loop 4.0.44 → 4.0.45

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 4.0.45 — 2026-09-12 (一个永远无法通过的维度 + 一个验代理的守卫)
+
+**Highlights**:
+
+1. **4 维验收闸里有一维从构造上就不可能通过。** `existing-functionality-intact` 的契约要求一份 `pre-post-diff`（前后结构对比：测试面 / 公开 API 面），而**全仓没有任何东西生产它**。于是它被喂的是 `rd/tech-doc.md`（设计意图）与 `prd/handoff.md`（批准范围）—— 而这个模块自己的文件头注释，把"拿设计意图文档当回归评估"列为它存在的理由。结果：`allPass === true` 对**任何**工作流都不可达。
+
+   本版补上生产者（`pre-post-diff.ts`）：以 base ref 对比工作树，报**测试面**（文件数 / 用例数）、**源文件清单**、**公开 API 面**（顶层 `export` 语句数与名字集合），写入 `.peaks/_runtime/<sessionId>/final-review/api-diff.txt`。**诚实边界写在产物里**：export 检测是行锚定的近似，能发现"少了一个导出"这类结构丢失，**发现不了签名变更**。算不出 baseline 时**不产出 artifact、不编造 diff** —— 该维保持 `inconclusive`。
+
+2. **消费它的那个闸，键在"送达"，不在"产物存在"。** 独立复核连做七轮，每轮都在下一层找到同一个形状 —— 一个接受**代理**的闸（"评审者看到了吗"被替换成"磁盘上有吗"）：
+
+   | 轮 | 被判为"检查过了"的东西 |
+   |---|---|
+   | 1 | `status === 'computed'`（磁盘上有文件） |
+   | 2 | `status === 'found'`（≥1 字节送达） |
+   | 3 | `totalBytes === 0`（把 missing 与 empty 混为一谈） |
+
+   共同根因是：一个源**可以被部分内联**，于是"送达了吗"永远有一个律师式答案。现在分配器是 **per-source 全有或全无**（要么整份、要么 omitted，不存在截在中间），且 `isDelivered` 是这个问题**唯一的家** —— 每个源声明自己的送达规则：`whole`（整份文档；被截断过的文档是另一份文档）或 `conclusion`（一个**就是结论本身**的字面量）。
+
+3. **随之而来的两处实质变化，都要求诚实。**
+   - 证据预算改为**推导**（`10,240 = 总额 / 4`）而不是常量 —— 因为走 `whole` 规则的源一旦超过它，就**永远送不到**。
+   - 一个维度若其全部支撑源都装不下，现在会被**响亮报出**（prompt 里出 `## Evidence delivery reachability` 段、维度 summary 挂 `[delivery-reachability: …]` 标记、并进 `needsAttention`），而不是**静默地永远红**。**故意不抛错** —— 抛错会连带毁掉那三个本来可送达的维度。
+
+4. **反回归守卫本身，就是同一个形状的第 7 个实例 —— 且它一开始是坏的。** 初版守卫按**语法形状**切分源码（只认行首 `function name`），于是**箭头函数、生成器、`export default function`、类方法**一律不被扫描：**8 种等价写法全部放行**，端到端实测"顶层箭头里放 2 个代理字面量"仍 `3 passed EXIT=0`。**一个能放行 8/8 的守卫比没有守卫更糟** —— 它把"没人在看"变成"有东西在看"。
+
+   现在它用仓库自带的 `typescript` 解析 AST、读**函数体内**的 token，于是那 4 种形状绕过全部关闭（实测：往真实源码注入箭头式代理 → 守卫转红）。剩下 4 种**不含该字面量**的改写（拆变量 `const F='found'`、`==`、`item['status']`、字符串拼接）**仍然放行** —— 这一点被**固定成一条通过的测试**，让守卫**陈述自己的边界**而不是暗示一个。
+
+5. **`peaks codegraph status` 在真有缺口时会同时印出两行互相矛盾的话。** 退出码（74）与 `[FAIL]` 细节都是对的，但人第一眼看到的是：
+
+   ```
+   [OK] Index is up to date
+   [FAIL] codegraph index is incomplete: 2 of 1133 tracked source files are excluded …
+   ```
+
+   两个闸在回答不同的问题：上游答"图与上次扫描一致"（确实一致），peaks 答"图覆盖了仓库吗"（没有）。**都对，并排印出来就是矛盾。** 现在上游那行被**归因而非抑制**（措辞与统计保留，只是把它的适用范围说明白），只在这一行、且只在缺口门**确实触发**时改动；无缺口路径逐字节不变（含 ANSI），机器可读 envelope 未动。
+
+**验证**:三个版本常量一致(**4.0.45**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **214 files / 2165 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
+**已知未修 / 边界**:`conclusion` 规则下超大的源不算"不可送达"（结论标记可能在截断点之后）;单一可送达源的**穿越前余量**（本 session 实测 748 B）**没有**告警，只报"已经不可能"的状态;4 维中的 `existing-functionality-intact` 在**非 git 项目**里永久 `inconclusive`（这是诚实结果，已写进 SKILL.md 与 `4-dimensions.md`）。
+
+**备注**:本版的 `prepare-final-review` 闸**未经过独立复核**（前六轮每一轮都经过并各找到 1 个 HIGH;第 7 轮由 orchestrator 自行验证,含箭头注入实测),这一点如实记录以便日后回溯。
+
 ## 4.0.44 — 2026-09-12 (被静默排除的源文件 + 一个验错东西的验收闸)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.44 (2026-09-12) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.45 (2026-09-12) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.44(2026-09-12) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.45(2026-09-12) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/dist/cli/commands/codegraph-commands.d.ts

@@ -10,4 +10,5 @@ import { type ProgramIO } from '../cli-helpers.js';
  * untouched.
  */
 export declare function rewriteBareCodegraphHints(text: string): string;
+export declare function attributeUpstreamUpToDateLine(stdout: string): string;
 export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/codegraph-commands.js

@@ -38,7 +38,48 @@ function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
 export function rewriteBareCodegraphHints(text) {
     return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
 }
-async function runCodegraphCommand(io, command, options, asJson) {
+const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
+/**
+ * Upstream `status` answers a different question than peaks-loop's
+ * integrity gate: upstream says "the on-disk graph matches the last scan"
+ * (true), peaks says "that graph covers the repository" (false when rules
+ * exclude tracked files). Both verdicts are correct, but an unqualified
+ * `[OK] Index is up to date` printed above our `[FAIL] ...` reads as
+ * "nothing to see here" — and the OK is the line the eye lands on first.
+ * The exit code and the JSON envelope are already right; only this line
+ * lies by juxtaposition.
+ *
+ * So: keep upstream's wording — the line stays recognizable, and the
+ * Files/Nodes counts around it are untouched — but drop the bare OK
+ * marker and name the only question it answers. Clean runs never reach
+ * this, so their output stays byte-identical.
+ *
+ * The match is anchored to THAT line. An earlier version keyed on
+ * `includes('up to date')`, which is content-blind: upstream prints other
+ * `[OK] ... are up to date` lines (a language-server or watcher line is the
+ * observed one), and each of those was rewritten into a claim about the
+ * INDEX — a misattribution introduced by a change whose entire purpose was
+ * to stop misleading output. Anything that is not the index line is passed
+ * through byte-for-byte, tail note and all.
+ */
+const INDEX_UP_TO_DATE_RE = /^\[OK\]\s+Index is up to date\b/i;
+export function attributeUpstreamUpToDateLine(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => {
+        const visible = line.replace(ANSI_SGR_PATTERN, '').trim();
+        if (!INDEX_UP_TO_DATE_RE.test(visible)) {
+            return line;
+        }
+        // Only the OK marker is downgraded and the attribution appended: the
+        // rest of the line — including whatever upstream wrote after it — is
+        // preserved, so nothing upstream actually said is replaced.
+        const withoutOk = visible.replace(/^\[OK\]\s*/, '');
+        return `[i] ${withoutOk} (upstream: matches the last scan only; repository coverage is answered below)`;
+    })
+        .join('\n');
+}
+async function runCodegraphCommand(io, command, options, asJson, attributeStdout) {
     try {
         const invocation = createCodegraphInvocation(options);
         const result = await executeCodegraphInvocation(invocation);
@@ -47,7 +88,8 @@ async function runCodegraphCommand(io, command, options, asJson) {
             return;
         }
         const didFail = result.exitCode !== null && result.exitCode !== 0;
-        const stdout = rewriteBareCodegraphHints(result.stdout);
+        const rewritten = rewriteBareCodegraphHints(result.stdout);
+        const stdout = attributeStdout === undefined ? rewritten : attributeStdout(rewritten);
         const stderr = rewriteBareCodegraphHints(result.stderr);
         if (stdout.length > 0) {
             io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
@@ -132,7 +174,11 @@ async function runCodegraphStatusCommand(io, options, asJson) {
         await runCodegraphStatusJson(io, options, integrity, integrityWarning);
     }
     else {
-        await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project });
+        // Only when the gate found a gap: upstream's `[OK] Index is up to
+        // date` answers "consistent with the last scan", and printing it
+        // unqualified right above our `[FAIL]` tells the reader two opposite
+        // things at once. Clean runs get no transform and stay byte-identical.
+        await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrity?.gap === true ? attributeUpstreamUpToDateLine : undefined);
         if (integrityWarning !== null) {
             io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${integrityWarning}`);
         }

package/dist/cli/commands/final-review-commands.js

@@ -113,7 +113,8 @@ export function registerFinalReviewCommands(program, io) {
         .description('Prepare the 4-dimension business review (final-review primitive) for human acceptance (W2 T9 service; CLI surface in W5 M2)')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--session-id <sid>', 'session id whose .peaks/_runtime/<sid>/audit-goal/<rid>.json is the approved goal source')
-        .option('--llm-provider <name>', `LLM provider name: ${SUPPORTED_LLM_PROVIDERS.join(' | ')} (default: ${DEFAULT_LLM_PROVIDER} — performs no review)`, DEFAULT_LLM_PROVIDER)).action(async (rid, options) => {
+        .option('--llm-provider <name>', `LLM provider name: ${SUPPORTED_LLM_PROVIDERS.join(' | ')} (default: ${DEFAULT_LLM_PROVIDER} — performs no review)`, DEFAULT_LLM_PROVIDER)
+        .option('--base <ref>', 'base ref for the pre/post baseline diff (`existing-functionality-intact`); default: merge-base with origin/HEAD, then origin/main, then origin/master, then HEAD~1 — pass this explicitly when none of those resolve')).action(async (rid, options) => {
         // 1. Project root must exist and be a directory.
         const projectValidation = validateProjectRoot(options.project);
         if (!projectValidation.ok) {
@@ -192,6 +193,7 @@ export function registerFinalReviewCommands(program, io) {
                 projectRoot: projectValidation.projectRoot,
                 sessionId: sessionValidation.sessionId,
                 llmRunner,
+                ...(options.base === undefined ? {} : { baseRef: options.base }),
             });
             const data = {
                 status: 'review-complete',

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 {};