@orion-agents/orion-code 0.3.26 → 0.3.28

package/CHANGELOG.md

@@ -22,14 +22,115 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.26] — UNRELEASED
-
-> **Status: candidate.** Open. Structured-diff integrity and Session lifecycle: body
-> rows that look like file headers stay body rows (#274), a hunk split across
-> pagination keeps its rows, line numbers and identity (#275), permanent Session
-> deletion removes the v2 Thread records (#276), and exiting a cutover Session no
-> longer rewrites its summary from the frozen legacy JSONL (#277). Plan:
-> `docs/plan/v0.3.26-plan.md`. Not merged, tagged or published.
+## [0.3.28] — UNRELEASED
+
+> **Status: candidate.** Open. The typed `/review` runtime & CLI slice
+> (plan: `docs/plan/v0.3.28-plan.md`, PR2 core of the v0.3.27 review loop):
+> `/review` arguments now parse into the frozen `ReviewSelectorV1` (worktree /
+> `--base` / repeatable `--path`, back-compat single-path filter) and unknown
+> input returns the usage text instead of silently continuing as an ordinary
+> chat turn. The review runs against the admission-time frozen Git snapshot
+> through a bounded single-pass model completion; the model's findings are
+> validated against the contract and anchored to the snapshot manifest, with
+> invalid or unanchored findings counted and surfaced rather than silently
+> dropped. Every run produces a digest-verifiable `CodeReviewResultV1` receipt
+> rendered by the shared formatter with honest state banners: an empty scope
+> reports "no changes under review" without calling the model, and partial,
+> failed, cancelled or inconclusive runs never render as a green pass.
+> Web wiring (PR3) and the qualification benchmark (PR4) remain subsequent
+> slices. Not merged, tagged or published.
+
+### Added
+
+- `src/services/code-review/selector.ts` — the typed `/review` argument
+  parser: empty / `all` → worktree scope, `--base <ref>` → base scope,
+  repeatable `--path <path>` filters, single bare relative path kept as a
+  back-compat worktree filter; unknown options, missing values, repeated
+  `--base`, absolute paths and traversal are typed usage errors. Fourteen
+  tests pin every accepted shape and rejection path.
+- `src/services/code-review/runner.ts` — the bounded single-pass review
+  runner: `resolveReviewBudgets` (tighten-only) → `captureReviewSnapshot`
+  (worktree contained reader) → frozen unified diff captured with the same
+  admission-time arguments → rules digest binding the read-only constraints
+  digest plus ancestor `AGENTS.md` contents → one model completion through an
+  injected adapter → contract validation + snapshot-membership anchoring +
+  `maxFindings` budget → `resolveReviewConclusion` → receipt digest
+  recomputation. Empty scope completes without a model call and is labeled
+  `empty_scope_no_changes`; cancellation, model errors and unparsable output
+  are typed failures, never green passes.
+- `src/services/code-review/format.ts` — the shared TUI formatter: scope and
+  resolved target header, findings grouped P0→P3 with side:line locations,
+  invalid-finding counts, coverage / skips / budget exhaustion footer and a
+  receipt digest line; partial / failed / cancelled banners never render as a
+  clean pass.
+- `/review` command wiring (`src/commands/workflow-commands.ts`,
+  `workflow-command-handlers.ts`): the command is now a read-only builtin
+  that runs the typed workflow; unrecognized arguments return usage, a
+  missing model returns an explicit error, and no path falls back to ordinary
+  chat.
+
+### Changed
+
+- `src/services/code-review/snapshot.ts` exports `reviewUnifiedDiffArgs` so
+  the runner reuses the exact frozen diff arguments instead of re-deriving
+  OIDs after admission; no frozen semantics changed.
+
+### Not run
+
+- Real-PTY CLI verification, Web E2E (no Web changes in this slice), and the
+  paid human-annotated review-quality benchmark remain `not_run`, matching
+  the v0.3.27 plan's PR3/PR4 sequencing.
+
+## [0.3.27] — 2026-10-22
+
+> **Status: published, 2026-10-22.** Tagged `v0.3.27` (`0be5b18`), merged via
+> #283, and visible on npm as registry `latest`. First slice of the
+> professional code review loop
+> (plan: `docs/plan/v0.3.27-plan.md`): the shared review contract (selectors,
+> states, conclusions, findings, tighten-only budgets, receipt digests,
+> stale-applicability) is frozen in `src/services/code-review` and bound by
+> contract tests; the shared Git snapshot reader captures worktree (staged /
+> unstaged / untracked, separate sources) and base (frozen merge-base..HEAD
+> OIDs, rename tracking) scopes with typed scope errors; and the read-only
+> workflow constraints deny every non-read tool by default with a dispatch-level
+> guard whose digest binds receipts. Runtime / CLI wiring (PR2), the Web loop
+> (PR3) and the qualification benchmark (PR4) are subsequent slices of the same
+> plan and are not part of this release; PR2's core CLI slice ships in 0.3.28.
+
+### Added
+
+- #277-plan PR0: `src/services/code-review/contract.ts` — the shared review
+  contract with the plan §4.1 conclusion mapping (a partial, failed, cancelled
+  or untrustworthy review can never surface as a green "no findings"),
+  tighten-only budgets from plan §4.3, finding validation, receipt digests
+  verified by recomputation, and stale-applicability annotation that never
+  rewrites history. Twelve contract tests pin the semantics.
+- PR0: the human-annotation review-quality benchmark set (12 defect + 8 clean
+  samples across TypeScript/JavaScript/Python with content digests, expected
+  triggers, allowed locations and frozen scoring thresholds), awaiting
+  per-sample human sign-off before any paid model run (plan §9.3).
+- PR1: `src/services/code-review/snapshot.ts` — the shared Git snapshot reader:
+  worktree scope records staged (index OIDs), unstaged (working content with
+  before/after digest re-checks) and untracked changes as separate sources;
+  base scope freezes ref/HEAD/merge-base into immutable OIDs with rename
+  tracking and typed `ref_unresolved` / `no_merge_base` errors; sensitive and
+  binary entries are skipped without being read; tightened budgets skip the
+  excess with typed reasons; the contained worktree reader refuses to leave the
+  repository root.
+- PR1: `src/services/code-review/constraints.ts` — deny-by-default read-only
+  workflow constraints (only `read_file`, `list_files`, `glob`, `grep` pass the
+  dispatch-level guard) with a frozen digest that receipts bind.
+
+## [0.3.26] — 2026-10-17
+
+> **Status: published.** Released as `@orion-agents/orion-code@0.3.26` from
+> `refs/tags/v0.3.26`, and merged to `main` as `b810996` (#278). Structured-diff
+> integrity and Session lifecycle: header-lookalike body rows stay body rows
+> (#274), hunks split across pagination keep their rows, line numbers and
+> identity (#275), permanent Session deletion removes the v2 Thread records
+> (#276), and exiting a cutover Session no longer rewrites its summary from the
+> frozen legacy JSONL (#277). Plan: `docs/plan/v0.3.26-plan.md`. GitHub Release:
+> https://github.com/orion-agents/orion-code/releases/tag/v0.3.26
 
 ### Fixed
 

package/README.md

@@ -2,12 +2,15 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.26 candidate — open. Structured-diff integrity and Session lifecycle: header-lookalike
-> body rows stay body rows (#274), hunks split across pagination keep their rows and line
-> numbers (#275), permanent Session deletion removes the v2 Thread records (#276), and
-> exiting a cutover Session no longer regresses its summary from the legacy JSONL (#277).
-> The previous release 0.3.25 is on npm (registry `latest`), tagged `v0.3.25` (`c356323`,
-> #273) and released on GitHub.
+> v0.3.28 candidate — open. The typed `/review` workflow: slash arguments are
+> parsed into the frozen review selector (worktree / `--base` / `--path`, with
+> usage errors instead of silent chat fallback), the review runs against the
+> admission-time frozen Git snapshot through a bounded single-pass model call,
+> model findings are validated against the contract and the snapshot manifest,
+> and the run renders a digest-verifiable receipt with honest state banners
+> (empty scope ≠ review pass; partial / failed / cancelled never green). The
+> previous release 0.3.27 is on npm (registry `latest`), tagged `v0.3.27`
+> (`0be5b18`, #283) and released on GitHub.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.24 plan](docs/plan/v0.3.24-plan.md) ·
@@ -170,10 +173,10 @@ user extension boundaries.
 Node.js 22.12+, 24, and 26 are supported. Use Node 24 LTS for production or Node 26 Current for
 current development environments. Node 20 is upstream EOL and is no longer a v0.3 runtime.
 
-To install the pinned v0.3.26 package when it is available on npm:
+To install the pinned v0.3.28 package when it is available on npm:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.26
+npm install -g @orion-agents/orion-code@0.3.28
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,10 +2,12 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.26 候选版本：进行中。结构化 diff 完整性与会话生命周期：形似文件头的 body 行保持为
-> body 行（#274）、跨页拆分的 hunk 保留行与行号（#275）、永久删除会话同时清除 v2 Thread
-> 记录（#276）、退出已切换会话不再从旧 JSONL 回退 summary（#277）。上一版 0.3.25 已发布
-> npm（registry `latest`）、打 tag `v0.3.25`（`c356323`，#273）并发布 GitHub Release。
+> v0.3.28 候选版本：进行中。类型化 `/review` 审查工作流：slash 参数解析为冻结的审查
+> selector（worktree / `--base` / `--path`，未知参数返回用法而非静默转入普通聊天）；审查
+> 基于 admission 时冻结的 Git snapshot，经有界单轮模型补全执行；模型 finding 按契约与
+> snapshot manifest 校验；输出 digest 可验证的 receipt 与如实状态横幅（空范围 ≠ 审查通过；
+> partial / failed / cancelled 永远不会显示为绿色）。上一版 0.3.27 已发布 npm
+> （registry `latest`）、打 tag `v0.3.27`（`0be5b18`，#283）并发布 GitHub Release。
 
 [English](README.md) ·
 [v0.3.24 方案](docs/plan/v0.3.24-plan.md) ·
@@ -100,10 +102,10 @@ MCP 仍是用户可见的扩展边界。
 支持 Node.js 22.12+、24 和 26。生产环境建议使用 Node 24 LTS，当前开发环境也支持 Node 26
 Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 
-v0.3.26 在 npm 可用后，可安装固定版本：
+v0.3.28 在 npm 可用后，可安装固定版本：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.26
+npm install -g @orion-agents/orion-code@0.3.28
 orion --version
 orion doctor
 ```

package/dist/commands/workflow-command-handlers.d.ts

@@ -4,5 +4,13 @@ declare function handlePlan(ctx: CommandContext, args: string): Promise<CommandR
 declare function handleDiff(ctx: CommandContext, args: string): CommandResult;
 declare function handleCommitPlan(ctx: CommandContext, args: string): CommandResult;
 declare function continueAsSlashChat(name: string, args: string): CommandResult;
-export { handlePlan, handleDiff, handleCommitPlan, continueAsSlashChat };
+/**
+ * v0.3.28 — the typed `/review` workflow (docs/plan/v0.3.28-plan.md S4).
+ * Arguments are parsed into a frozen selector; unrecognized input returns the
+ * usage text instead of silently continuing as an ordinary chat turn. The
+ * run goes through the bounded single-pass review runner against the frozen
+ * Git snapshot, and the receipt is rendered by the shared formatter.
+ */
+declare function handleReview(ctx: CommandContext, args: string): Promise<CommandResult>;
+export { handlePlan, handleDiff, handleCommitPlan, continueAsSlashChat, handleReview, };
 //# sourceMappingURL=workflow-command-handlers.d.ts.map

package/dist/commands/workflow-command-handlers.js

@@ -5,9 +5,13 @@ exports.handlePlan = handlePlan;
 exports.handleDiff = handleDiff;
 exports.handleCommitPlan = handleCommitPlan;
 exports.continueAsSlashChat = continueAsSlashChat;
+exports.handleReview = handleReview;
 const workspace_diff_1 = require("../services/workspace-diff");
 const commit_plan_1 = require("../services/commit-plan");
 const agent_mode_1 = require("../framework/agent-mode");
+const selector_1 = require("../services/code-review/selector");
+const runner_1 = require("../services/code-review/runner");
+const format_1 = require("../services/code-review/format");
 async function handlePlan(ctx, args) {
     const task = args.trim();
     const [subcommand = '', ...tail] = task.split(/\s+/);
@@ -92,4 +96,66 @@ function continueAsSlashChat(name, args) {
         chatInput: `/${name}${trimmed ? ` ${trimmed}` : ''}`,
     };
 }
+/**
+ * v0.3.28 — the typed `/review` workflow (docs/plan/v0.3.28-plan.md S4).
+ * Arguments are parsed into a frozen selector; unrecognized input returns the
+ * usage text instead of silently continuing as an ordinary chat turn. The
+ * run goes through the bounded single-pass review runner against the frozen
+ * Git snapshot, and the receipt is rendered by the shared formatter.
+ */
+async function handleReview(ctx, args) {
+    const parsed = (0, selector_1.parseReviewSelector)(args);
+    if (!parsed.ok)
+        return { success: false, error: parsed.usage };
+    if (!ctx.llm) {
+        return {
+            success: false,
+            error: 'Code review needs a configured model. Run /model first, then retry /review.',
+        };
+    }
+    const llm = ctx.llm;
+    const outcome = await (0, runner_1.runCodeReview)({
+        cwd: ctx.cwd,
+        selector: parsed.selector,
+        adapter: {
+            async complete(messages) {
+                const response = await llm.chat(messages.map(message => ({ role: message.role, content: message.content })));
+                return {
+                    content: response.content,
+                    model: response.model,
+                    usage: {
+                        inputTokens: response.usage?.promptTokens ?? 0,
+                        outputTokens: response.usage?.completionTokens ?? 0,
+                    },
+                };
+            },
+        },
+        identity: {
+            workspaceIdentity: ctx.cwd,
+            sessionId: ctx.sessionId ?? 'pending-session',
+            threadId: ctx.sessionId ?? 'pending-session',
+            turnId: String(ctx.turnId ?? 'ad-hoc'),
+        },
+        ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
+    });
+    if (!outcome.ok) {
+        const failure = outcome.failure;
+        if (failure.kind === 'cancelled')
+            return { success: false, error: 'Review cancelled.' };
+        if (failure.kind === 'budget') {
+            return { success: false, error: `Review budget rejected: ${failure.field}` };
+        }
+        if (failure.kind === 'snapshot') {
+            return {
+                success: false,
+                error: `Review scope error (${failure.code}): ${failure.message}`,
+            };
+        }
+        if (failure.kind === 'model_error') {
+            return { success: false, error: `Review model call failed: ${failure.message}` };
+        }
+        return { success: false, error: `Review output could not be parsed: ${failure.message}` };
+    }
+    return { success: true, output: (0, format_1.formatReviewReport)(outcome.result) };
+}
 //# sourceMappingURL=workflow-command-handlers.js.map

package/dist/commands/workflow-commands.js

@@ -54,14 +54,14 @@ exports.WORKFLOW_COMMANDS = [
     },
     {
         name: 'review',
-        description: 'Review the current change or requested files',
-        argumentHint: '[scope]',
+        description: 'Run a bounded read-only code review of the current change or a base comparison',
+        argumentHint: '[all | --base <ref>] [--path <path>]',
         category: 'workflow',
         priority: 10,
-        type: 'chat',
-        execution: 'agent-workflow',
+        type: 'builtin',
+        execution: 'builtin',
         risk: 'read-only',
-        execute: (_ctx, args) => (0, workflow_command_handlers_1.continueAsSlashChat)('review', args),
+        execute: (ctx, args) => (0, workflow_command_handlers_1.handleReview)(ctx, args),
     },
     {
         name: 'research',

package/dist/services/code-review/constraints.d.ts

@@ -0,0 +1,25 @@
+/** Read-only tools the review turn may use. Only first-party core tools with
+ *  `readOnly: true` in their descriptors qualify (plan §5.1); `edit_file`,
+ *  `exec_command` and `write_file` are structurally excluded. */
+export declare const REVIEW_ALLOWED_TOOLS: ReadonlySet<string>;
+export interface ReviewWorkflowConstraintsV1 {
+    readonly schemaVersion: 1;
+    readonly workflow: 'code-review';
+    readonly allowedTools: readonly string[];
+    readonly constraintsDigest: string;
+    readonly policy: string;
+}
+/** The frozen constraint set with its digest. Receipts and capability
+ *  compilations bind this digest so a policy change invalidates old reviews'
+ *  rules provenance alongside the rules digest. */
+export declare const REVIEW_WORKFLOW_CONSTRAINTS: ReviewWorkflowConstraintsV1;
+export declare class ReviewToolPolicyError extends Error {
+    readonly code: 'review_tool_denied';
+    readonly toolName: string;
+    constructor(message: string, code: 'review_tool_denied', toolName: string);
+}
+/** Dispatch-level re-validation. Called on every tool invocation of a review
+ *  turn — direct calls, batch calls, aliases and steering all funnel through
+ *  here before the gateway executes anything. */
+export declare function assertReviewToolAllowed(toolName: string): void;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/services/code-review/constraints.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewToolPolicyError = exports.REVIEW_WORKFLOW_CONSTRAINTS = exports.REVIEW_ALLOWED_TOOLS = void 0;
+exports.assertReviewToolAllowed = assertReviewToolAllowed;
+/**
+ * v0.3.27 PR1 — read-only workflow constraints for code review (plan §5.1).
+ *
+ * The review turn runs through the normal AgentLoop / ToolGateway, but under
+ * immutable workflow constraints: the model only sees bounded read/list/glob/
+ * grep capabilities, and every dispatch re-validates against this module so
+ * aliases, batch calls, steering or permission escalation (AUTO / ALLOW) can
+ * never widen the turn. The constraint set is deny-by-default: a tool that is
+ * not explicitly allowlisted is rejected, which covers long-tail tools, MCP,
+ * network, task derivation and future additions without maintaining a denylist.
+ *
+ * PR2 wires this guard into the review workflow's dispatch; PR1 ships the
+ * frozen model, its digest, and the negative tests.
+ */
+const canonical_1 = require("../../runtime/protocol/canonical");
+/** Read-only tools the review turn may use. Only first-party core tools with
+ *  `readOnly: true` in their descriptors qualify (plan §5.1); `edit_file`,
+ *  `exec_command` and `write_file` are structurally excluded. */
+exports.REVIEW_ALLOWED_TOOLS = new Set([
+    'read_file',
+    'list_files',
+    'glob',
+    'grep',
+]);
+const REVIEW_CONSTRAINT_CONTENT = Object.freeze({
+    schemaVersion: 1,
+    workflow: 'code-review',
+    mode: 'read-only',
+    allowedTools: [...exports.REVIEW_ALLOWED_TOOLS].sort(),
+    deniedByDefault: Object.freeze([
+        'exec_command',
+        'write_file',
+        'edit_file',
+        'git mutations',
+        'mcp',
+        'network tools',
+        'dynamic skills',
+        'task derivation',
+        'settings mutation',
+    ]),
+    /** Rationale text is part of the digest: changing the policy changes every
+     *  receipt that binds it. */
+    policy: 'The review turn may only inspect the frozen snapshot through the ' +
+        'allowlisted read tools. Permission escalation (AUTO / ALLOW) may tighten ' +
+        'or maintain but never widen this set. Test commands are not run: they ' +
+        'can write caches and mutate the workspace under review.',
+});
+/** The frozen constraint set with its digest. Receipts and capability
+ *  compilations bind this digest so a policy change invalidates old reviews'
+ *  rules provenance alongside the rules digest. */
+exports.REVIEW_WORKFLOW_CONSTRAINTS = Object.freeze({
+    schemaVersion: 1,
+    workflow: 'code-review',
+    allowedTools: REVIEW_CONSTRAINT_CONTENT.allowedTools,
+    constraintsDigest: (0, canonical_1.digestRuntimeValue)(REVIEW_CONSTRAINT_CONTENT),
+    policy: REVIEW_CONSTRAINT_CONTENT.policy,
+});
+class ReviewToolPolicyError extends Error {
+    constructor(message, code, toolName) {
+        super(message);
+        this.code = code;
+        this.toolName = toolName;
+        this.name = 'ReviewToolPolicyError';
+    }
+}
+exports.ReviewToolPolicyError = ReviewToolPolicyError;
+/** Dispatch-level re-validation. Called on every tool invocation of a review
+ *  turn — direct calls, batch calls, aliases and steering all funnel through
+ *  here before the gateway executes anything. */
+function assertReviewToolAllowed(toolName) {
+    if (!exports.REVIEW_ALLOWED_TOOLS.has(toolName)) {
+        throw new ReviewToolPolicyError(`Tool "${toolName}" is not available in a read-only code review turn.`, 'review_tool_denied', toolName);
+    }
+}
+//# sourceMappingURL=constraints.js.map

package/dist/services/code-review/contract.d.ts

@@ -0,0 +1,172 @@
+/** v0.3.27 §3.1 — what a review examines. Parsed once, frozen at admission. */
+export type ReviewSelectorV1 = {
+    readonly kind: 'worktree';
+    readonly paths?: readonly string[];
+} | {
+    readonly kind: 'base';
+    readonly ref: string;
+    readonly paths?: readonly string[];
+};
+/** v0.3.27 §4.1 — run states. `queued`/`running` never carry a conclusion. */
+export type ReviewRunStateV1 = 'queued' | 'running' | 'completed' | 'partial' | 'failed' | 'cancelled';
+/** v0.3.27 §4.1 — terminal conclusions. Absence can only be asserted when the
+ *  state is `completed`, coverage is complete and the output contained no
+ *  invalid findings; everything else maps to findings or inconclusive. */
+export type ReviewConclusionV1 = 'findings' | 'no_findings' | 'inconclusive';
+/** v0.3.27 §6.1 — a stored result's applicability after code or rules change.
+ *  History is never rewritten; staleness is an annotation, not an edit. */
+export type ReviewApplicabilityV1 = 'current' | 'stale';
+/** Priority levels. P0 requires evidence that the defect blocks usage without
+ *  special preconditions; the definition is frozen here and in PR0 tests. */
+export type ReviewFindingPriorityV1 = 'P0' | 'P1' | 'P2' | 'P3';
+/** v0.3.27 §4.1 — one review finding. `fileKey` is validated for shape here;
+ *  membership against the frozen snapshot manifest happens at Host validation
+ *  time (PR1+), never in the model's favor. */
+export interface ReviewFindingV1 {
+    readonly findingId: string;
+    readonly priority: ReviewFindingPriorityV1;
+    readonly title: string;
+    /** The condition under which the defect manifests — not a style opinion. */
+    readonly trigger: string;
+    readonly impact: string;
+    readonly fileKey: string;
+    readonly side: 'old' | 'new';
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly evidence: string;
+}
+/** Coverage is evidence, not a count: what was actually inspected, what was
+ *  skipped and why, and where truncation or budget exhaustion occurred. */
+export interface ReviewCoverageV1 {
+    readonly inspectedFiles: readonly string[];
+    readonly inspectedRanges: readonly {
+        readonly fileKey: string;
+        readonly startLine: number;
+        readonly endLine: number;
+    }[];
+    readonly skipped: readonly {
+        readonly fileKey: string;
+        readonly reason: 'over_budget_files' | 'over_budget_bytes' | 'binary' | 'sensitive' | 'unreadable' | 'changed_during_review' | 'other';
+        readonly detail?: string;
+    }[];
+    readonly truncated: boolean;
+    readonly budgetExhausted: readonly string[];
+}
+/** Whether the declared coverage is internally consistent and complete for the
+ *  resolved selector — computed by the Host from the frozen manifest, never
+ *  taken from the model's self-report (§4.1). */
+export interface ReviewCoverageAssertionV1 {
+    readonly complete: boolean;
+    readonly reason?: string;
+}
+/** v0.3.27 §4.1 — the persisted receipt. `receiptDigest` covers the canonical
+ *  form of everything above it and is recomputed on read. */
+export interface CodeReviewResultV1 {
+    readonly schemaVersion: 1;
+    readonly reviewId: string;
+    readonly workspaceIdentity: string;
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly requestedSelector: ReviewSelectorV1;
+    /** The actually resolved target (commit OIDs, snapshot ids), not the request. */
+    readonly resolvedTarget: {
+        readonly kind: 'worktree' | 'base';
+        readonly baseOid?: string;
+        readonly headOid?: string;
+        readonly snapshotId: string;
+    };
+    /** Digest of the frozen input snapshot; a stored result is stale when this
+     *  no longer matches the current snapshot digest for the same selector. */
+    readonly inputSnapshotDigest: string;
+    readonly rulesDigest: string;
+    readonly state: ReviewRunStateV1;
+    readonly conclusion: ReviewConclusionV1;
+    readonly findings: readonly ReviewFindingV1[];
+    /** Findings that failed validation — counted and surfaced, never silently
+     *  dropped (dropping them must not turn the run into no_findings). */
+    readonly invalidFindingCount: number;
+    readonly coverage: ReviewCoverageV1;
+    readonly coverageAssertion: ReviewCoverageAssertionV1;
+    readonly limits: readonly string[];
+    readonly model: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly receiptDigest: string;
+}
+/** Budgets are ceilings that may only be tightened (§4.3): a provider with a
+ *  smaller window takes the stricter value; nothing may widen them at runtime. */
+export interface ReviewBudgetsV1 {
+    readonly maxFiles: number;
+    readonly maxBodyBytes: number;
+    readonly maxDiffBytes: number;
+    readonly maxReadToolCalls: number;
+    readonly maxDurationMs: number;
+    readonly maxFindings: number;
+    readonly maxResultBytes: number;
+}
+export declare const DEFAULT_REVIEW_BUDGETS: ReviewBudgetsV1;
+/** Text size caps for finding fields, in characters. Chosen so 100 maximal
+ *  findings stay well inside the 256 KiB result bound. */
+export declare const FINDING_TEXT_LIMITS: Readonly<{
+    title: 200;
+    trigger: 2000;
+    impact: 2000;
+    evidence: 4000;
+    fileKey: 1024;
+}>;
+/** Validates one model-produced finding against the frozen shape. Returns the
+ *  finding unchanged when valid; a typed reason when not. Membership against
+ *  the snapshot manifest is a separate Host check (PR1+). */
+export declare function validateReviewFinding(value: unknown): {
+    readonly valid: true;
+    readonly finding: ReviewFindingV1;
+} | {
+    readonly valid: false;
+    readonly reason: 'not_an_object' | 'finding_id_invalid' | 'priority_invalid' | 'title_invalid' | 'trigger_invalid' | 'impact_invalid' | 'file_key_invalid' | 'side_invalid' | 'line_range_invalid' | 'evidence_invalid';
+};
+/**
+ * v0.3.27 §4.1 — the conclusion mapping, frozen as code so CLI and Web cannot
+ * diverge. The invariants:
+ * - `queued`/`running` results carry no conclusion (callers must not call this).
+ * - A state that is not `completed` can never conclude `no_findings`.
+ * - Invalid findings make the output untrustworthy: zero valid findings with
+ *   invalid ones present is `inconclusive`, never a green pass.
+ * - Zero findings without complete coverage is `inconclusive`, never a green
+ *   pass ("不静默截断后宣布全部完成").
+ */
+export declare function resolveReviewConclusion(input: {
+    readonly state: ReviewRunStateV1;
+    readonly validFindingCount: number;
+    readonly invalidFindingCount: number;
+    readonly coverageComplete: boolean;
+}): ReviewConclusionV1;
+/** Applies the budgets with the tighten-only rule: every override must be a
+ *  safe integer at or below the frozen default, otherwise the run is refused
+ *  rather than silently widened. */
+export declare function resolveReviewBudgets(overrides?: Partial<ReviewBudgetsV1>): {
+    readonly ok: true;
+    readonly budgets: ReviewBudgetsV1;
+} | {
+    readonly ok: false;
+    readonly field: string;
+};
+/** Marks a stored result's applicability against the current input snapshot and
+ *  rules digests. The receipt itself is never rewritten. */
+export declare function reviewApplicability(result: Pick<CodeReviewResultV1, 'inputSnapshotDigest' | 'rulesDigest'>, current: {
+    readonly inputSnapshotDigest: string;
+    readonly rulesDigest: string;
+}): ReviewApplicabilityV1;
+/** The receipt digest covers the canonical form of the result with the digest
+ *  field itself excluded, so verification is a recomputation, not a lookup. */
+export declare function computeReceiptDigest(result: Omit<CodeReviewResultV1, 'receiptDigest'>): string;
+/** Verifies a stored receipt by recomputing its digest. */
+export declare function verifyReceiptDigest(result: CodeReviewResultV1): boolean;
+//# sourceMappingURL=contract.d.ts.map