@kontourai/survey 3.0.0 → 5.0.0

package/dist/src/mcp/review-mcp.js

@@ -1,10 +1,11 @@
-import { readFile, writeFile, rename } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
-import { buildReviewSessionEvents, currentReviewItem, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
+import { buildReviewSessionEvents, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { appendReviewSessionEvents, readReviewSessionFile, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 const SESSION_NAME = "mcp-review-session";
 const UI_RESOURCE_URI_META_KEY = "ui/resourceUri";
 const UI_CAPABILITY_EXTENSION = "io.modelcontextprotocol/ui";
@@ -19,13 +20,7 @@ const MCP_DECISION_MAP = {
     "could-not-confirm": "could-not-confirm",
 };
 async function readSessionFile(path) {
-    const raw = await readFile(path, "utf8");
-    return JSON.parse(raw);
-}
-async function writeSessionFileAtomic(path, content) {
-    const tmp = `${path}.tmp`;
-    await writeFile(tmp, JSON.stringify(content, null, 2), "utf8");
-    await rename(tmp, path);
+    return readReviewSessionFile(path);
 }
 // ---- Queue helpers -------------------------------------------------------
 function queueSummaryText(snapshot, events) {
@@ -58,7 +53,7 @@ function itemDetailText(item, snapshot, events) {
     const decision = current.decisionsByItemName[item.metadata.name];
     const note = current.notesByItemName[item.metadata.name];
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
-    const proposedCandidate = item.spec.candidates.find((c) => c.role === "proposed");
+    const proposedCandidates = item.spec.candidates.filter((c) => c.role === "proposed");
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "unknown";
     const lines = [
@@ -74,10 +69,15 @@ function itemDetailText(item, snapshot, events) {
         `  source: ${currentCandidate?.source?.sourceRef ?? "none"}`,
         ...(currentCandidate?.locator?.excerpt ? [`  excerpt: ${currentCandidate.locator.excerpt}`] : []),
         ``,
-        `Proposed value: ${valueStr(proposedCandidate?.value ?? "(none)")}`,
-        `  confidence: ${confStr(proposedCandidate?.extraction?.confidence ?? proposedCandidate?.confidence)}`,
-        `  source: ${proposedCandidate?.source?.sourceRef ?? "none"}`,
-        ...(proposedCandidate?.locator?.excerpt ? [`  excerpt: ${proposedCandidate.locator.excerpt}`] : []),
+        ...(proposedCandidates.length > 1
+            ? [`Conflict: ${proposedCandidates.length} proposed values. Accept is refused; reject them all or use could-not-confirm with a reason.`]
+            : []),
+        ...(proposedCandidates.length === 0 ? [`Proposed value: (none)`] : proposedCandidates.flatMap((candidate) => [
+            `Proposed value: ${valueStr(candidate.value)}`,
+            `  confidence: ${confStr(candidate.extraction?.confidence ?? candidate.confidence)}`,
+            `  source: ${candidate.source?.sourceRef ?? "none"}`,
+            ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
+        ])),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
@@ -104,19 +104,32 @@ function buildReviewCardHtml(item, snapshot, events) {
     const total = current.items.length;
     const resolved = total - summary.unresolved;
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
-    const proposedCandidate = item.spec.candidates.find((c) => c.role === "proposed");
+    const proposedCandidates = item.spec.candidates.filter((c) => c.role === "proposed");
+    // Several proposed values are a conflict: every value is shown, and accept
+    // (which names a role, not a value) is not offered.
+    const conflict = proposedCandidates.length > 1;
     const decision = current.decisionsByItemName[item.metadata.name];
     const status = deriveQueueRowStatus(item, current);
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v, null, 2);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "—";
     const currentValue = valueStr(currentCandidate?.value ?? "—");
-    const proposedValue = valueStr(proposedCandidate?.value ?? "—");
     const currentConf = confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
-    const proposedConf = confStr(proposedCandidate?.extraction?.confidence ?? proposedCandidate?.confidence);
     const currentSource = currentCandidate?.source?.sourceRef ?? "—";
-    const proposedSource = proposedCandidate?.source?.sourceRef ?? "—";
     const currentExcerpt = currentCandidate?.locator?.excerpt ?? "";
-    const proposedExcerpt = proposedCandidate?.locator?.excerpt ?? "";
+    const proposedCard = (candidate, label) => {
+        const value = valueStr(candidate?.value ?? "—");
+        const excerpt = candidate?.locator?.excerpt ?? "";
+        return `<div class="card is-proposed">
+    <div class="card-label">${escapeHtml(label)}</div>
+    <div class="value">${value.includes("\n") ? `<pre>${escapeHtml(value)}</pre>` : escapeHtml(value)}</div>
+    <div class="conf">confidence ${confStr(candidate?.extraction?.confidence ?? candidate?.confidence)}</div>
+    <div class="source-ref">${escapeHtml(candidate?.source?.sourceRef ?? "—")}</div>
+    ${excerpt ? `<div class="excerpt">${escapeHtml(excerpt)}</div>` : ""}
+  </div>`;
+    };
+    const proposedCards = conflict
+        ? proposedCandidates.map((candidate, index) => proposedCard(candidate, `Proposed ${index + 1} of ${proposedCandidates.length}`)).join("\n  ")
+        : proposedCard(proposedCandidates[0], "Proposed");
     const itemNameJson = escapeJsonInHtml(item.metadata.name);
     const decisionBadge = decision
         ? `<span class="badge badge-${decision === "accept-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(workbenchDecisionDefinitions[decision].label)}</span>`
@@ -205,6 +218,7 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 <div class="meta">
   <span>${escapeHtml(item.metadata.name)}</span>
   ${decisionBadge}
+  ${conflict ? `<span class="badge badge-hold" id="conflict-badge">Conflict: ${proposedCandidates.length} values</span>` : ""}
   <span class="progress">${resolved}/${total} resolved</span>
 </div>
 
@@ -216,14 +230,9 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
     <div class="source-ref">${escapeHtml(currentSource)}</div>
     ${currentExcerpt ? `<div class="excerpt">${escapeHtml(currentExcerpt)}</div>` : ""}
   </div>
-  <div class="card is-proposed">
-    <div class="card-label">Proposed</div>
-    <div class="value">${proposedValue.includes("\n") ? `<pre>${escapeHtml(proposedValue)}</pre>` : escapeHtml(proposedValue)}</div>
-    <div class="conf">confidence ${proposedConf}</div>
-    <div class="source-ref">${escapeHtml(proposedSource)}</div>
-    ${proposedExcerpt ? `<div class="excerpt">${escapeHtml(proposedExcerpt)}</div>` : ""}
-  </div>
+  ${proposedCards}
 </div>
+${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length} different values were proposed. This card cannot choose one of them yet: reject them all, or use Could not confirm with a reason.</p>` : ""}
 
 <div class="divider"></div>
 
@@ -231,9 +240,9 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 <textarea class="note-input" id="note" placeholder="Add a rationale for this decision...">${escapeHtml(current.notesByItemName[item.metadata.name] ?? "")}</textarea>
 
 <div class="btn-row">
-  <button class="btn btn-accept${decision === "accept-proposed" ? " active" : ""}" id="btn-accept">Accept proposed</button>
-  <button class="btn btn-hold${decision === "keep-current" ? " active" : ""}" id="btn-hold">Hold / Keep current</button>
-  <button class="btn btn-reject${decision === "reject-proposed" ? " active" : ""}" id="btn-reject">Reject proposed</button>
+  ${conflict ? "" : `<button class="btn btn-accept${decision === "accept-proposed" ? " active" : ""}" id="btn-accept">Accept proposed</button>`}
+  ${currentCandidate ? `<button class="btn btn-hold${decision === "keep-current" ? " active" : ""}" id="btn-hold">Hold / Keep current</button>` : ""}
+  <button class="btn btn-reject${decision === "reject-proposed" ? " active" : ""}" id="btn-reject">${conflict ? "Reject all values" : "Reject proposed"}</button>
   <button class="btn btn-unconfirmed${decision === "could-not-confirm" ? " active" : ""}" id="btn-unconfirmed">Could not confirm</button>
 </div>
 <div class="feedback" id="feedback"></div>
@@ -264,8 +273,10 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
     return true;
   }
 
-  document.getElementById('btn-accept').addEventListener('click', function () { postDecision('accept'); document.getElementById('feedback').textContent = 'Submitting accept…'; });
-  document.getElementById('btn-hold').addEventListener('click', function () { postDecision('hold'); document.getElementById('feedback').textContent = 'Submitting hold…'; });
+  var acceptButton = document.getElementById('btn-accept');
+  if (acceptButton) acceptButton.addEventListener('click', function () { postDecision('accept'); document.getElementById('feedback').textContent = 'Submitting accept…'; });
+  var holdButton = document.getElementById('btn-hold');
+  if (holdButton) holdButton.addEventListener('click', function () { postDecision('hold'); document.getElementById('feedback').textContent = 'Submitting hold…'; });
   document.getElementById('btn-reject').addEventListener('click', function () { postDecision('reject'); document.getElementById('feedback').textContent = 'Submitting reject…'; });
   document.getElementById('btn-unconfirmed').addEventListener('click', function () { if (postDecision('could-not-confirm')) document.getElementById('feedback').textContent = 'Submitting could not confirm…'; });
 
@@ -353,72 +364,83 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
     if (wbDecision === "could-not-confirm" && !note?.trim()) {
         throw new DomainError("survey_review_decide requires a non-empty reason for could-not-confirm");
     }
-    const file = await readSessionFile(options.sessionPath);
-    const { snapshot, events } = file;
-    const current = currentSessionState(snapshot, events);
-    const item = current.items.find((i) => i.metadata.name === itemName);
-    if (!item) {
-        throw new DomainError(`Unknown review item: ${itemName}`);
-    }
-    const existingDecision = current.decisionsByItemName[item.metadata.name];
-    if (existingDecision) {
-        throw new DomainError(`Item ${itemName} already has a decision: ${existingDecision}. Use a new session to re-decide.`);
-    }
-    // Build the updated session state with the decision
-    const sessionWithDecision = {
-        ...current,
-        decisionsByItemName: {
-            ...current.decisionsByItemName,
-            [itemName]: wbDecision,
-        },
-        ...(note !== undefined
-            ? {
-                notesByItemName: {
-                    ...current.notesByItemName,
-                    [itemName]: note,
-                },
-            }
-            : {}),
-        ...(attemptEvidenceIds?.length
-            ? {
-                attemptEvidenceIdsByItemName: {
-                    ...current.attemptEvidenceIdsByItemName,
-                    [itemName]: [...attemptEvidenceIds],
-                },
-            }
-            : {}),
-    };
-    // Use the server session APIs for apply-path validation
-    const record = createServerReviewSessionRecord({
-        sessionName: SESSION_NAME,
-        snapshot,
-        eventCount: events.length,
-        updatedAt: new Date(),
-    });
-    const newEvents = buildReviewSessionEvents(sessionWithDecision, SESSION_NAME);
-    const applyResult = deriveServerReviewSessionApplyResult({
-        record,
-        events: newEvents,
-        requiredResolvedItems: "none",
+    // Read, validate and write inside the shared session lock so a concurrent
+    // decide or console save cannot interleave and drop this decision (#281).
+    const { snapshot, sessionWithDecision, newEvents } = await updateReviewSessionFile(options.sessionPath, (file) => {
+        const { snapshot, events } = file;
+        const current = currentSessionState(snapshot, events);
+        const item = current.items.find((i) => i.metadata.name === itemName);
+        if (!item) {
+            throw new DomainError(`Unknown review item: ${itemName}`);
+        }
+        const existingDecision = current.decisionsByItemName[item.metadata.name];
+        if (existingDecision) {
+            throw new DomainError(`Item ${itemName} already has a decision: ${existingDecision}. Use a new session to re-decide.`);
+        }
+        // Build the updated session state with the decision
+        const sessionWithDecision = {
+            ...current,
+            decisionsByItemName: {
+                ...current.decisionsByItemName,
+                [itemName]: wbDecision,
+            },
+            ...(note !== undefined
+                ? {
+                    notesByItemName: {
+                        ...current.notesByItemName,
+                        [itemName]: note,
+                    },
+                }
+                : {}),
+            ...(attemptEvidenceIds?.length
+                ? {
+                    attemptEvidenceIdsByItemName: {
+                        ...current.attemptEvidenceIdsByItemName,
+                        [itemName]: [...attemptEvidenceIds],
+                    },
+                }
+                : {}),
+        };
+        // Append only this decision's events (its note, then the decision) to the
+        // stored log. Regenerating the whole log from state would erase earlier
+        // reversals and note changes recorded by the console (#281).
+        const sessionName = storedReviewSessionName(file, SESSION_NAME);
+        const decisionEvents = buildReviewSessionEvents(sessionWithDecision, sessionName).filter((event) => event.spec.reviewItemName === itemName
+            && (event.spec.eventType === "decision-changed"
+                || event.spec.eventType === "decision-submitted"
+                || (event.spec.eventType === "note-changed" && note !== undefined)));
+        const newEvents = appendReviewSessionEvents(file, decisionEvents);
+        // Use the server session APIs for apply-path validation
+        const record = createServerReviewSessionRecord({
+            sessionName,
+            snapshot,
+            eventCount: events.length,
+            updatedAt: new Date(),
+        });
+        const applyResult = deriveServerReviewSessionApplyResult({
+            record,
+            events: newEvents,
+            requiredResolvedItems: "none",
+        });
+        if (!applyResult.ok) {
+            throw new DomainError(`Decision validation failed: ${applyResult.issues.map((issue) => "message" in issue ? issue.message : String(issue)).join("; ")}`);
+        }
+        const updatedFile = {
+            session: file.session,
+            snapshot,
+            events: newEvents,
+        };
+        return { next: updatedFile, result: { snapshot, sessionWithDecision, newEvents } };
     });
-    if (!applyResult.ok) {
-        throw new DomainError(`Decision validation failed: ${applyResult.issues.map((issue) => "message" in issue ? issue.message : String(issue)).join("; ")}`);
-    }
-    // Persist atomically
-    const updatedFile = {
-        session: file.session,
-        snapshot,
-        events: newEvents,
-    };
-    await writeSessionFileAtomic(options.sessionPath, updatedFile);
     // Summarize the result
     const updatedItem = sessionWithDecision.items.find((i) => i.metadata.name === itemName);
     const itemText = updatedItem ? itemDetailText(updatedItem, snapshot, newEvents) : `Item: ${itemName}`;
     const remainingText = queueSummaryText(snapshot, newEvents);
     const definition = workbenchDecisionDefinitions[wbDecision];
+    const conflictRejected = wbDecision === "reject-proposed" && updatedItem !== undefined && decisionSelectsNoCandidate(updatedItem, wbDecision);
     const text = [
-        `Decision recorded: ${definition.label}`,
-        `Effect: ${definition.effect}`,
+        `Decision recorded: ${conflictRejected ? "Reject all values" : definition.label}`,
+        `Effect: ${conflictRejected ? "Every proposed value is rejected; none becomes the claim's value." : definition.effect}`,
         "",
         itemText,
         "",

package/dist/src/producer-profile.d.ts

@@ -129,6 +129,20 @@ export declare const AUTO_ACCEPT_WITHIN_COMFORT_ZONE: true;
  * candidate's evidence gets passed into that decision.
  */
 export declare function meetsAutoAcceptThreshold(confidence: number, minConfidence: number): boolean;
+/**
+ * Refuse an auto-accept policy threshold that cannot express a comfort zone:
+ * `minConfidence` must be a finite number in (0, 1]. A threshold of 0 (or
+ * below) would accept every proposal, and one above 1 accepts only
+ * out-of-range self-reports, so either makes `withinComfortZone: true` a
+ * false statement. Throws `RangeError`.
+ */
+export declare function assertValidAutoAcceptThreshold(minConfidence: number): void;
+/**
+ * Whether a proposal's self-reported confidence is usable by the auto-accept
+ * gate: a finite number in [0, 1]. Anything else (7, -5, NaN) is never
+ * auto-accepted; the proposal stays in human review.
+ */
+export declare function isAutoAcceptConfidenceInRange(confidence: number): boolean;
 /**
  * The accepted-candidate-shaped evidence `evaluateAutoAccept` decides over.
  * Deliberately narrow: only the fields the auto-accept policy itself reads,
@@ -157,6 +171,18 @@ export interface AutoAcceptEvidence {
      */
     proposedAt?: string;
 }
+/**
+ * A proposal the auto-accept policy refused because its self-reported
+ * confidence is not a finite number in [0, 1]. The proposal is left for human
+ * review; the warning records why it was not auto-accepted.
+ */
+export interface AutoAcceptWarning {
+    code: "confidence-out-of-range";
+    /** The refused proposal's id. */
+    proposalId: string;
+    /** The out-of-range confidence exactly as reported. */
+    confidence: number;
+}
 /** The auto-accept policy `evaluateAutoAccept` gates against. */
 export interface AutoAcceptPolicy {
     /** Minimum confidence (inclusive) a proposal must clear to auto-accept. */
@@ -164,8 +190,17 @@ export interface AutoAcceptPolicy {
 }
 /** The unified auto-accept decision `evaluateAutoAccept` returns. */
 export interface AutoAcceptDecision {
-    /** `true` iff there is no conflict and `evidence.confidence` clears `policy.minConfidence`. */
+    /**
+     * `true` iff there is no conflict, `evidence.confidence` is a finite number
+     * in [0, 1], and it clears `policy.minConfidence`.
+     */
     accepted: boolean;
+    /**
+     * Set when the proposal was refused because its self-reported confidence
+     * is not a finite number in [0, 1]. The proposal is not auto-accepted and
+     * stays in human review.
+     */
+    warning?: "confidence-out-of-range";
     /** The confidence value that was gated on (== `evidence.confidence`). */
     confidence: number;
     /** Composed rationale — always computed; callers only use it when `accepted`. */
@@ -192,7 +227,11 @@ export interface AutoAcceptDecision {
  *    back to `fallbackTimestamp` (and reporting which source was used via
  *    `reviewedAtSource`) when a profile's evidence carries no timestamp of
  *    its own.
- * 4. Always report `actor: AUTO_ACCEPT_ACTOR` and
+ * 4. Refuse out-of-range inputs: throw `RangeError` unless
+ *    `policy.minConfidence` is a finite number in (0, 1], and never accept a
+ *    proposal whose confidence is not a finite number in [0, 1] (reported via
+ *    `warning`). This is what keeps `withinComfortZone: true` truthful.
+ * 5. Always report `actor: AUTO_ACCEPT_ACTOR` and
  *    `withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE` (ADR 0003 §4:
  *    auto-accept only ever yields "assumed" with the comfort-zone posture).
  *

package/dist/src/producer-profile.js

@@ -119,6 +119,26 @@ export const AUTO_ACCEPT_WITHIN_COMFORT_ZONE = true;
 export function meetsAutoAcceptThreshold(confidence, minConfidence) {
     return confidence >= minConfidence;
 }
+/**
+ * Refuse an auto-accept policy threshold that cannot express a comfort zone:
+ * `minConfidence` must be a finite number in (0, 1]. A threshold of 0 (or
+ * below) would accept every proposal, and one above 1 accepts only
+ * out-of-range self-reports, so either makes `withinComfortZone: true` a
+ * false statement. Throws `RangeError`.
+ */
+export function assertValidAutoAcceptThreshold(minConfidence) {
+    if (typeof minConfidence !== "number" || !Number.isFinite(minConfidence) || minConfidence <= 0 || minConfidence > 1) {
+        throw new RangeError(`Auto-accept minConfidence must be a finite number in (0, 1]; received ${String(minConfidence)}.`);
+    }
+}
+/**
+ * Whether a proposal's self-reported confidence is usable by the auto-accept
+ * gate: a finite number in [0, 1]. Anything else (7, -5, NaN) is never
+ * auto-accepted; the proposal stays in human review.
+ */
+export function isAutoAcceptConfidenceInRange(confidence) {
+    return typeof confidence === "number" && Number.isFinite(confidence) && confidence >= 0 && confidence <= 1;
+}
 /**
  * The one core auto-accept policy decision every Producer Profile delegates
  * to, per the owner-accepted semantics recorded in
@@ -132,7 +152,11 @@ export function meetsAutoAcceptThreshold(confidence, minConfidence) {
  *    back to `fallbackTimestamp` (and reporting which source was used via
  *    `reviewedAtSource`) when a profile's evidence carries no timestamp of
  *    its own.
- * 4. Always report `actor: AUTO_ACCEPT_ACTOR` and
+ * 4. Refuse out-of-range inputs: throw `RangeError` unless
+ *    `policy.minConfidence` is a finite number in (0, 1], and never accept a
+ *    proposal whose confidence is not a finite number in [0, 1] (reported via
+ *    `warning`). This is what keeps `withinComfortZone: true` truthful.
+ * 5. Always report `actor: AUTO_ACCEPT_ACTOR` and
  *    `withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE` (ADR 0003 §4:
  *    auto-accept only ever yields "assumed" with the comfort-zone posture).
  *
@@ -142,7 +166,9 @@ export function meetsAutoAcceptThreshold(confidence, minConfidence) {
  * inline `ReviewOutcome`) from this decision's fields.
  */
 export function evaluateAutoAccept(evidence, hasConflict, policy, fallbackTimestamp) {
-    const accepted = !hasConflict && meetsAutoAcceptThreshold(evidence.confidence, policy.minConfidence);
+    assertValidAutoAcceptThreshold(policy.minConfidence);
+    const inRange = isAutoAcceptConfidenceInRange(evidence.confidence);
+    const accepted = !hasConflict && inRange && meetsAutoAcceptThreshold(evidence.confidence, policy.minConfidence);
     const rationale = `Auto-accepted: confidence ${evidence.confidence} >= threshold ${policy.minConfidence}.` +
         (evidence.rationale !== undefined ? ` ${evidence.rationale}` : "");
     const reviewedAt = evidence.proposedAt ?? fallbackTimestamp;
@@ -154,5 +180,6 @@ export function evaluateAutoAccept(evidence, hasConflict, policy, fallbackTimest
         reviewedAtSource: evidence.proposedAt !== undefined ? "proposedAt" : "fallback",
         actor: AUTO_ACCEPT_ACTOR,
         withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
+        ...(inRange ? {} : { warning: "confidence-out-of-range" }),
     };
 }

package/dist/src/review-session-file.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared session-file persistence for the local review writers
+ * (`survey-review-console` and `survey-review-mcp`).
+ *
+ * Every write goes through {@link updateReviewSessionFile}, which takes one
+ * exclusive lock file next to the session, re-reads the session inside the
+ * lock, applies the caller's change, writes a uniquely named temp file and
+ * renames it into place. Both writers must use this helper: a lock that only
+ * one of them takes still races with the other (kontourai/survey#281).
+ */
+import type { ReviewQueueSessionState } from "./review-workbench/review-queue-session.js";
+import type { ReviewSessionEvent } from "./review-resource.js";
+export interface ReviewSessionFileContent {
+    readonly session: unknown;
+    readonly snapshot: ReviewQueueSessionState;
+    readonly events: readonly ReviewSessionEvent[];
+}
+export interface ReviewSessionFileLockOptions {
+    /** How long to wait for a busy lock before failing. Defaults to 10s. */
+    readonly timeoutMs?: number;
+    /** A lock older than this is treated as abandoned. Defaults to 30s. */
+    readonly staleMs?: number;
+}
+export declare class ReviewSessionFileLockTimeoutError extends Error {
+    constructor(lockPath: string, timeoutMs: number);
+}
+export declare function reviewSessionLockPath(sessionPath: string): string;
+export declare function readReviewSessionFile<T extends ReviewSessionFileContent = ReviewSessionFileContent>(sessionPath: string): Promise<T>;
+/**
+ * Opaque revision token for an event log: a digest of its serialized form.
+ * An event count is not enough, because the log is regenerated from session
+ * state and a changed decision keeps the count while changing the content.
+ */
+export declare function reviewSessionRevision(events: readonly ReviewSessionEvent[]): string;
+/**
+ * Acquire the exclusive session lock. Resolves with a release function.
+ * Exported so tests can hold the lock and observe that writers wait for it.
+ */
+export declare function acquireReviewSessionFileLock(sessionPath: string, options?: ReviewSessionFileLockOptions): Promise<() => Promise<void>>;
+/**
+ * Locked read-modify-write of a session file. `mutate` receives the content
+ * read inside the lock and returns the content to write, or `undefined` to
+ * leave the file untouched. Whatever `mutate` throws propagates after the lock
+ * is released.
+ */
+export declare function updateReviewSessionFile<T extends ReviewSessionFileContent, R>(sessionPath: string, mutate: (current: T) => Promise<{
+    readonly next?: T;
+    readonly result: R;
+}> | {
+    readonly next?: T;
+    readonly result: R;
+}, options?: ReviewSessionFileLockOptions): Promise<R>;
+/**
+ * The session name the stored log is recorded under: the name its events
+ * already carry, else the stored ReviewSession's name, else `fallback` (the
+ * writer's own default). Appended events are renamed into it so one log never mixes names.
+ */
+export declare function storedReviewSessionName(content: ReviewSessionFileContent, fallback?: string): string;
+/**
+ * Append events to the stored log, renumbering them after the stored events
+ * and renaming them into the stored session. The stored log is never
+ * rewritten, so decision reversals and note changes stay on record.
+ */
+export declare function appendReviewSessionEvents(content: ReviewSessionFileContent, appended: readonly ReviewSessionEvent[]): ReviewSessionEvent[];