@kontourai/survey 3.0.0 → 4.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 { 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) {
@@ -353,64 +348,74 @@ 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}`;

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[];