opencode-swarm 7.162.0 → 7.163.0

package/dist/pr-review/guardrails.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PR-review recurrence guardrails (issue #2385).
+ *
+ * Exported source scanners implementing the mechanical guardrails the issue
+ * requires. Each scanner is a PURE function over `{ path, content }` source
+ * maps; unit tests prove each scanner flags a synthetic violating snippet
+ * (the guardrail "biting") and then apply it over the real `src/` tree.
+ *
+ * 1. `scanObserverTerminalization` — (a) the historical wait-deadline/no-client
+ *    terminalizer may never reappear by name; (b) in
+ *    `src/tools/dispatch-lanes.ts`, durable delegation-transition writes are
+ *    allowed only inside the sanctioned settlement functions.
+ * 2. `scanParallelCircuitRuleConstruction` — circuit-record construction may
+ *    exist only under `src/pr-review/` (the inline-construction recurrence
+ *    class G-1).
+ *
+ * Issue #2385 originally specified a third scanner for transcript-parsing
+ * locality (the 13 conversion symbols restricted to the legacy adapter),
+ * but its only test consumer was a synthetic-input bite demo with no
+ * production caller. The boundary is already enforced structurally
+ * (the legacy-transcript-adapter is the sole module that owns those symbols,
+ * and the two retained scanners cover the real recurrence classes). A
+ * scanner with no caller would create the appearance of a guardrail where
+ * there is none — per the issue's "no unwired functionality" bar, it was
+ * removed instead.
+ */
+export interface GuardrailSource {
+    path: string;
+    content: string;
+}
+export interface GuardrailHit {
+    path: string;
+    line: number;
+    rule: string;
+    excerpt: string;
+}
+/**
+ * The historical PR-review wait-deadline terminalizer (issue #2381 deleted
+ * it). Any reappearance of these names in `src/` is the exact recurrence
+ * class the issue forbids: a collection wait budget or an unavailable host
+ * messages client must never write a terminal delegation transition.
+ */
+export declare const FORBIDDEN_OBSERVER_TERMINALIZER_SYMBOLS: readonly string[];
+/**
+ * Enclosing functions in `src/tools/dispatch-lanes.ts` that are allowed to
+ * write delegation transitions. Every entry is child-evidence-driven
+ * settlement (typed terminal error, explicit caller cancellation, or the
+ * age+liveness presumed-stale backstop) — never observer-deadline evidence:
+ * - `startAsyncLanePrompt`: `running` transition after a successful launch.
+ * - `appendAsyncLaneLaunchError`: typed `error` for a failed child launch.
+ * - `collectOnce`: explicit caller `cancelled` transition.
+ * - `settleCollectedLane`: `completed`/`error` settlement from child evidence.
+ * - `sweepStaleAsyncLaneRecords`: the presumed-stale `stale` backstop.
+ * Additions must document their evidence source here.
+ */
+export declare const DELEGATION_WRITE_ALLOWED_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Guardrail 2. (a) flags any forbidden historical-terminalizer symbol;
+ * (b) for `src/tools/dispatch-lanes.ts`, flags delegation-transition writes
+ * inside any enclosing function outside the sanctioned allowlist. This
+ * module itself is exempt from rule (a): it DEFINES the forbidden names
+ * (the definition site is not a recurrence, same reasoning as the adapter
+ * allowlist in guardrail 1).
+ */
+export declare function scanObserverTerminalization(sources: readonly GuardrailSource[]): GuardrailHit[];
+/** Guardrail 3 (issue #2385 recurrence class G-1). */
+export declare function scanParallelCircuitRuleConstruction(sources: readonly GuardrailSource[]): GuardrailHit[];

package/dist/pr-review/legacy-transcript-adapter.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Legacy transcript adapter — the transcript/artifact-text → canonical
+ * conversion authority (issue #2385).
+ *
+ * This is the ONLY module allowed to convert raw transcript / artifact text
+ * into canonical PR-review data (verdict rows, per-item verdicts, feedback
+ * classifications). The locality contract is enforced mechanically by
+ * `scanTranscriptParsingOutsideAdapter` in `src/pr-review/guardrails.ts`:
+ * every identifier in `TRANSCRIPT_CONVERSION_SYMBOLS` may appear only in this
+ * file across `src/`. The gate therefore consumes this boundary through the
+ * `legacy*`-prefixed aliases and the test surface exported below — never
+ * through the conversion identifiers themselves.
+ *
+ * Compat gating: the settlement path that accepts legacy (pre-structured-
+ * receipt) transcript text is governed by the delegation record's
+ * `pr_review_legacy_transcript_compatibility` flag (default false), read
+ * through `prReviewLegacyTranscriptCompatibilityEnabled` from
+ * `src/background/pr-review-contract.ts`. That settlement path emits no
+ * deprecation diagnostic today and none is added here; this header documents
+ * the gate only.
+ *
+ * Binding contract (same precedent as `bindPrReviewCompletionHelpers` in
+ * `completion.ts` and `bindPrReviewReentryBindingReader` in
+ * `authorization.ts`): this boundary must never import the orchestration gate
+ * back. Gate-owned composition/settlement helpers are supplied by the owning
+ * gate through `bindPrReviewTranscriptAdapterHelpers`, bound once at gate
+ * module init.
+ *
+ * State typing: the moved functions read only the PR-review slices of the
+ * gate's `PrWorkflowGateState` and `PrReviewGateContext`, expressed as the
+ * local structural interfaces below; the gate passes its full state and
+ * context, which satisfy the slices structurally without a projection step.
+ */
+import { type LaneOutputArtifact } from '../background/lane-output-store.js';
+import { type BackgroundDelegationRecord } from '../background/pending-delegations.js';
+import { type PrReviewRiskImpact, type PrReviewRiskTag } from '../background/pr-review-contract.js';
+export type PrReviewComposablePhase = 'reviewer' | 'critic';
+/** One item's admitted verdict plus the lane provenance that admitted it. */
+export interface PrReviewItemClaim {
+    batchId: string;
+    laneId: string;
+    workflowLane: string;
+    /** Reviewer classification, or critic status. */
+    classification: string;
+    severity: string;
+    /**
+     * Typed risk metadata from the reviewer row (issue #2383). Reviewer claims
+     * only; absent on critic claims, which never re-assess routing risk.
+     */
+    riskImpact?: PrReviewRiskImpact;
+    riskTags?: PrReviewRiskTag[];
+    /**
+     * sha256 of the full canonical `[REVIEWED]` row this claim was parsed from.
+     * Reviewer claims only — this is what a critic batch binds to per item.
+     */
+    rowDigest?: string;
+}
+export interface PrReviewPhaseComposition {
+    /** Item id -> winning claim. Most recent successful lane per item wins. */
+    claims: Map<string, PrReviewItemClaim>;
+    requiredInventory: string[];
+    unclaimed: string[];
+    contributingBatchIds: string[];
+    diagnostics: string[];
+}
+/** Validation-batch shape, as the transcript composition reads it. */
+export interface PrReviewTranscriptBatch {
+    batchId: string;
+    lanes: ReadonlyArray<PrReviewTranscriptLane>;
+    validatedAt: string;
+}
+/** Declared lane shape, as the transcript composition reads it. */
+export interface PrReviewTranscriptLane {
+    laneId: string;
+    workflowLane: string;
+    reviewItemIds?: string[];
+}
+/**
+ * Per-batch coherence keys for item-keyed reviewer/critic composition, as the
+ * adapter reads them (structural slice of the gate's record).
+ */
+export interface PrReviewTranscriptBatchCoherence {
+    /**
+     * The exact candidate/critic inventory this batch's ownership was validated
+     * against at record time.
+     */
+    validatedInventory: string[];
+    /** Critic batches only: per-item sha256 of the authoritative `[REVIEWED]` row. */
+    reviewerItemBindings?: Record<string, string>;
+    /** Key encoding for reviewerItemBindings; absent means legacy raw item IDs. */
+    reviewerItemBindingKeyEncoding?: 'prefixed-v1';
+}
+/** Settled PR_FEEDBACK verification batch, as the adapter reads it. */
+export interface PrReviewTranscriptFeedbackVerification {
+    batchId: string;
+    ownership: ReadonlyArray<{
+        laneId: string;
+    }>;
+}
+/**
+ * The PR-review slice of the owning gate's `PrWorkflowGateState`: exactly the
+ * fields the moved conversion/composition machinery reads directly. The gate's
+ * full state type satisfies this structurally.
+ */
+export interface PrReviewTranscriptState {
+    sessionID: string;
+    prReviewBatchCoherence?: Record<string, PrReviewTranscriptBatchCoherence>;
+    prFeedbackVerifications?: PrReviewTranscriptFeedbackVerification[];
+}
+/** The gate-context surface the transcript composition consumes (full ctx is gate-owned). */
+export interface PrReviewTranscriptContext {
+    readonly revisionDigest: string;
+    reviewer?: PrReviewPhaseComposition;
+    critic?: PrReviewPhaseComposition;
+}
+/** A batch-integrity-qualified record, as the transcript composition consumes it. */
+export interface PrReviewTranscriptQualifiedBatchRecord {
+    record: BackgroundDelegationRecord;
+    expectedLane: PrReviewTranscriptLane;
+    expectedWorkflowLane: string;
+}
+/**
+ * Gate-owned composition/settlement helpers, bound by the owning gate at
+ * module init so this boundary never imports the gate back. Declared with
+ * method syntax on purpose: the gate's implementations accept/return its FULL
+ * state and context types, which are structural supersets of the slices
+ * above, and interface method parameters are checked bivariantly.
+ */
+export interface PrReviewTranscriptGateHelpers {
+    derivePrReviewCandidateInventory(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): string[];
+    derivePrReviewCriticInventory(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): string[];
+    authoritativeReviewerClaims(directory: string, state: PrReviewTranscriptState, ctx: PrReviewTranscriptContext): ReadonlyMap<string, PrReviewItemClaim>;
+    reviewerSubagentSessionIds(directory: string, state: PrReviewTranscriptState): Set<string>;
+    prReviewPhaseWindow(state: PrReviewTranscriptState, phase: PrReviewComposablePhase): PrReviewTranscriptBatch[];
+    batchMayContributeClaims(directory: string, state: PrReviewTranscriptState, batch: PrReviewTranscriptBatch, phase: PrReviewComposablePhase, requiredInventory: readonly string[], forbiddenSubagentSessionIds: ReadonlySet<string>, reviewerClaims: ReadonlyMap<string, PrReviewItemClaim> | undefined, ctx: PrReviewTranscriptContext): boolean;
+    recordsPassingBatchIntegrity(directory: string, state: PrReviewTranscriptState, batchId: string, expectedLanes: ReadonlyArray<PrReviewTranscriptLane>, expectedMode: string, validatedAt: string, checkWorkflowLane?: boolean, forbiddenSubagentSessionIds?: ReadonlySet<string>, diagnostics?: string[]): PrReviewTranscriptQualifiedBatchRecord[];
+    loadArtifactPassingLaneIntegrity(directory: string, state: PrReviewTranscriptState, record: BackgroundDelegationRecord, expectedMode: string, expectedWorkflowLane: string, expectedRevisionDigest: string, diagnostics?: string[]): LaneOutputArtifact | null;
+}
+export declare function bindPrReviewTranscriptAdapterHelpers(helpers: PrReviewTranscriptGateHelpers): void;
+/**
+ * Prefix item IDs before using them as persisted object keys. In particular,
+ * assigning a raw `__proto__` key to an ordinary object invokes JavaScript's
+ * prototype setter instead of creating an own property.
+ */
+export declare function reviewerItemBindingKey(itemId: string): string;
+/**
+ * The single item-keyed computation behind reviewer/critic settlement AND every
+ * reviewer/critic verdict derivation.
+ *
+ * Settlement *is* `unclaimed.length === 0` over this map, so settlement can never
+ * pass while derivation returns nothing — the failure mode that would let
+ * CONFIRMED CRITICAL/HIGH findings ship without critic coverage.
+ *
+ * Scanning the window reverse-chronologically and claiming only *unclaimed*
+ * items makes first-write-wins equal "most recent successful lane per item wins",
+ * which is the explicit conflict rule for the case where two batches both carry a
+ * parseable verdict for one item. Memoized per gate context so two passes never
+ * hold two different verdict maps.
+ *
+ * The scan stops as soon as every required item is claimed (issue #1968 FIX 5).
+ * `readLaneOutput` is a synchronous `readFileSync` per lane per batch, and the
+ * window can hold up to `MAX_WORKFLOW_BATCHES` batches, so scanning past a
+ * complete claim set is unbounded blocking I/O for no verdict change — first
+ * write wins, and every required item has already been written.
+ *
+ * `exhaustive` turns the exit off for the batch GC, which prunes a reviewer
+ * batch on "it contributed no claim". Being precise about what that buys: with
+ * *this* exit condition the two scans yield the same `contributingBatchIds`,
+ * because the exit fires only when every required item is claimed and a batch
+ * reached after that point could never have claimed anything anyway. The flag is
+ * therefore not fixing a live divergence — it decouples a durable-state decision
+ * from a performance heuristic, so that weakening the exit condition later
+ * cannot silently turn "not examined" into "proven inert". It also keeps the
+ * whole-window abandoned-lane diagnostics intact for the GC's scan.
+ */
+export declare function composePrReviewPhaseVerdicts(directory: string, state: PrReviewTranscriptState, phase: PrReviewComposablePhase, ctx: PrReviewTranscriptContext, exhaustive?: boolean): PrReviewPhaseComposition;
+export interface IndexedVerdictRows {
+    markerRows: string[][];
+    rowsByItemId: Map<string, string[][]>;
+    recoveries: Array<{
+        marker: '[REVIEWED]' | '[CRITIC]';
+        itemId: string;
+        recovery: 'legacy-fidelity-safe' | 'legacy-lossy';
+    }>;
+}
+export declare function indexVerdictRows(text: string, marker: '[REVIEWED]' | '[CRITIC]'): IndexedVerdictRows;
+export declare function validateReviewerVerdictFields(fields: string[]): string[] | null;
+/**
+ * Digest of the FULL canonical reviewer row, not the classification/severity
+ * pair a reviewer verdict projects to. Only 2 of the 12 required fields survive
+ * that projection, so a tuple binding would still match a row whose evidence,
+ * file:line and root cause all changed. Fields are joined on NUL, which
+ * `pipeFields` can never produce, so no field boundary is forgeable.
+ */
+export declare function reviewerVerdictRowDigest(fields: readonly string[]): string;
+/**
+ * Per-item verdicts an artifact actually carries, as a map rather than a
+ * boolean. This is the granularity the composition needs: one unparseable item
+ * must not discard its healthy siblings in the same lane.
+ */
+export declare function parseLaneItemVerdicts(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): Map<string, {
+    classification: string;
+    severity: string;
+    riskImpact?: PrReviewRiskImpact;
+    riskTags?: PrReviewRiskTag[];
+    rowDigest?: string;
+}>;
+export declare function parsePrReviewVerdictRows(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): {
+    markerRows: string[][];
+    parsed: Map<string, {
+        classification: string;
+        severity: string;
+        riskImpact?: PrReviewRiskImpact;
+        riskTags?: PrReviewRiskTag[];
+        rowDigest?: string;
+    }>;
+    recoveries: IndexedVerdictRows['recoveries'];
+};
+/** Exact assigned-row contract used by both normal and recovered collection. */
+export declare function analyzePrReviewVerdictRowContract(text: string, itemIds: readonly string[], phase: PrReviewComposablePhase, reviewerClaims?: ReadonlyMap<string, PrReviewItemClaim>): {
+    ok: boolean;
+    expected: string;
+    actual: string;
+    recoveries: IndexedVerdictRows['recoveries'];
+};
+export declare function parseCriticVerdict(text: string, itemId: string, reviewerSeverity?: string): {
+    status: string;
+    severity: string;
+} | null;
+export declare function validateCriticVerdictFields(fields: string[], reviewerSeverity?: string): {
+    status: string;
+    severity: string;
+} | null;
+export declare function artifactHasExactPositiveVerdictRow(text: string, marker: string, itemId: string, positiveVerdict: string): boolean;
+export declare function pipeFields(line: string): string[];
+/**
+ * `pipeFields` capped at the row's canonical field count: separators beyond the
+ * expected count merge back into the trailing (free-text) field. Verdict rows
+ * ([REVIEWED], [CRITIC], [FEEDBACK-VERIFIED]) carry prose evidence in their
+ * last field, and prose containing literal pipes (regex text, `,;|`, shell
+ * snippets) otherwise splits the row past its strict field-count check and the
+ * whole verdict becomes unparseable. Deterministic: the enumerated leading
+ * fields are never merged.
+ */
+export declare function pipeFieldsCapped(line: string, expectedFieldCount: number): string[];
+export declare function feedbackArtifactCoversItems(directory: string, state: PrReviewTranscriptState, batchId: string, laneId: string, itemIds: readonly string[]): boolean;
+export declare function feedbackArtifactTextCoversItems(text: string, itemIds: readonly string[]): boolean;
+/**
+ * Read the settled verification classification of every inventory item from the
+ * settled verification batches' lane outputs (issue #2131 criterion C1). An
+ * item missing from the map has no settled verified classification.
+ */
+export declare function readSettledFeedbackClassifications(directory: string, state: PrReviewTranscriptState): Map<string, string>;
+/**
+ * Issue #2385 guardrail aliases: the transcript-conversion identifiers may
+ * appear only in this module (`scanTranscriptParsingOutsideAdapter` in
+ * `src/pr-review/guardrails.ts`), so the owning gate imports these aliases
+ * instead of the canonical names.
+ */
+export declare const analyzeLegacyVerdictRowContract: typeof analyzePrReviewVerdictRowContract;
+export declare const legacyArtifactHasExactPositiveVerdictRow: typeof artifactHasExactPositiveVerdictRow;
+export declare const legacyFeedbackArtifactCoversItems: typeof feedbackArtifactCoversItems;
+export declare const legacyFeedbackArtifactTextCoversItems: typeof feedbackArtifactTextCoversItems;
+export declare const readLegacySettledFeedbackClassifications: typeof readSettledFeedbackClassifications;
+/**
+ * The gate's historical `_test_exports` surface for this cluster: spread onto
+ * the gate's `_test_exports` at module init so the existing suites keep seeing
+ * the same property names without the gate naming the conversion identifiers.
+ */
+export declare const legacyTranscriptAdapterTestSurface: {
+    pipeFieldsCapped: typeof pipeFieldsCapped;
+    indexVerdictRows: typeof indexVerdictRows;
+    reviewerVerdictRowDigest: typeof reviewerVerdictRowDigest;
+    analyzePrReviewVerdictRowContract: typeof analyzePrReviewVerdictRowContract;
+    parseLaneItemVerdicts: typeof parseLaneItemVerdicts;
+};

package/dist/pr-review/persistence.d.ts

@@ -0,0 +1,107 @@
+/**
+ * PR-review workflow persistence adapter (issues #2385).
+ *
+ * The single atomic persistence boundary for PR-review workflow state, moved
+ * from `src/hooks/pr-workflow-gate.ts` (region: state locks, CAS write,
+ * bounded parsing, atomic JSON writes, safe-parent/identity assertions, path
+ * helpers, in-memory caches). Every durable PR-review gate-state write goes
+ * through this module; the recurrence sweep (issue #2385) forbids direct
+ * writes to the state shape outside this boundary.
+ *
+ * Binding contract (issue #2385 plan, critic item 1): the owning gate binds
+ * (a) its full Zod state codec via `bindPrReviewStateCodec` and (b) its
+ * `_test_exports` object via `bindPrReviewPersistenceHooks`. Properties are
+ * read at CALL time through the bound reference — never destructured at bind
+ * time — so test-time property mutation and `resetTrackedStateCache` remain
+ * fully visible. Defaults in `defaultPersistenceHooks` make the module usable
+ * standalone and are what the gate resets seams back to.
+ *
+ * The recovery-salvage reader (`readPrWorkflowGateStateForRecovery`) remains
+ * in the gate: it composes PR_FEEDBACK sub-schemas (gate-owned) and is a
+ * read-only diagnostic built on these primitives.
+ */
+import type { BigIntStats } from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import type { ZodError } from 'zod';
+export declare function normalizeSessionID(sessionID: string): string;
+export declare function prWorkflowSessionFileStem(sessionID: string): string;
+export declare const WORKFLOW_GATE_DIR = "pr-workflow-gates";
+export declare function workflowGateStateRelativePath(sessionID: string): string;
+export declare function workflowGateStateLockRelativePath(sessionID: string): string;
+export declare function workflowCheckoutMutationLockRelativePath(): string;
+export declare function workflowGateStatePath(directory: string, sessionID: string): string;
+export declare const MAX_TRACKED_SESSIONS = 200;
+export declare const CHECKOUT_MUTATION_ACTION_TIMEOUT_MS: number;
+export declare const trackedStatesByProjectSession: Map<string, PrWorkflowPersistedStateBase>;
+export declare function isoNow(): string;
+export declare function delay(ms: number): Promise<void>;
+export declare function sameBigIntFileIdentity(left: Pick<BigIntStats, 'dev' | 'ino'>, right: Pick<BigIntStats, 'dev' | 'ino'>): boolean;
+export declare function normalizeComparableFsPath(value: string): string;
+export declare function stateCacheKey(directory: string, sessionID: string): string;
+export declare function rememberState<S extends PrWorkflowPersistedStateBase>(directory: string, state: S): void;
+/** Drop one session's cached state (gate clear/abort paths). */
+export declare function forgetTrackedPrWorkflowState(directory: string, sessionID: string): void;
+/** Test reset: clear every in-process persistence cache/queue. */
+export declare function resetPrReviewPersistenceCaches(): void;
+export interface PrReviewPersistenceHooks {
+    nowMs: () => number;
+    isProcessAlive: (pid: number) => boolean;
+    openCheckoutLock: (lockPath: string) => ReturnType<typeof fsp.open>;
+    removeCheckoutLock: (lockPath: string) => Promise<void>;
+    checkoutMutationActionTimeoutMs: number;
+    rename: (from: string, to: string) => Promise<void>;
+    beforeSessionStateLockWrite?: () => Promise<void>;
+    beforeCheckoutLockWrite?: () => Promise<void>;
+    beforeSafeDirectoryCreate?: (parentPath: string, nextPath: string) => Promise<void>;
+    beforeAtomicTempWrite?: () => Promise<void>;
+    beforeAtomicRename?: () => Promise<void>;
+}
+export declare const defaultPersistenceHooks: PrReviewPersistenceHooks;
+/**
+ * Bind the persistence seam. The gate passes its `_test_exports` object (same
+ * reference) so property mutation by tests is read at call time.
+ */
+export declare function bindPrReviewPersistenceHooks(nextHooks: PrReviewPersistenceHooks): void;
+/** Structural minimum the CAS machinery relies on. */
+export interface PrWorkflowPersistedStateBase {
+    schemaVersion: number;
+    revision: number;
+    sessionID: string;
+    workflowInstanceId?: string;
+}
+export interface PrReviewStateCodec<S extends PrWorkflowPersistedStateBase> {
+    safeParse: (data: unknown) => {
+        success: true;
+        data: S;
+    } | {
+        success: false;
+        error: ZodError;
+    };
+    parse: (data: unknown) => S;
+}
+export declare function bindPrReviewStateCodec<S extends PrWorkflowPersistedStateBase>(nextCodec: PrReviewStateCodec<S>): void;
+export declare function ensurePrWorkflowSafeParentDirectory(directory: string, filePath: string): Promise<string>;
+export declare function writeAtomicJson(directory: string, filePath: string, value: unknown): Promise<void>;
+/**
+ * Write a PR-workflow artifact with the gate's Windows-safe atomic persistence
+ * contract. Checkout-preparation receipts must survive the same transient
+ * rename contention as canonical gate state.
+ */
+export declare function writePrWorkflowAtomicJson(directory: string, filePath: string, value: unknown): Promise<void>;
+export declare function readPrWorkflowGateStateFromDisk<S extends PrWorkflowPersistedStateBase>(directory: string, sessionID: string): Promise<S | null>;
+export declare function readPrWorkflowGateStateFileFromDisk<S extends PrWorkflowPersistedStateBase>(filePath: string, stateLabel: string): Promise<S | null>;
+/** Persist one CAS-checked state replacement while the session lock is held. */
+export declare function writeStateWhileLocked<S extends PrWorkflowPersistedStateBase>(directory: string, state: S, options?: {
+    replaceWorkflowInstanceId?: string;
+}): Promise<S>;
+/** A bounded checkout-mutation refusal that never permits unsafe late overlap. */
+export declare class PrWorkflowCheckoutMutationTimeoutError extends Error {
+    readonly phase: 'queue' | 'action';
+    readonly code: "PR_WORKFLOW_CHECKOUT_MUTATION_TIMEOUT";
+    readonly retryable: false;
+    constructor(phase: 'queue' | 'action');
+}
+/** Serialize project-wide checkout mutations before any session state lock. */
+export declare function withPrWorkflowCheckoutMutationLock<T>(directory: string, action: () => Promise<T>): Promise<T>;
+/** Serialize in-process mutations; the durable revision rejects stale callers. */
+export declare function withSessionStateMutation<T>(directory: string, sessionID: string, action: () => Promise<T>): Promise<T>;

package/dist/pr-review/reducer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PR-review transition authority (issue #2385).
+ *
+ * Pure `(state, event) -> { state, effects }` reducer over the closed
+ * `PrReviewEvent` union. Rule computation is delegated to the focused
+ * boundary modules (`circuit.ts`, `completion.ts` via its settlement inputs,
+ * `critic-routing.ts`, `lifecycle.ts`); this module owns transition
+ * composition and the explicit rejection of every invalid transition class
+ * named by issue #2385:
+ *
+ * - observer deadline / client absence → terminal child failure
+ * - raw transcript / parser failure → provider circuit signal
+ * - one lane → multiple circuit samples (delegated to circuit.ts's
+ *   distinct-`(generation, batch, lane)` scan; asserted by property tests)
+ * - unresolved/live lane → terminal coverage report
+ * - partial/no coverage → approval
+ * - ordinary MEDIUM → critic without typed high-impact/vulnerability evidence
+ *   (enforced where critic inventory is composed, via critic-routing.ts)
+ * - stale/foreign authorization → reviewer or publication access
+ * - late old-generation result → current-state mutation
+ * - structured receipt → downgrade by later transcript parsing
+ *
+ * The owning gate and `dispatch-lanes` are orchestration adapters: they build
+ * events from real I/O, apply the returned state, and map typed rejections to
+ * the operator-facing BLOCKED messages. Effects are the transition's OUTPUT
+ * CONTRACT — every effect kind maps to an executor that exists in production
+ * (see `PrReviewEffect` in types.ts): the gate executes `persist_state`
+ * through the persistence CAS write; `settle_delegation` describes the
+ * delegation settlement the dispatch/collect adapters perform through
+ * `pending-delegations.ts`; `emit_diagnostic` describes the collect
+ * observer's bounded diagnostics channel; `block_dispatch` describes the
+ * circuit-open admission refusal. No effect kind is emitted without a real
+ * executor (reviewer finding 1, issue #2385 Phase 8b).
+ *
+ * Probe outcomes other than an admission rollback are processed by the
+ * machine on the NEXT staged admission: the gate feeds the recorded probe's
+ * observation into `advancePrReviewCircuit` (`probeObservationForCircuit`),
+ * which is the design's single advance-per-admission cadence.
+ */
+import type { PrReviewEffect, PrReviewEvent, PrReviewTransitionRejection, PrReviewWorkflowState } from './types.js';
+export type PrReviewReduceResult = {
+    status: 'applied';
+    state: PrReviewWorkflowState;
+    effects: PrReviewEffect[];
+} | {
+    status: 'rejected';
+    state: PrReviewWorkflowState;
+    rejection: PrReviewTransitionRejection;
+};
+/**
+ * The transition authority. Pure: every I/O input arrives on the event; every
+ * write leaves as an effect. The state is never mutated in place.
+ */
+export declare function reducePrReviewEvent(state: PrReviewWorkflowState, event: PrReviewEvent): PrReviewReduceResult;