@kontourai/survey 6.1.0 → 7.0.0

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

@@ -3,9 +3,9 @@ import { resolve, dirname } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
-import { buildReviewSessionEvents, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
+import { attestReviewQueueExtraction, buildReviewSessionEvents, conflictSelectionIssue, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
-import { buildReviewItemPresentation, candidateVerificationNotes, excludedProposalsSentence } from "../review-workbench/review-presentation.js";
+import { buildReviewItemPresentation, candidateVerificationNotes, excludedProposalsSentence, excludedProposalsUnreadableSentence } from "../review-workbench/review-presentation.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";
@@ -16,15 +16,33 @@ const SERVER_INSTRUCTIONS = "Use survey_review_queue to inspect the queue, surve
 // MCP tool decision strings → ReviewWorkbenchDecision
 const MCP_DECISION_MAP = {
     accept: "accept-proposed",
+    select: "select-proposed",
     hold: "keep-current",
     reject: "reject-proposed",
     "could-not-confirm": "could-not-confirm",
 };
+/**
+ * Reads the session and checks its queue against the extraction import stored
+ * beside it. A queue that does not match its import is refused outright; one
+ * whose items came from an import but has no record stored is presented with
+ * an "Unverified queue" notice on every surface.
+ */
 async function readSessionFile(path) {
-    return readReviewSessionFile(path);
+    const file = await readReviewSessionFile(path);
+    return { ...file, attestation: attestedQueue(file) };
+}
+function attestedQueue(file) {
+    const attestation = attestReviewQueueExtraction(file.snapshot.items, file.extractionImport);
+    if (attestation.state === "diverges") {
+        throw new DomainError(attestation.message);
+    }
+    return attestation;
+}
+function attestationLines(attestation) {
+    return attestation.state === "unverified" ? [attestation.message, ``] : [];
 }
 // ---- Queue helpers -------------------------------------------------------
-function queueSummaryText(snapshot, events) {
+function queueSummaryText(snapshot, events, attestation) {
     const current = currentSessionState(snapshot, events);
     const summary = reviewSessionSummary(current);
     const total = current.items.length;
@@ -38,6 +56,7 @@ function queueSummaryText(snapshot, events) {
         return `  ${item.metadata.name} — ${item.spec.target} — ${status}${marker}`;
     });
     return [
+        ...attestationLines(attestation),
         `Review queue: ${resolved}/${total} resolved`,
         `Active item: ${activeItem.metadata.name} (${activeItem.spec.target})`,
         ...(nextItem ? [`Next unresolved: ${nextItem}`] : ["All items resolved."]),
@@ -48,16 +67,18 @@ function queueSummaryText(snapshot, events) {
         ...rows,
     ].join("\n");
 }
-function itemDetailText(item, snapshot, events) {
+function itemDetailText(item, snapshot, events, attestation) {
     const current = currentSessionState(snapshot, events);
     const status = deriveQueueRowStatus(item, current);
     const decision = current.decisionsByItemName[item.metadata.name];
     const note = current.notesByItemName[item.metadata.name];
+    const chosenId = decision === "select-proposed" ? current.selectedCandidateIdsByItemName?.[item.metadata.name] : undefined;
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
     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 = [
+        ...attestationLines(attestation),
         `Item: ${item.metadata.name}`,
         `Target: ${item.spec.target}`,
         `Status: ${status}`,
@@ -71,10 +92,14 @@ function itemDetailText(item, snapshot, events) {
         ...(currentCandidate?.locator?.excerpt ? [`  excerpt: ${currentCandidate.locator.excerpt}`] : []),
         ``,
         ...(proposedCandidates.length > 1
-            ? [`Conflict: ${proposedCandidates.length} proposed values. Accept is refused; reject them all or use could-not-confirm with a reason.`]
+            ? [`Conflict: ${proposedCandidates.length} proposed values. Accept is refused; choose one with decision "select" and its candidateId, reject them all, or use could-not-confirm with a reason.`]
+            : []),
+        ...(chosenId !== undefined
+            ? [`Chosen value: ${valueStr(proposedCandidates.find((c) => c.id === chosenId)?.value)} (candidate ${chosenId}); not chosen: ${proposedCandidates.filter((c) => c.id !== chosenId).map((c) => `${valueStr(c.value)} (candidate ${c.id})`).join(", ")}`]
             : []),
         ...(proposedCandidates.length === 0 ? [`Proposed value: (none)`] : proposedCandidates.flatMap((candidate) => [
-            `Proposed value: ${valueStr(candidate.value)}`,
+            `Proposed value: ${valueStr(candidate.value)}${chosenId === undefined ? "" : candidate.id === chosenId ? " [chosen]" : " [not chosen]"}`,
+            ...(proposedCandidates.length > 1 ? [`  candidateId: ${candidate.id}`] : []),
             `  confidence: ${confStr(candidate.extraction?.confidence ?? candidate.confidence)}`,
             `  source: ${candidate.source?.sourceRef ?? "none"}`,
             ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
@@ -95,8 +120,10 @@ function editedValueFor(item, state) {
 function extractionImportLines(item) {
     const presentation = buildReviewItemPresentation(item);
     const excluded = excludedProposalsSentence(presentation.excludedProposals);
+    const unreadable = excludedProposalsUnreadableSentence(presentation.excludedProposalsUnreadable);
     return [
         ...(excluded ? [``, `Excluded: ${excluded} Check the source before accepting.`] : []),
+        ...(unreadable ? [``, `Excluded: ${unreadable} Check the source before accepting.`] : []),
         ...(presentation.excerptVerification ? [``, `Excerpts ${presentation.excerptVerification === "verified" ? "were" : "were not"} checked against the prepared source text at import.`] : []),
     ];
 }
@@ -114,17 +141,19 @@ function escapeHtml(text) {
         .replace(/>/g, ">")
         .replace(/"/g, """);
 }
-function buildReviewCardHtml(item, snapshot, events) {
+function buildReviewCardHtml(item, snapshot, events, attestation) {
     const current = currentSessionState(snapshot, events);
     const summary = reviewSessionSummary(current);
     const total = current.items.length;
     const resolved = total - summary.unresolved;
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
     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.
+    // Several proposed values are a conflict: every value is shown, accept
+    // (which names a role, not a value) is not offered, and each value has its
+    // own "Use this value" control that names its candidate id.
     const conflict = proposedCandidates.length > 1;
     const decision = current.decisionsByItemName[item.metadata.name];
+    const chosenId = decision === "select-proposed" ? current.selectedCandidateIdsByItemName?.[item.metadata.name] : undefined;
     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)}%` : "—";
@@ -135,22 +164,32 @@ function buildReviewCardHtml(item, snapshot, events) {
     const proposedCard = (candidate, label) => {
         const value = valueStr(candidate?.value ?? "—");
         const excerpt = candidate?.locator?.excerpt ?? "";
-        return `<div class="card is-proposed">
+        const choice = conflict && candidate
+            ? chosenId !== undefined
+                ? `<div class="choice ${candidate.id === chosenId ? "chosen" : "not-chosen"}" data-candidate-id="${escapeHtml(candidate.id)}">${candidate.id === chosenId ? "Chosen" : "Not chosen"}</div>`
+                : decision === undefined
+                    ? `<button class="btn btn-accept btn-select" data-candidate-id="${escapeHtml(candidate.id)}">Use this value</button>`
+                    : ""
+            : "";
+        return `<div class="card is-proposed"${conflict && candidate ? ` data-candidate-id="${escapeHtml(candidate.id)}"` : ""}>
     <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>` : ""}
+    ${choice}
   </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 excludedNote = excludedProposalsSentence(buildReviewItemPresentation(item).excludedProposals);
+    const itemPresentation = buildReviewItemPresentation(item);
+    const excludedNote = excludedProposalsSentence(itemPresentation.excludedProposals);
+    const unreadableNote = excludedProposalsUnreadableSentence(itemPresentation.excludedProposalsUnreadable);
     const verificationNotes = candidateVerificationNotes(item, editedValueFor(item, current));
     const decisionBadge = decision
-        ? `<span class="badge badge-${decision === "accept-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(workbenchDecisionDefinitions[decision].label)}</span>`
+        ? `<span class="badge badge-${decision === "accept-proposed" || decision === "select-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(decision === "select-proposed" ? `Chose 1 of ${proposedCandidates.length} values` : workbenchDecisionDefinitions[decision].label)}</span>`
         : `<span class="badge badge-pending">${escapeHtml(status)}</span>`;
     return `<!doctype html>
 <html lang="en">
@@ -228,9 +267,15 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 .btn-reject:hover,.btn-reject.active{background:color-mix(in srgb,var(--k-negative) 16%,transparent);border-color:var(--k-negative);color:var(--k-negative)}
 .btn-unconfirmed:hover,.btn-unconfirmed.active{background:color-mix(in srgb,var(--k-caution) 16%,transparent);border-color:var(--k-caution);color:var(--k-caution)}
 .feedback{font-size:11px;color:var(--k-text-faint);margin-top:8px;min-height:16px}
+.btn-select{width:100%;margin-top:8px}
+.choice{font-family:var(--k-font-mono);font-size:10px;font-weight:600;margin-top:8px;text-transform:uppercase;letter-spacing:.06em}
+.choice.chosen{color:var(--k-positive)}
+.choice.not-chosen{color:var(--k-text-faint)}
+.notice{font-size:11px;color:var(--k-caution);background:color-mix(in srgb,var(--k-caution) 12%,transparent);border-radius:var(--k-radius-sm);padding:7px 10px;margin:0 0 12px}
 </style>
 </head>
 <body>
+${attestation.state === "unverified" ? `<p class="notice" id="unverified-queue-note">${escapeHtml(attestation.message)}</p>` : ""}
 <p class="eyebrow">Survey Review</p>
 <h1>${escapeHtml(item.spec.target)}</h1>
 <div class="meta">
@@ -251,8 +296,11 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
   ${proposedCards}
 </div>
 ${excludedNote ? `<p class="feedback" id="excluded-note">${escapeHtml(excludedNote)}</p>` : ""}
+${unreadableNote ? `<p class="feedback" id="excluded-unreadable-note">${escapeHtml(unreadableNote)}</p>` : ""}
 ${verificationNotes.map((entry) => `<p class="feedback verification-note" data-candidate-id="${escapeHtml(entry.candidateId)}">${escapeHtml(entry.sentence)}</p>`).join("\n")}
-${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>` : ""}
+${conflict ? `<p class="feedback" id="conflict-note">${escapeHtml(chosenId !== undefined
+        ? `${proposedCandidates.length} different values were proposed. One was chosen; ${proposedCandidates.length === 2 ? "the other was" : "the others were"} seen and not chosen.`
+        : `${proposedCandidates.length} different values were proposed. Use the value the source supports, reject them all, or use Could not confirm with a reason.`)}</p>` : ""}
 
 <div class="divider"></div>
 
@@ -272,7 +320,7 @@ ${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length
   var itemName = ${itemNameJson};
   var msgId = 1;
 
-  function postDecision(decision) {
+  function postDecision(decision, candidateId) {
     var note = document.getElementById('note').value;
     if (decision === 'could-not-confirm' && !note.trim()) {
       document.getElementById('feedback').textContent = 'A reason is required when you could not confirm.';
@@ -287,12 +335,18 @@ ${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length
         name: "survey_review_decide",
         arguments: decision === 'could-not-confirm'
           ? { itemName: itemName, decision: decision, reason: note }
-          : { itemName: itemName, decision: decision, note: note || undefined }
+          : decision === 'select'
+            ? { itemName: itemName, decision: decision, candidateId: candidateId, note: note || undefined }
+            : { itemName: itemName, decision: decision, note: note || undefined }
       }
     }, "*");
     return true;
   }
 
+  Array.prototype.forEach.call(document.querySelectorAll('.btn-select'), function (button) {
+    button.addEventListener('click', function () { postDecision('select', button.getAttribute('data-candidate-id')); document.getElementById('feedback').textContent = 'Submitting choice…'; });
+  });
+
   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');
@@ -318,16 +372,21 @@ ${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length
 // ---- Tool implementations ------------------------------------------------
 async function toolQueue(options) {
     const file = await readSessionFile(options.sessionPath);
-    const { snapshot, events } = file;
-    const text = queueSummaryText(snapshot, events);
+    const { snapshot, events, attestation } = file;
+    const text = queueSummaryText(snapshot, events, attestation);
     const queueData = {
+        queueAttestation: attestation.state,
         items: snapshot.items.map((item) => {
             const current = currentSessionState(snapshot, events);
+            const selectedCandidateId = current.decisionsByItemName[item.metadata.name] === "select-proposed"
+                ? current.selectedCandidateIdsByItemName?.[item.metadata.name]
+                : undefined;
             return {
                 name: item.metadata.name,
                 target: item.spec.target,
                 status: deriveQueueRowStatus(item, current),
                 decision: current.decisionsByItemName[item.metadata.name],
+                ...(selectedCandidateId !== undefined ? { selectedCandidateId } : {}),
                 candidateSetStatus: item.spec.candidateSetStatus,
             };
         }),
@@ -339,24 +398,28 @@ async function toolQueue(options) {
     ];
     if (!options.noUi) {
         const activeItem = currentReviewItem(currentSessionState(snapshot, events));
-        content.push(buildUiResource(activeItem, snapshot, events, "queue"));
+        content.push(buildUiResource(activeItem, snapshot, events, "queue", attestation));
     }
     return content;
 }
 async function toolItem(itemName, options) {
     const file = await readSessionFile(options.sessionPath);
-    const { snapshot, events } = file;
+    const { snapshot, events, attestation } = 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 text = itemDetailText(item, snapshot, events);
+    const text = itemDetailText(item, snapshot, events, attestation);
+    const decision = current.decisionsByItemName[item.metadata.name];
+    const selectedCandidateId = decision === "select-proposed" ? current.selectedCandidateIdsByItemName?.[item.metadata.name] : undefined;
     const itemData = {
+        queueAttestation: attestation.state,
         name: item.metadata.name,
         target: item.spec.target,
         status: deriveQueueRowStatus(item, current),
-        decision: current.decisionsByItemName[item.metadata.name],
+        decision,
+        ...(selectedCandidateId !== undefined ? { selectedCandidateId } : {}),
         note: current.notesByItemName[item.metadata.name],
         candidateSetStatus: item.spec.candidateSetStatus,
         ...(() => {
@@ -364,6 +427,7 @@ async function toolItem(itemName, options) {
             return {
                 ...(presentation.excerptVerification ? { excerptVerification: presentation.excerptVerification } : {}),
                 ...(presentation.excludedProposals.length ? { excludedProposals: presentation.excludedProposals.map(({ proposalIndex, value, locator, excerpt }) => ({ proposalIndex, value, locator, excerpt })) } : {}),
+                ...(presentation.excludedProposalsUnreadable ? { excludedProposalsUnreadable: presentation.excludedProposalsUnreadable } : {}),
             };
         })(),
         candidates: (() => {
@@ -377,6 +441,7 @@ async function toolItem(itemName, options) {
                     confidence: c.extraction?.confidence ?? c.confidence,
                     sourceRef: c.source?.sourceRef,
                     excerpt: c.locator?.excerpt,
+                    ...(selectedCandidateId !== undefined && c.role === "proposed" ? { chosen: c.id === selectedCandidateId } : {}),
                     ...(note ? { verification: { subject: note.subjectLabel, status: note.status, records: note.records, inapplicableCount: note.inapplicableCount, rejectedCount: note.rejectedCount } } : {}),
                 };
             });
@@ -386,22 +451,23 @@ async function toolItem(itemName, options) {
         { type: "text", text: `${text}\n\n${JSON.stringify(itemData, null, 2)}` },
     ];
     if (!options.noUi) {
-        content.push(buildUiResource(item, snapshot, events, itemName));
+        content.push(buildUiResource(item, snapshot, events, itemName, attestation));
     }
     return content;
 }
-async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, options) {
+async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, options, selectedCandidateId) {
     const wbDecision = MCP_DECISION_MAP[mcpDecision];
     if (!wbDecision) {
-        throw new DomainError(`Invalid decision: ${mcpDecision}. Must be accept, hold, reject, or could-not-confirm.`);
+        throw new DomainError(`Invalid decision: ${mcpDecision}. Must be accept, select, hold, reject, or could-not-confirm.`);
     }
     if (wbDecision === "could-not-confirm" && !note?.trim()) {
         throw new DomainError("survey_review_decide requires a non-empty reason for could-not-confirm");
     }
     // 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, sessionWithDecision, newEvents, attestation } = await updateReviewSessionFile(options.sessionPath, (file) => {
         const { snapshot, events } = file;
+        const attestation = attestedQueue(file);
         const current = currentSessionState(snapshot, events);
         const item = current.items.find((i) => i.metadata.name === itemName);
         if (!item) {
@@ -411,6 +477,12 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
         if (existingDecision) {
             throw new DomainError(`Item ${itemName} already has a decision: ${existingDecision}. Use a new session to re-decide.`);
         }
+        if (wbDecision === "select-proposed") {
+            const selectionIssue = conflictSelectionIssue(item, selectedCandidateId);
+            if (selectionIssue) {
+                throw new DomainError(selectionIssue);
+            }
+        }
         // Build the updated session state with the decision
         const sessionWithDecision = {
             ...current,
@@ -434,6 +506,14 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
                     },
                 }
                 : {}),
+            ...(wbDecision === "select-proposed" && selectedCandidateId !== undefined
+                ? {
+                    selectedCandidateIdsByItemName: {
+                        ...current.selectedCandidateIdsByItemName,
+                        [itemName]: selectedCandidateId,
+                    },
+                }
+                : {}),
         };
         // Append only this decision's events (its note, then the decision) to the
         // stored log. Regenerating the whole log from state would erase earlier
@@ -455,26 +535,36 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
             record,
             events: newEvents,
             requiredResolvedItems: "none",
+            extractionImport: file.extractionImport,
         });
         if (!applyResult.ok) {
             throw new DomainError(`Decision validation failed: ${applyResult.issues.map((issue) => "message" in issue ? issue.message : String(issue)).join("; ")}`);
         }
         const updatedFile = {
+            ...file,
             session: file.session,
             snapshot,
             events: newEvents,
         };
-        return { next: updatedFile, result: { snapshot, sessionWithDecision, newEvents } };
+        return { next: updatedFile, result: { snapshot, sessionWithDecision, newEvents, attestation } };
     });
     // 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 itemText = updatedItem ? itemDetailText(updatedItem, snapshot, newEvents, attestation) : `Item: ${itemName}`;
+    const remainingText = queueSummaryText(snapshot, newEvents, attestation);
     const definition = workbenchDecisionDefinitions[wbDecision];
     const conflictRejected = wbDecision === "reject-proposed" && updatedItem !== undefined && decisionSelectsNoCandidate(updatedItem, wbDecision);
+    const valueStr = (v) => (typeof v === "string" ? v : JSON.stringify(v));
+    const proposed = updatedItem?.spec.candidates.filter((c) => c.role === "proposed") ?? [];
+    const chosen = proposed.find((c) => c.id === selectedCandidateId);
+    const effect = conflictRejected
+        ? "Every proposed value is rejected; none becomes the claim's value."
+        : wbDecision === "select-proposed"
+            ? `${valueStr(chosen?.value)} becomes the verified value; not chosen: ${proposed.filter((c) => c.id !== selectedCandidateId).map((c) => valueStr(c.value)).join(", ")}.`
+            : definition.effect;
     const text = [
         `Decision recorded: ${conflictRejected ? "Reject all values" : definition.label}`,
-        `Effect: ${conflictRejected ? "Every proposed value is rejected; none becomes the claim's value." : definition.effect}`,
+        `Effect: ${effect}`,
         "",
         itemText,
         "",
@@ -483,13 +573,13 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
     ].join("\n");
     return [{ type: "text", text }];
 }
-function buildUiResource(item, snapshot, events, instance) {
+function buildUiResource(item, snapshot, events, instance, attestation) {
     return {
         type: "resource",
         resource: {
             uri: `ui://survey/review-card/${encodeURIComponent(instance)}`,
             mimeType: "text/html;profile=mcp-app",
-            text: buildReviewCardHtml(item, snapshot, events),
+            text: buildReviewCardHtml(item, snapshot, events, attestation),
             _meta: {
                 ui: {
                     csp: {
@@ -505,10 +595,10 @@ function buildUiResource(item, snapshot, events, instance) {
 // Render the declared review card from the same function used by embedded tool
 // results, so Apps and text-first hosts cannot drift.
 async function readQueuePanelResource(options) {
-    const { snapshot, events } = await readSessionFile(options.sessionPath);
+    const { snapshot, events, attestation } = await readSessionFile(options.sessionPath);
     const current = currentSessionState(snapshot, events);
     const activeItem = currentReviewItem(current);
-    return buildUiResource(activeItem, snapshot, events, "queue").resource;
+    return buildUiResource(activeItem, snapshot, events, "queue", attestation).resource;
 }
 // ---- Domain error (maps to isError:true, not a JSON-RPC error) -----------
 class DomainError extends Error {
@@ -557,7 +647,7 @@ function createReviewMcpServer(options, serverVersion) {
     }, async ({ itemName }) => runReviewTool(() => toolItem(itemName, options)));
     server.registerTool("survey_review_decide", {
         title: "Record a review decision",
-        description: "Apply a decision to a review item and persist it through Survey's server-owned validation boundary. Decision must be accept, hold, reject, or could-not-confirm. Could-not-confirm requires a reason. Domain failures return isError:true.",
+        description: "Apply a decision to a review item and persist it through Survey's server-owned validation boundary. Decision must be accept, select, hold, reject, or could-not-confirm. Select chooses one value of a conflict (several proposed values) by candidateId. Could-not-confirm requires a reason. Domain failures return isError:true.",
         inputSchema: z.discriminatedUnion("decision", [
             z.object({
                 itemName: z.string().min(1).describe("The ReviewItem name to decide."),
@@ -581,10 +671,23 @@ function createReviewMcpServer(options, serverVersion) {
                     .optional()
                     .describe("Evidence ids attempted before a could-not-confirm decision."),
             }),
+            z.object({
+                itemName: z.string().min(1).describe("The ReviewItem name to decide."),
+                decision: z
+                    .literal("select")
+                    .describe("select = select-proposed: choose one value of a conflict; the other proposed values are recorded as seen and not chosen."),
+                candidateId: z
+                    .string()
+                    .min(1)
+                    .describe("The id of the proposed candidate to use, from survey_review_item."),
+                note: z.string().optional().describe("Optional reviewer note or rationale."),
+            }),
         ]),
     }, async (input) => runReviewTool(() => input.decision === "could-not-confirm"
         ? toolDecide(input.itemName, input.decision, input.reason, input.attemptEvidenceIds, options)
-        : toolDecide(input.itemName, input.decision, input.note, undefined, options)));
+        : input.decision === "select"
+            ? toolDecide(input.itemName, input.decision, input.note, undefined, options, input.candidateId)
+            : toolDecide(input.itemName, input.decision, input.note, undefined, options)));
     if (!options.noUi) {
         server.registerResource("survey-review-workbench", QUEUE_PANEL_URI, {
             title: "Survey review workbench",

package/dist/src/review-resource.d.ts

@@ -200,6 +200,13 @@ export interface ReviewDecisionSpec {
      * Additive/optional: absent means the candidate's original value was used unchanged.
      */
     editedValue?: unknown;
+    /**
+     * The proposed candidates a `select-proposed` decision saw and did not
+     * choose, when the reviewer chose one value of a conflict (`candidateId` is
+     * the chosen one). Additive/optional: absent on every other decision, and on
+     * decisions recorded before choosing between conflicting values existed.
+     */
+    unselectedCandidateIds?: string[];
 }
 export interface ReviewDecisionStatus {
     appliedToClaimIds?: string[];

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

@@ -14,6 +14,13 @@ export interface ReviewSessionFileContent {
     readonly session: unknown;
     readonly snapshot: ReviewQueueSessionState;
     readonly events: readonly ReviewSessionEvent[];
+    /**
+     * The extraction import record (`ExtractionEnvelopeImport`) the snapshot's
+     * items were built from, stored beside them so every reload path can check
+     * the queue against it. Optional: a session without one whose items came
+     * from an import is presented as an unverified queue.
+     */
+    readonly extractionImport?: unknown;
 }
 export interface ReviewSessionFileLockOptions {
     /** How long to wait for a busy lock before failing. Defaults to 10s. */

package/dist/src/review-workbench/audit-rows.d.ts

@@ -25,7 +25,7 @@
  * it is a duplicate placement or a constant, but a key is never renamed or
  * repointed at a different fact. Hosts may hold selectors against these values.
  */
-export declare const reviewAuditRowKeys: readonly ["current-candidate-id", "proposed-candidate-id", "claim-id", "raw-source-id", "locator", "model", "extractor", "extracted-at", "excluded-proposal", "history-value", "candidate-id", "source-reference", "excerpt", "observed", "source-authority-class", "declared-by", "authority-scope", "extraction-id", "actor", "reviewed-at", "status", "rationale", "outcome", "checksum", "candidate-set-id", "authority-trace-status", "authority-trace-detail"];
+export declare const reviewAuditRowKeys: readonly ["current-candidate-id", "proposed-candidate-id", "claim-id", "raw-source-id", "locator", "model", "extractor", "extracted-at", "excluded-proposal", "excluded-proposals-unreadable", "history-value", "candidate-id", "source-reference", "excerpt", "observed", "source-authority-class", "declared-by", "authority-scope", "extraction-id", "actor", "reviewed-at", "status", "rationale", "outcome", "checksum", "candidate-set-id", "authority-trace-status", "authority-trace-detail"];
 /** One of {@link reviewAuditRowKeys}. */
 export type ReviewAuditRowKey = (typeof reviewAuditRowKeys)[number];
 /**

package/dist/src/review-workbench/audit-rows.js

@@ -36,6 +36,7 @@ export const reviewAuditRowKeys = [
     "extractor",
     "extracted-at",
     "excluded-proposal",
+    "excluded-proposals-unreadable",
     // Unselected candidate history
     "history-value",
     "candidate-id",

package/dist/src/review-workbench/queue-binding.d.ts

@@ -1,6 +1,6 @@
 import type { ReviewQueueSessionState } from "./review-queue-session.js";
 import { reviewResourceApiVersion, type ReviewItem } from "../review-resource.js";
-import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import { type ExtractionEnvelopeImport, type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
 /**
  * The durable attestation record. Serializable; a consumer stores it beside the
  * queue when the round opens and presents it, unchanged, at every later
@@ -78,7 +78,7 @@ export declare function bindReviewQueue(snapshot: ReviewQueueSessionState, optio
  */
 export declare function validateReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): ReviewQueueBindingIssue[];
 export declare function assertReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): void;
-export type ReviewQueueExtractionIssueCode = "import-not-grounded" | "empty-queue" | "item-missing-from-queue" | "item-not-in-extraction" | "item-diverges-from-extraction";
+export type ReviewQueueExtractionIssueCode = "import-invalid" | "import-not-grounded" | "empty-queue" | "item-missing-from-queue" | "item-not-in-extraction" | "item-diverges-from-extraction";
 export interface ReviewQueueExtractionIssue {
     readonly code: ReviewQueueExtractionIssueCode;
     readonly message: string;
@@ -124,4 +124,47 @@ export declare class UnattestedExtractionQueueError extends Error {
  * cross-check the label.
  */
 export declare function validateReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): ReviewQueueExtractionIssue[];
+/**
+ * What a reload path can say about a stored queue and the extraction import it
+ * came from:
+ *
+ * - `attested`: an import record was supplied and the queue matches it (see
+ *   {@link validateReviewQueueAgainstExtractionImport}).
+ * - `diverges`: an import record was supplied and the queue does not match it,
+ *   or the record itself is invalid. The queue must not be reviewed.
+ * - `unverified`: items carry the extraction-envelope binding but no import
+ *   record was supplied, so nothing checked them. A rival value deleted from
+ *   the stored queue would not show; every surface says so.
+ * - `not-extraction`: no item carries the binding and no record was supplied;
+ *   there is no import to check against.
+ *
+ * Detection reads the binding the import writes on every item and candidate.
+ * A writer that strips it from every item also strips every other extraction
+ * fact from the queue; keeping the stored import record beside the queue is
+ * what makes a reload path able to check it.
+ */
+export type ReviewQueueExtractionAttestation = {
+    readonly state: "attested";
+} | {
+    readonly state: "not-extraction";
+} | {
+    readonly state: "unverified";
+    readonly itemNames: readonly string[];
+    readonly message: string;
+} | {
+    readonly state: "diverges";
+    readonly issues: readonly ReviewQueueExtractionIssue[];
+    readonly message: string;
+};
+/** Whether a ReviewItem, or any of its candidates, carries the extraction-envelope binding. */
+export declare function reviewItemCarriesExtractionBinding(item: ReviewItem): boolean;
+/**
+ * Check a queue a reload path is about to present against its extraction
+ * import. Pass the import record (or import result) stored beside the queue;
+ * pass `undefined` when the path has none, and the result says whether that
+ * leaves the queue unverified.
+ */
+export declare function attestReviewQueueExtraction(items: readonly ReviewItem[], extractionImport: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult | undefined): ReviewQueueExtractionAttestation;
+/** The notice every surface shows for an `unverified` queue. */
+export declare function unverifiedExtractionQueueSentence(itemCount: number): string;
 export declare function assertReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): void;

package/dist/src/review-workbench/queue-binding.js

@@ -276,6 +276,51 @@ export function validateReviewQueueAgainstExtractionImport(items, importResult)
     }
     return issues;
 }
+const EXTRACTION_ENVELOPE_PRODUCER = "survey.kontourai.io/extraction-envelope";
+/** Whether a ReviewItem, or any of its candidates, carries the extraction-envelope binding. */
+export function reviewItemCarriesExtractionBinding(item) {
+    const bound = (producer) => producer !== undefined && producer !== null && typeof producer === "object" && Object.hasOwn(producer, EXTRACTION_ENVELOPE_PRODUCER);
+    return bound(item.metadata?.producer) || (Array.isArray(item.spec?.candidates) && item.spec.candidates.some((candidate) => bound(candidate?.producer)));
+}
+/**
+ * Check a queue a reload path is about to present against its extraction
+ * import. Pass the import record (or import result) stored beside the queue;
+ * pass `undefined` when the path has none, and the result says whether that
+ * leaves the queue unverified.
+ */
+export function attestReviewQueueExtraction(items, extractionImport) {
+    if (extractionImport === undefined || extractionImport === null) {
+        const itemNames = items.filter(reviewItemCarriesExtractionBinding).map((item) => item.metadata.name);
+        return itemNames.length === 0
+            ? { state: "not-extraction" }
+            : { state: "unverified", itemNames, message: unverifiedExtractionQueueSentence(itemNames.length) };
+    }
+    const record = isImportResult(extractionImport) ? extractionImport.record : extractionImport;
+    let issues;
+    try {
+        issues = validateReviewQueueAgainstExtractionImport(items, { record, reviewItems: [] });
+    }
+    catch (error) {
+        issues = [{
+                code: "import-invalid",
+                message: `The stored extraction import is invalid: ${error instanceof Error ? error.message : String(error)}`,
+            }];
+    }
+    return issues.length === 0
+        ? { state: "attested" }
+        : {
+            state: "diverges",
+            issues,
+            message: `This review queue does not match the extraction import stored with it, so it cannot be reviewed: ${issues.map((issue) => issue.message).join(" ")}`,
+        };
+}
+/** The notice every surface shows for an `unverified` queue. */
+export function unverifiedExtractionQueueSentence(itemCount) {
+    return `Unverified queue: ${itemCount === 1 ? "1 item came" : `${itemCount} items came`} from an extraction import, but no import record was stored with this queue, so its items were not checked against it. A rival value removed from the stored queue would not be shown.`;
+}
+function isImportResult(value) {
+    return typeof value === "object" && value !== null && "record" in value && !("kind" in value);
+}
 export function assertReviewQueueAgainstExtractionImport(items, importResult) {
     const issues = validateReviewQueueAgainstExtractionImport(items, importResult);
     if (issues.length > 0) {