@kontourai/survey 6.1.0 → 8.0.0

package/dist/src/index.js

@@ -2,7 +2,7 @@ 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";
 export { buildExtractionInspectorModel, exportExtractionInspector, inspectorSourcePosture, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
-export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./review-workbench/queue-binding.js";
+export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, attestReviewQueueExtraction, bindReviewQueue, reviewItemCarriesExtractionBinding, unverifiedExtractionQueueSentence, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./review-workbench/queue-binding.js";
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
@@ -28,3 +28,5 @@ export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./v
 export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
 export { calibrationToClaims, deriveCalibration, mergeTrustBundleWithCalibration, } from "./calibration.js";
+export { deriveFieldStates, fieldStateClaimMetadata, lifecycleForDecision, FIELD_STATE_METADATA_KEY, } from "./field-states.js";
+export { buildDecisionSupersession, decisionCarryForwardKind, decisionReference, decisionResolution, decisionSupersessionKind, defaultCarryForwardPolicy, splitRoundForCarryForward, validateDecisionCarryForward, validateDecisionSupersession, } from "./decision-carry-forward.js";

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, isScoreBlind, 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,41 @@ 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, ``] : [];
+}
+/**
+ * A score-blind session shows no confidence and no verifier result on any
+ * surface (text, data or card), so the decision is made without them.
+ */
+const SCORE_BLIND_NOTICE = "Score-blind review: confidence and verifier results are hidden for this whole session. Decide from the source and its excerpt.";
+function scoreBlindLines(state) {
+    return isScoreBlind(state) ? [`${state.sampling?.kind === "random-audit" ? "Random audit sample. " : ""}${SCORE_BLIND_NOTICE}`, ``] : [];
 }
 // ---- 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 +64,8 @@ function queueSummaryText(snapshot, events) {
         return `  ${item.metadata.name} — ${item.spec.target} — ${status}${marker}`;
     });
     return [
+        ...attestationLines(attestation),
+        ...scoreBlindLines(current),
         `Review queue: ${resolved}/${total} resolved`,
         `Active item: ${activeItem.metadata.name} (${activeItem.spec.target})`,
         ...(nextItem ? [`Next unresolved: ${nextItem}`] : ["All items resolved."]),
@@ -48,16 +76,21 @@ 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 blind = isScoreBlind(current);
+    const confidenceLine = (c) => blind ? [] : [`  confidence: ${confStr(c)}`];
     const lines = [
+        ...attestationLines(attestation),
+        ...scoreBlindLines(current),
         `Item: ${item.metadata.name}`,
         `Target: ${item.spec.target}`,
         `Status: ${status}`,
@@ -66,21 +99,25 @@ function itemDetailText(item, snapshot, events) {
         ...(note ? [`Note: ${note}`] : []),
         ``,
         `Current value: ${valueStr(currentCandidate?.value ?? "(none)")}`,
-        `  confidence: ${confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence)}`,
+        ...confidenceLine(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence),
         `  source: ${currentCandidate?.source?.sourceRef ?? "none"}`,
         ...(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)}`,
-            `  confidence: ${confStr(candidate.extraction?.confidence ?? candidate.confidence)}`,
+            `Proposed value: ${valueStr(candidate.value)}${chosenId === undefined ? "" : candidate.id === chosenId ? " [chosen]" : " [not chosen]"}`,
+            ...(proposedCandidates.length > 1 ? [`  candidateId: ${candidate.id}`] : []),
+            ...confidenceLine(candidate.extraction?.confidence ?? candidate.confidence),
             `  source: ${candidate.source?.sourceRef ?? "none"}`,
             ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
         ])),
         ...extractionImportLines(item),
-        ...candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`]),
+        ...(blind ? [] : candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`])),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
@@ -88,6 +125,13 @@ function itemDetailText(item, snapshot, events) {
     return lines.join("\n");
 }
 /** The reviewer's edit when the item's decision accepts one; verifier records are read against it. */
+/** The session's presentation and sampling, as a client should read them. */
+function sessionConditions(snapshot) {
+    return {
+        ...(snapshot.presentation !== undefined ? { presentation: snapshot.presentation } : {}),
+        ...(snapshot.sampling !== undefined ? { sampling: snapshot.sampling } : {}),
+    };
+}
 function editedValueFor(item, state) {
     return state.decisionsByItemName[item.metadata.name] === "accept-proposed" ? state.editedValuesByItemName?.[item.metadata.name] : undefined;
 }
@@ -95,8 +139,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,43 +160,57 @@ 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)}%` : "—";
+    const blind = isScoreBlind(current);
+    const confHtml = (c) => blind ? "" : `<div class="conf">confidence ${confStr(c)}</div>`;
     const currentValue = valueStr(currentCandidate?.value ?? "—");
-    const currentConf = confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
+    const currentConf = confHtml(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
     const currentSource = currentCandidate?.source?.sourceRef ?? "—";
     const currentExcerpt = currentCandidate?.locator?.excerpt ?? "";
     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>
+    ${confHtml(candidate?.extraction?.confidence ?? candidate?.confidence)}
     <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 verificationNotes = candidateVerificationNotes(item, editedValueFor(item, current));
+    const itemPresentation = buildReviewItemPresentation(item);
+    const excludedNote = excludedProposalsSentence(itemPresentation.excludedProposals);
+    const unreadableNote = excludedProposalsUnreadableSentence(itemPresentation.excludedProposalsUnreadable);
+    const verificationNotes = blind ? [] : 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 +288,16 @@ 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>` : ""}
+${blind ? `<p class="notice" id="score-blind-note">${escapeHtml(scoreBlindLines(current)[0])}</p>` : ""}
 <p class="eyebrow">Survey Review</p>
 <h1>${escapeHtml(item.spec.target)}</h1>
 <div class="meta">
@@ -244,15 +311,18 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
   <div class="card">
     <div class="card-label">Current</div>
     <div class="value">${currentValue.includes("\n") ? `<pre>${escapeHtml(currentValue)}</pre>` : escapeHtml(currentValue)}</div>
-    <div class="conf">confidence ${currentConf}</div>
+    ${currentConf}
     <div class="source-ref">${escapeHtml(currentSource)}</div>
     ${currentExcerpt ? `<div class="excerpt">${escapeHtml(currentExcerpt)}</div>` : ""}
   </div>
   ${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 +342,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 +357,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 +394,22 @@ ${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,
+        ...sessionConditions(snapshot),
         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 +421,30 @@ 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 blind = isScoreBlind(current);
     const itemData = {
+        queueAttestation: attestation.state,
+        ...sessionConditions(snapshot),
         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,19 +452,21 @@ 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: (() => {
-            const notes = candidateVerificationNotes(item, editedValueFor(item, current));
+            const notes = blind ? [] : candidateVerificationNotes(item, editedValueFor(item, current));
             return item.spec.candidates.map((c, index) => {
                 const note = notes.find((entry) => entry.candidateIndex === index);
                 return {
                     id: c.id,
                     role: c.role,
                     value: c.value,
-                    confidence: c.extraction?.confidence ?? c.confidence,
+                    ...(blind ? {} : { 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 +476,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 +502,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 +531,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 +560,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 +598,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 +620,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 +672,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 +696,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,7 +200,43 @@ 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[];
+    /**
+     * The presentation of the session the decision was made in, copied from the
+     * session (never supplied by the reviewer). `{ scoreBlind: true }` means the
+     * reviewer saw no confidence and no verifier result before deciding.
+     * Absent on decisions from sessions that declare none.
+     */
+    presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen, copied from the session. */
+    sampling?: ReviewSessionSampling;
 }
+/**
+ * How a session presents items to its reviewer, fixed by the session (never
+ * by the reviewer). `scoreBlind` hides every proposer confidence and every
+ * verifier result on every decision surface for the whole session, so the
+ * decision is made without them.
+ */
+export interface ReviewSessionPresentation {
+    readonly scoreBlind: boolean;
+}
+/**
+ * How the session's items were chosen: the ordinary review `queue`, or a
+ * seeded `random-audit` draw at `rate` (see `drawRandomAuditSample`).
+ */
+export type ReviewSessionSampling = {
+    readonly kind: "queue";
+} | {
+    readonly kind: "random-audit";
+    readonly rate: number;
+    readonly seed: 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",