@kontourai/survey 2.5.0 → 4.0.0

package/dist/src/console/review-console-server.js

@@ -5,18 +5,20 @@
  * Routes:
  *   GET  /              HTML shell that mounts the workbench
  *   GET  /api/session   Current session state (snapshot + replayed events)
- *   POST /api/events    Append review session events (same contract as MCP server)
+ *   POST /api/events    Append review session events to the stored log (same
+ *                       validation as MCP server), compare-and-swap on the
+ *                       revision the client last read
  *   GET  /api/stream    SSE stream: emits "update" events when the session file changes
  *   GET  /api/health    Health check
  *   GET  /dist/*        Compiled assets served from the dist tree (traversal-safe)
  */
 import { createServer } from "node:http";
 import { watch } from "node:fs";
-import { readFile as readFileAsync, writeFile as writeFileAsync, rename as renameAsync } from "node:fs/promises";
+import { readFile as readFileAsync } from "node:fs/promises";
 import { resolve, join, dirname, extname, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultReviewSessionName, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { appendReviewSessionEvents, readReviewSessionFile, reviewSessionRevision, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -55,13 +57,7 @@ function distRoot() {
 // Session file helpers
 // ---------------------------------------------------------------------------
 async function readSession(path) {
-    const raw = await readFileAsync(path, "utf8");
-    return JSON.parse(raw);
-}
-async function writeSessionAtomic(path, content) {
-    const tmp = `${path}.tmp`;
-    await writeFileAsync(tmp, JSON.stringify(content, null, 2), "utf8");
-    await renameAsync(tmp, path);
+    return readReviewSessionFile(path);
 }
 // ---------------------------------------------------------------------------
 // SSE broadcaster
@@ -271,6 +267,14 @@ body {
 .connection-dot.disconnected {
   background: var(--k-negative, #ff6f6f);
 }
+.console-save-status {
+  padding: 8px 16px;
+  border-bottom: 1px solid var(--k-negative, #ff6f6f);
+  background: var(--k-panel-raised, #16202d);
+  color: var(--k-text, #eef3f8);
+  font-size: 13px;
+}
+.console-save-status[hidden] { display: none; }
 #review-workbench {
   flex: 1;
   min-height: 0;
@@ -309,31 +313,92 @@ body {
     </button>
   </div>
 </header>
+<div id="console-save-status" class="console-save-status" role="alert" data-testid="console-save-status" hidden></div>
 <main id="review-workbench" class="workbench survey-workbench-embed" data-testid="review-workbench"></main>
 <script type="module">
 import { mountReviewWorkbench, replayReviewSessionEvents, defaultReviewSessionName, buildReviewSessionEvents } from "${workbenchJsPath}";
 
 // ---- persistence adapter: POST events to /api/events ----
-function createConsoleEventStore() {
-  let _events = [];
+// One store per mount, bound to the server revision the mount was built from.
+// Each save sends only the workbench events of this mount that are not stored
+// yet; the server appends them to the stored log, so reversals and note
+// changes stay on record and decisions another writer stored (for example the
+// MCP server) are kept. Saves are serialized so each one carries the revision
+// the previous save produced. A save the server refuses (409 conflict or any
+// other failure) is never kept as local truth: the console re-fetches the
+// stored session, re-mounts from it and tells the reviewer once.
+let saveChain = Promise.resolve();
+
+function showSaveStatus(message) {
+  const el = document.getElementById("console-save-status");
+  if (!el) return;
+  if (message) {
+    el.textContent = message;
+    el.hidden = false;
+  } else {
+    el.textContent = "";
+    el.hidden = true;
+  }
+}
+
+function createConsoleEventStore(baseRevision) {
+  let revision = baseRevision;
+  // Local events of this mount already appended to the stored log.
+  let persistedCount = 0;
+  // Set once a save from this mount is refused. Saves still queued from this
+  // mount were built on the view the server just refused, and the page has
+  // re-mounted from the stored session and told the reviewer: drop them
+  // instead of reporting the same conflict again.
+  let abandoned = false;
+
+  async function refused(message) {
+    abandoned = true;
+    showSaveStatus(message);
+    await fetchAndMount();
+  }
+
+  async function persist(localEvents) {
+    if (abandoned) return;
+    const pending = localEvents.slice(persistedCount);
+    if (pending.length === 0) return;
+    let res;
+    try {
+      res = await fetch("/api/events", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: pending, baseRevision: revision }),
+      });
+    } catch (err) {
+      console.error("[console] Failed to persist events:", err);
+      await refused("Your last change was not saved: the console could not reach the server.");
+      return;
+    }
+    if (res.ok) {
+      const body = await res.json().catch(() => ({}));
+      if (typeof body.revision === "string") revision = body.revision;
+      persistedCount = localEvents.length;
+      showSaveStatus("");
+      return;
+    }
+    if (res.status === 409) {
+      await refused("Your last change was not saved because the session changed (another tab, reviewer or agent wrote to it). The console reloaded the current session.");
+    } else {
+      const body = await res.json().catch(() => ({}));
+      await refused("Your last change was not saved (HTTP " + res.status + (body.error ? ": " + body.error : "") + "). The console reloaded the stored session.");
+    }
+  }
+
   return {
-    load: () => _events.length > 0 ? [..._events] : undefined,
-    save: async (_session, events) => {
-      _events = [...events];
-      try {
-        await fetch("/api/events", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ events }),
-        });
-      } catch (err) {
-        console.error("[console] Failed to persist events:", err);
-      }
+    // The mount state is already replayed from the stored log.
+    load: () => undefined,
+    save: (_session, events) => {
+      const localEvents = [...events];
+      saveChain = saveChain.then(() => persist(localEvents));
+      return saveChain;
     },
   };
 }
 
-const eventStore = createConsoleEventStore();
 let activeItemName = null;
 
 async function fetchAndMount() {
@@ -341,7 +406,7 @@ async function fetchAndMount() {
     const res = await fetch("/api/session");
     if (!res.ok) throw new Error("Session fetch failed: " + res.status);
     const data = await res.json();
-    const { snapshot, events } = data;
+    const { snapshot, events, revision } = data;
     const state = events && events.length > 0
       ? replayReviewSessionEvents(snapshot, events)
       : snapshot;
@@ -354,7 +419,7 @@ async function fetchAndMount() {
     const root = document.getElementById("review-workbench");
     if (!root) return;
 
-    mountReviewWorkbench(root, state, { eventStore });
+    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision) });
   } catch (err) {
     console.error("[console] Mount error:", err);
   }
@@ -451,6 +516,49 @@ async function readJsonBody(req) {
     return parsed;
 }
 // ---------------------------------------------------------------------------
+// Request guards (kontourai/survey#281)
+// ---------------------------------------------------------------------------
+function hostnameOf(hostHeader) {
+    try {
+        return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server binds to loopback only, but a browser page on another site can
+ * still reach it through DNS rebinding (Host is the attacker's name) or a
+ * cross-origin "simple request" (text/plain body, foreign Origin). Each guard
+ * returns an error message, or undefined when the request passes.
+ */
+function hostGuard(req) {
+    const host = req.headers.host;
+    const hostname = host ? hostnameOf(host) : undefined;
+    return hostname && LOOPBACK_HOSTS.has(hostname) ? undefined : "Host must be a loopback address";
+}
+function originGuard(req, port) {
+    const origin = req.headers.origin;
+    if (origin === undefined)
+        return undefined;
+    try {
+        const parsed = new URL(origin);
+        const originPort = parsed.port === "" ? "80" : parsed.port;
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+        if (parsed.protocol === "http:" && LOOPBACK_HOSTS.has(hostname) && originPort === String(port)) {
+            return undefined;
+        }
+    }
+    catch {
+        // Unparseable (for example "null"): refuse below.
+    }
+    return "Cross-origin writes are not allowed";
+}
+function contentTypeGuard(req) {
+    const mediaType = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+    return mediaType === "application/json" ? undefined : "Content-Type must be application/json";
+}
+// ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 export async function startReviewConsoleServer(options) {
@@ -464,8 +572,14 @@ export async function startReviewConsoleServer(options) {
     const stopWatcher = watchSessionFile(sessionPath, () => {
         broadcaster.broadcast("update", JSON.stringify({ ts: Date.now() }));
     });
+    let listenPort = 0;
     const server = createServer(async (req, res) => {
         try {
+            const hostError = hostGuard(req);
+            if (hostError) {
+                sendJson(res, 403, { error: hostError });
+                return;
+            }
             const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
             const pathname = url.pathname;
             // ---- Static dist assets ----
@@ -492,42 +606,80 @@ export async function startReviewConsoleServer(options) {
                     session: content.session,
                     snapshot: content.snapshot,
                     events: content.events,
+                    revision: reviewSessionRevision(content.events),
                     state: currentSessionState(content.snapshot, content.events),
                 });
                 return;
             }
             // ---- Events write (append) ----
             if (pathname === "/api/events" && req.method === "POST") {
+                const originError = originGuard(req, listenPort);
+                if (originError) {
+                    sendJson(res, 403, { error: originError });
+                    return;
+                }
+                const contentTypeError = contentTypeGuard(req);
+                if (contentTypeError) {
+                    sendJson(res, 415, { error: contentTypeError });
+                    return;
+                }
                 const body = await readJsonBody(req);
                 const incomingEvents = body.events;
+                const baseRevision = body.baseRevision;
                 if (!Array.isArray(incomingEvents)) {
                     sendJson(res, 400, { error: "events must be an array" });
                     return;
                 }
-                const content = await readSession(sessionPath);
-                const { snapshot, events: existingEvents } = content;
-                const record = createServerReviewSessionRecord({
-                    sessionName: defaultReviewSessionName,
-                    snapshot,
-                    eventCount: existingEvents.length,
-                    updatedAt: new Date(),
-                });
-                const applyResult = deriveServerReviewSessionApplyResult({
-                    record,
-                    events: incomingEvents,
-                    requiredResolvedItems: "none",
-                });
-                if (!applyResult.ok) {
-                    const issueMessages = applyResult.issues.map((issue) => "message" in issue ? issue.message : String(issue));
-                    sendJson(res, 422, { error: `Validation failed: ${issueMessages.join("; ")}` });
-                    return;
-                }
-                await writeSessionAtomic(sessionPath, {
-                    session: content.session,
-                    snapshot,
-                    events: incomingEvents,
+                const outcome = await updateReviewSessionFile(sessionPath, (content) => {
+                    const { snapshot, events: existingEvents } = content;
+                    const revision = reviewSessionRevision(existingEvents);
+                    // Compare-and-swap: the appended events express decisions made on
+                    // the reviewer's view of the log, so they are only safe to append
+                    // when that view is the log that is stored right now.
+                    if (typeof baseRevision !== "string") {
+                        return { result: { status: 428, body: { error: "baseRevision is required: send the revision from GET /api/session", revision, eventCount: existingEvents.length } } };
+                    }
+                    if (baseRevision !== revision) {
+                        return { result: { status: 409, body: { error: "Session changed since it was read; reload and retry", revision, eventCount: existingEvents.length } } };
+                    }
+                    if (incomingEvents.length === 0) {
+                        return { result: { status: 422, body: { error: "events must contain at least one event to append", revision, eventCount: existingEvents.length } } };
+                    }
+                    // Append, never replace: the stored log stays a complete record of
+                    // reviewer intent (reversals and note changes included).
+                    const nextEvents = appendReviewSessionEvents(content, incomingEvents);
+                    const record = createServerReviewSessionRecord({
+                        sessionName: storedReviewSessionName(content),
+                        snapshot,
+                        eventCount: existingEvents.length,
+                        updatedAt: new Date(),
+                    });
+                    let issueMessages;
+                    try {
+                        const applyResult = deriveServerReviewSessionApplyResult({
+                            record,
+                            events: nextEvents,
+                            requiredResolvedItems: "none",
+                        });
+                        issueMessages = applyResult.ok
+                            ? []
+                            : applyResult.issues.map((issue) => ("message" in issue ? issue.message : String(issue)));
+                    }
+                    catch (error) {
+                        issueMessages = [error instanceof Error ? error.message : String(error)];
+                    }
+                    if (issueMessages.length > 0) {
+                        return { result: { status: 422, body: { error: `Validation failed: ${issueMessages.join("; ")}` } } };
+                    }
+                    return {
+                        next: { session: content.session, snapshot, events: nextEvents },
+                        result: {
+                            status: 200,
+                            body: { ok: true, eventCount: nextEvents.length, revision: reviewSessionRevision(nextEvents) },
+                        },
+                    };
                 });
-                sendJson(res, 200, { ok: true, eventCount: incomingEvents.length });
+                sendJson(res, outcome.status, outcome.body);
                 return;
             }
             // ---- Health ----
@@ -558,6 +710,7 @@ export async function startReviewConsoleServer(options) {
     if (!address || typeof address === "string") {
         throw new Error("Unable to determine server address");
     }
+    listenPort = address.port;
     const normalizedHost = host === "::1" ? "[::1]" : host;
     const url = `http://${normalizedHost}:${address.port}/`;
     return {

package/dist/src/extraction-envelope.d.ts

@@ -17,6 +17,24 @@ export interface PortableExtractionOccurrence {
     hintUsed: boolean;
     ambiguous: boolean;
 }
+/** Which model produced one proposal, as the extractor recorded it for that proposal's own request. */
+export interface PortableExtractionProducedBy {
+    model: string;
+    modelSource: "provider-reported" | "configured";
+    /** Content-free digest of the provider request (`sha256:<hex>`). */
+    requestDigest: string;
+}
+/**
+ * Deterministic, versioned facts about how a proposal's value relates to the
+ * declared schema and to its own excerpt. Annotations only: Survey carries
+ * them to review and does not route or block on them.
+ */
+export interface PortableExtractionEvidenceMatch {
+    checkerVersion: string;
+    schema: "ok" | "type-mismatch" | "enum-mismatch" | "format-invalid";
+    valueInExcerpt: "match" | "mismatch" | "not-evaluated" | "not-applicable";
+    tokenBoundary?: boolean;
+}
 export interface PortableExtractionProposal {
     fieldPath: string;
     candidateValue: unknown;
@@ -31,6 +49,8 @@ export interface PortableExtractionProposal {
     inferenceType?: "explicit" | "inferred";
     valueType?: ReviewValueType;
     enumValues?: string[];
+    producedBy?: PortableExtractionProducedBy;
+    evidenceMatch?: PortableExtractionEvidenceMatch;
 }
 export type PortablePreparedArtifactState = {
     status: "available" | "unavailable" | "storage-error";
@@ -89,10 +109,12 @@ export interface PortableExtractionResultEnvelope {
             remainingChunks: number;
             tokenOvershoot?: number;
         };
+        /** `code` is the upstream error code, informational only; `kind` stays authoritative. */
         providerFailures?: Array<{
             provider: string;
             kind: "authentication" | "rate-limit" | "timeout" | "invalid-request" | "unavailable" | "unknown";
             retryable: boolean;
+            code?: string;
         }>;
         taskDigest?: string;
         exampleDigests?: string[];

package/dist/src/extraction-envelope.js

@@ -89,7 +89,9 @@ function buildReviewItem(record, proposal, index) {
             target: proposal.fieldPath,
             confidence: proposal.confidence,
             extractor: proposal.extractor,
-            ...(envelope.result.model ? { model: envelope.result.model } : {}),
+            // The proposal's own served model when recorded; in a multi-chunk run
+            // `result.model` names only the last chunk's model.
+            ...(proposal.producedBy ? { model: proposal.producedBy.model } : envelope.result.model ? { model: envelope.result.model } : {}),
         },
         claimTarget: target,
         producer: { "survey.kontourai.io/extraction-envelope": {
@@ -100,6 +102,8 @@ function buildReviewItem(record, proposal, index) {
                 ...(envelope.result.taskDigest ? { taskDigest: envelope.result.taskDigest } : {}),
                 ...(envelope.result.exampleDigests ? { exampleDigests: envelope.result.exampleDigests } : {}),
                 valueType: { type: valueType, origin: proposal.inferenceType ?? "inferred" },
+                ...(proposal.producedBy ? { producedBy: proposal.producedBy } : {}),
+                ...(proposal.evidenceMatch ? { evidenceMatch: proposal.evidenceMatch } : {}),
                 occurrence: proposal.provenance.occurrence,
                 attempt: { id: envelope.result.runId, providerCalls: envelope.result.providerCalls },
                 ...(envelope.result.warningClassifications ? { warnings: envelope.result.warningClassifications } : {}),
@@ -228,7 +232,7 @@ function validateEnvelope(input) {
 }
 function validateProposal(input, index, contentLength) {
     const p = obj(input, `proposal[${index}]`);
-    exact(p, ["fieldPath", "candidateValue", "confidence", "provenance", "extractor"], `proposal[${index}]`, ["pathIndices", "inferenceType", "valueType", "enumValues"]);
+    exact(p, ["fieldPath", "candidateValue", "confidence", "provenance", "extractor"], `proposal[${index}]`, ["pathIndices", "inferenceType", "valueType", "enumValues", "producedBy", "evidenceMatch"]);
     wireNonEmpty(p.fieldPath, "proposal.fieldPath");
     stableIdentity(p.extractor, "proposal.extractor");
     finite(p.confidence, "proposal.confidence", 0, 1);
@@ -252,6 +256,10 @@ function validateProposal(input, index, contentLength) {
         throw new Error("proposal valueType is invalid.");
     if (p.enumValues !== undefined)
         array(p.enumValues, "enumValues").forEach((v) => wellFormedString(v, "enumValue"));
+    if (p.producedBy !== undefined)
+        validateProducedBy(p.producedBy);
+    if (p.evidenceMatch !== undefined)
+        validateEvidenceMatch(p.evidenceMatch);
     return cloneJson(p);
 }
 function validateOccurrence(input, start, end) { const o = obj(input, "occurrence"); exact(o, ["resolverVersion", "count", "selected", "selection", "hintUsed", "ambiguous"], "occurrence"); if (o.resolverVersion !== "exact-occurrence-v1")
@@ -317,8 +325,18 @@ else
     throw new Error("partial requires partial outcome."); }
 function validateWarning(v) { const w = obj(v, "warning"); exact(w, ["category", "code"], "warning"); if (!WARNING_CATEGORIES.has(w.category))
     throw new Error("warning category invalid."); stableIdentity(w.code, "warning.code"); }
-function validateFailure(v) { const f = obj(v, "providerFailure"); exact(f, ["provider", "kind", "retryable"], "providerFailure"); stableIdentity(f.provider, "failure.provider"); if (!FAILURE_KINDS.has(f.kind) || typeof f.retryable !== "boolean")
-    throw new Error("provider failure invalid."); }
+function validateFailure(v) { const f = obj(v, "providerFailure"); exact(f, ["provider", "kind", "retryable"], "providerFailure", ["code"]); stableIdentity(f.provider, "failure.provider"); if (!FAILURE_KINDS.has(f.kind) || typeof f.retryable !== "boolean")
+    throw new Error("provider failure invalid."); if (f.code !== undefined) {
+    stableIdentity(f.code, "failure.code");
+    if (f.code.length > 128)
+        throw new Error("failure.code must be at most 128 characters.");
+} }
+function validateProducedBy(v) { const b = obj(v, "proposal.producedBy"); exact(b, ["model", "modelSource", "requestDigest"], "proposal.producedBy"); stableIdentity(b.model, "proposal.producedBy.model"); if (!MODEL_SOURCES.has(b.modelSource))
+    throw new Error("proposal.producedBy.modelSource is invalid."); digest(b.requestDigest, "proposal.producedBy.requestDigest"); }
+function validateEvidenceMatch(v) { const m = obj(v, "proposal.evidenceMatch"); exact(m, ["checkerVersion", "schema", "valueInExcerpt"], "proposal.evidenceMatch", ["tokenBoundary"]); stableIdentity(m.checkerVersion, "proposal.evidenceMatch.checkerVersion"); if (!SCHEMA_MATCHES.has(m.schema))
+    throw new Error("proposal.evidenceMatch.schema is invalid."); if (!VALUE_IN_EXCERPT_MATCHES.has(m.valueInExcerpt))
+    throw new Error("proposal.evidenceMatch.valueInExcerpt is invalid."); if (m.tokenBoundary !== undefined && typeof m.tokenBoundary !== "boolean")
+    throw new Error("proposal.evidenceMatch.tokenBoundary must be a boolean."); }
 function validateClaimTarget(v) { const t = obj(v, "claimTarget"); exact(t, ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior", "impactLevel"], "claimTarget", ["claimId", "evidenceType", "evidenceMethod", "collectedBy", "derivedFrom"]); for (const key of ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior"])
     nonEmpty(t[key], `claimTarget.${key}`); if (!["low", "medium", "high", "critical"].includes(t.impactLevel))
     throw new Error("claimTarget.impactLevel invalid."); for (const key of ["claimId", "evidenceType", "evidenceMethod", "collectedBy"])
@@ -433,6 +451,9 @@ const PARTIAL = new Set(["cancelled", "max-provider-calls", "max-total-tokens",
 const FAILURE_CATEGORIES = new Set(["invalid-config", "invalid-task", "preparation", "provider", "unexpected"]);
 const WARNING_CATEGORIES = new Set(["provider", "normalization", "preparation", "limit", "storage", "content", "other"]);
 const FAILURE_KINDS = new Set(["authentication", "rate-limit", "timeout", "invalid-request", "unavailable", "unknown"]);
+const MODEL_SOURCES = new Set(["provider-reported", "configured"]);
+const SCHEMA_MATCHES = new Set(["ok", "type-mismatch", "enum-mismatch", "format-invalid"]);
+const VALUE_IN_EXCERPT_MATCHES = new Set(["match", "mismatch", "not-evaluated", "not-applicable"]);
 const PREPARATION_MODES = new Set(["text", "markdown", "transcript", "pdf-text", "image-ocr"]);
 const ARTIFACT_INVALID_REASONS = new Set(["not-an-object", "invalid-format", "invalid-version", "invalid-digest", "invalid-ref", "invalid-preparation-mode", "invalid-preparation-version", "invalid-content-length", "invalid-source-snapshot-ref", "ill-formed-unicode", "invalid-resolved-text"]);
 const STABLE_IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._:@/+~-]{0,255}$/;

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, InterpretationAnswerImpact, InterpretationReadingKind, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
 export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeResolutionIdentity, exportExtractionEnvelopeImport, extractionEnvelopeImportApiVersion, importExtractionEnvelope, portableExtractionResultFormat, portableExtractionResultVersion, reimportExtractionEnvelope, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
@@ -8,7 +8,7 @@ export type { BindReviewQueueOptions, ReviewQueueBinding, ReviewQueueBindingIssu
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry, PortablePdfRegionContext, PortablePdfTable, PortablePdfTableCell, PortablePdfTextElement, PortablePdfTextRange, } from "./pdf-layout.js";
 export type { ExtractionAlignmentState, ArtifactUnavailableCode, BuiltExtractionInspectorCandidate, BuiltExtractionInspectorModel, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
-export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionOccurrence, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
+export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionEvidenceMatch, PortableExtractionOccurrence, PortableExtractionProducedBy, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
 export type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
 export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
@@ -17,7 +17,7 @@ export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js"
 export type { ReviewedCandidateResolutionInput } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-resolution.js";
-export { buildSurveyTrustBundle } from "./to-surface.js";
+export { buildSurveyTrustBundle, ReviewAgreementError } from "./to-surface.js";
 export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
 export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
 export type { BuildCanonicalReviewedTrustInputOptions, CanonicalReviewedTrustInput, } from "./canonical-reviewed-trust-input.js";
@@ -35,16 +35,17 @@ export { repeatedObservation } from "./repeated-observation.js";
 export type { RepeatedObservationInput } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationBuilderArgs, SourceOfAuthorityObservationInput, } from "./source-of-authority-observation.js";
-export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
-export type { ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export type { InterpretationReadingPresentation, InterpretationReadingSource, ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, PolicyStandardMetadata, PolicyStandardSourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
-export type { AutoAcceptPolicy, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
+export type { AutoAcceptWarning } from "./producer-profile.js";
+export type { AutoAcceptPolicy, AutoAcceptPolicyOptions, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
-export type { ExtractedStatement, StatementBadge, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
+export type { ExtractedStatement, LocatorResolution, StatementBadge, StatementValueComparison, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
-export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";
+export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SchemaMappingValue, SystemFieldRef, } from "./schema-mapping.js";
 export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
 export type { BuildAuthorizedActionAuthorizingInput, BuildPromptRefInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";
 export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";

package/dist/src/index.js

@@ -8,7 +8,7 @@ export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport,
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
-export { buildSurveyTrustBundle } from "./to-surface.js";
+export { buildSurveyTrustBundle, ReviewAgreementError } from "./to-surface.js";
 export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
@@ -17,7 +17,7 @@ export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalRevi
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
-export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";

package/dist/src/inquiry-mapping.d.ts

@@ -20,6 +20,7 @@
 import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
 import type { CanonicalClaimTarget } from "@kontourai/surface";
 import type { Candidate, CandidateSet, ReviewOutcome } from "./types.js";
+import type { AutoAcceptWarning } from "./producer-profile.js";
 import type { ReviewItem } from "./review-resource.js";
 /**
  * A single machine- or human-generated suggestion that a natural-language
@@ -140,18 +141,31 @@ export declare function applyMappingReview(candidateSet: CandidateSet, reviewOut
 export interface AutoAcceptPolicy {
     minConfidence: number;
 }
+/** Optional hooks for {@link applyAutoAcceptPolicy}. */
+export interface AutoAcceptPolicyOptions {
+    /**
+     * Called once for each proposal the policy refused because its confidence
+     * is not a finite number in [0, 1]. The proposal gets no mapping and stays
+     * in human review.
+     */
+    onWarning?: (warning: AutoAcceptWarning) => void;
+}
 /**
  * Apply an auto-accept policy to a list of proposals, returning InquiryMappings.
  *
  * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
  * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ * Proposals whose confidence is not a finite number in [0, 1] are never
+ * auto-accepted. Throws `RangeError` unless `policy.minConfidence` is a finite
+ * number in (0, 1]. Refused out-of-range proposals are reported through
+ * `options.onWarning`.
  *
  * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
  * need human review regardless of confidence.
  *
  * Returns an array of InquiryMappings (only for accepted proposals).
  */
-export declare function applyAutoAcceptPolicy(proposals: MappingProposal[], policy: AutoAcceptPolicy): InquiryMapping[];
+export declare function applyAutoAcceptPolicy(proposals: MappingProposal[], policy: AutoAcceptPolicy, options?: AutoAcceptPolicyOptions): InquiryMapping[];
 /**
  * Look up an InquiryMapping for a question by exact normalized-text match.
  *

package/dist/src/inquiry-mapping.js

@@ -18,7 +18,7 @@
  * and lives in the flow-agents repo.
  */
 import { resolveInquiry } from "@kontourai/surface";
-import { evaluateAutoAccept, getProducerProposal, hasCandidateConflict, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { assertValidAutoAcceptThreshold, evaluateAutoAccept, getProducerProposal, hasCandidateConflict, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { reviewResourceApiVersion } from "./review-resource.js";
 // ---------------------------------------------------------------------------
 // Question normalization
@@ -140,13 +140,18 @@ export function applyMappingReview(candidateSet, reviewOutcome) {
  *
  * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
  * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ * Proposals whose confidence is not a finite number in [0, 1] are never
+ * auto-accepted. Throws `RangeError` unless `policy.minConfidence` is a finite
+ * number in (0, 1]. Refused out-of-range proposals are reported through
+ * `options.onWarning`.
  *
  * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
  * need human review regardless of confidence.
  *
  * Returns an array of InquiryMappings (only for accepted proposals).
  */
-export function applyAutoAcceptPolicy(proposals, policy) {
+export function applyAutoAcceptPolicy(proposals, policy, options = {}) {
+    assertValidAutoAcceptThreshold(policy.minConfidence);
     if (proposals.length === 0)
         return [];
     // If proposals disagree, none can be auto-accepted
@@ -154,6 +159,9 @@ export function applyAutoAcceptPolicy(proposals, policy) {
         return [];
     return proposals.flatMap((proposal) => {
         const decision = evaluateAutoAccept({ confidence: proposal.confidence, rationale: proposal.rationale, proposedAt: proposal.proposedAt }, false, policy, proposal.proposedAt);
+        if (decision.warning) {
+            options.onWarning?.({ code: decision.warning, proposalId: proposal.id, confidence: decision.confidence });
+        }
         if (!decision.accepted)
             return [];
         return [