@kontourai/survey 4.0.0 → 5.0.0

package/dist/src/index.d.ts

@@ -2,13 +2,13 @@ export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, Escalati
 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, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.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 type { BindReviewQueueOptions, ReviewQueueBinding, ReviewQueueBindingIssue, ReviewQueueBindingIssueCode, ReviewQueueExtractionIssue, ReviewQueueExtractionIssueCode, ValidateReviewQueueBindingOptions, } from "./review-workbench/queue-binding.js";
 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, PortableExtractionEvidenceMatch, PortableExtractionOccurrence, PortableExtractionProducedBy, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
+export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionCoverageEntry, PortableExtractionEvidenceMatch, PortableExtractionPartialReason, 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";

package/dist/src/index.js

@@ -1,7 +1,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, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.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 { resolvePortablePdfRegion } from "./pdf-layout.js";
 export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";

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

@@ -3,7 +3,7 @@ import { resolve, dirname } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
-import { buildReviewSessionEvents, currentReviewItem, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
+import { buildReviewSessionEvents, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
 import { appendReviewSessionEvents, readReviewSessionFile, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 const SESSION_NAME = "mcp-review-session";
@@ -53,7 +53,7 @@ function itemDetailText(item, snapshot, events) {
     const decision = current.decisionsByItemName[item.metadata.name];
     const note = current.notesByItemName[item.metadata.name];
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
-    const proposedCandidate = item.spec.candidates.find((c) => c.role === "proposed");
+    const proposedCandidates = item.spec.candidates.filter((c) => c.role === "proposed");
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "unknown";
     const lines = [
@@ -69,10 +69,15 @@ function itemDetailText(item, snapshot, events) {
         `  source: ${currentCandidate?.source?.sourceRef ?? "none"}`,
         ...(currentCandidate?.locator?.excerpt ? [`  excerpt: ${currentCandidate.locator.excerpt}`] : []),
         ``,
-        `Proposed value: ${valueStr(proposedCandidate?.value ?? "(none)")}`,
-        `  confidence: ${confStr(proposedCandidate?.extraction?.confidence ?? proposedCandidate?.confidence)}`,
-        `  source: ${proposedCandidate?.source?.sourceRef ?? "none"}`,
-        ...(proposedCandidate?.locator?.excerpt ? [`  excerpt: ${proposedCandidate.locator.excerpt}`] : []),
+        ...(proposedCandidates.length > 1
+            ? [`Conflict: ${proposedCandidates.length} proposed values. Accept is refused; reject them all or use could-not-confirm with a reason.`]
+            : []),
+        ...(proposedCandidates.length === 0 ? [`Proposed value: (none)`] : proposedCandidates.flatMap((candidate) => [
+            `Proposed value: ${valueStr(candidate.value)}`,
+            `  confidence: ${confStr(candidate.extraction?.confidence ?? candidate.confidence)}`,
+            `  source: ${candidate.source?.sourceRef ?? "none"}`,
+            ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
+        ])),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
@@ -99,19 +104,32 @@ function buildReviewCardHtml(item, snapshot, events) {
     const total = current.items.length;
     const resolved = total - summary.unresolved;
     const currentCandidate = item.spec.candidates.find((c) => c.role === "current");
-    const proposedCandidate = item.spec.candidates.find((c) => c.role === "proposed");
+    const proposedCandidates = item.spec.candidates.filter((c) => c.role === "proposed");
+    // Several proposed values are a conflict: every value is shown, and accept
+    // (which names a role, not a value) is not offered.
+    const conflict = proposedCandidates.length > 1;
     const decision = current.decisionsByItemName[item.metadata.name];
     const status = deriveQueueRowStatus(item, current);
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v, null, 2);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "—";
     const currentValue = valueStr(currentCandidate?.value ?? "—");
-    const proposedValue = valueStr(proposedCandidate?.value ?? "—");
     const currentConf = confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
-    const proposedConf = confStr(proposedCandidate?.extraction?.confidence ?? proposedCandidate?.confidence);
     const currentSource = currentCandidate?.source?.sourceRef ?? "—";
-    const proposedSource = proposedCandidate?.source?.sourceRef ?? "—";
     const currentExcerpt = currentCandidate?.locator?.excerpt ?? "";
-    const proposedExcerpt = proposedCandidate?.locator?.excerpt ?? "";
+    const proposedCard = (candidate, label) => {
+        const value = valueStr(candidate?.value ?? "—");
+        const excerpt = candidate?.locator?.excerpt ?? "";
+        return `<div class="card is-proposed">
+    <div class="card-label">${escapeHtml(label)}</div>
+    <div class="value">${value.includes("\n") ? `<pre>${escapeHtml(value)}</pre>` : escapeHtml(value)}</div>
+    <div class="conf">confidence ${confStr(candidate?.extraction?.confidence ?? candidate?.confidence)}</div>
+    <div class="source-ref">${escapeHtml(candidate?.source?.sourceRef ?? "—")}</div>
+    ${excerpt ? `<div class="excerpt">${escapeHtml(excerpt)}</div>` : ""}
+  </div>`;
+    };
+    const proposedCards = conflict
+        ? proposedCandidates.map((candidate, index) => proposedCard(candidate, `Proposed ${index + 1} of ${proposedCandidates.length}`)).join("\n  ")
+        : proposedCard(proposedCandidates[0], "Proposed");
     const itemNameJson = escapeJsonInHtml(item.metadata.name);
     const decisionBadge = decision
         ? `<span class="badge badge-${decision === "accept-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(workbenchDecisionDefinitions[decision].label)}</span>`
@@ -200,6 +218,7 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 <div class="meta">
   <span>${escapeHtml(item.metadata.name)}</span>
   ${decisionBadge}
+  ${conflict ? `<span class="badge badge-hold" id="conflict-badge">Conflict: ${proposedCandidates.length} values</span>` : ""}
   <span class="progress">${resolved}/${total} resolved</span>
 </div>
 
@@ -211,14 +230,9 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
     <div class="source-ref">${escapeHtml(currentSource)}</div>
     ${currentExcerpt ? `<div class="excerpt">${escapeHtml(currentExcerpt)}</div>` : ""}
   </div>
-  <div class="card is-proposed">
-    <div class="card-label">Proposed</div>
-    <div class="value">${proposedValue.includes("\n") ? `<pre>${escapeHtml(proposedValue)}</pre>` : escapeHtml(proposedValue)}</div>
-    <div class="conf">confidence ${proposedConf}</div>
-    <div class="source-ref">${escapeHtml(proposedSource)}</div>
-    ${proposedExcerpt ? `<div class="excerpt">${escapeHtml(proposedExcerpt)}</div>` : ""}
-  </div>
+  ${proposedCards}
 </div>
+${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length} different values were proposed. This card cannot choose one of them yet: reject them all, or use Could not confirm with a reason.</p>` : ""}
 
 <div class="divider"></div>
 
@@ -226,9 +240,9 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 <textarea class="note-input" id="note" placeholder="Add a rationale for this decision...">${escapeHtml(current.notesByItemName[item.metadata.name] ?? "")}</textarea>
 
 <div class="btn-row">
-  <button class="btn btn-accept${decision === "accept-proposed" ? " active" : ""}" id="btn-accept">Accept proposed</button>
-  <button class="btn btn-hold${decision === "keep-current" ? " active" : ""}" id="btn-hold">Hold / Keep current</button>
-  <button class="btn btn-reject${decision === "reject-proposed" ? " active" : ""}" id="btn-reject">Reject proposed</button>
+  ${conflict ? "" : `<button class="btn btn-accept${decision === "accept-proposed" ? " active" : ""}" id="btn-accept">Accept proposed</button>`}
+  ${currentCandidate ? `<button class="btn btn-hold${decision === "keep-current" ? " active" : ""}" id="btn-hold">Hold / Keep current</button>` : ""}
+  <button class="btn btn-reject${decision === "reject-proposed" ? " active" : ""}" id="btn-reject">${conflict ? "Reject all values" : "Reject proposed"}</button>
   <button class="btn btn-unconfirmed${decision === "could-not-confirm" ? " active" : ""}" id="btn-unconfirmed">Could not confirm</button>
 </div>
 <div class="feedback" id="feedback"></div>
@@ -259,8 +273,10 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
     return true;
   }
 
-  document.getElementById('btn-accept').addEventListener('click', function () { postDecision('accept'); document.getElementById('feedback').textContent = 'Submitting accept…'; });
-  document.getElementById('btn-hold').addEventListener('click', function () { postDecision('hold'); document.getElementById('feedback').textContent = 'Submitting hold…'; });
+  var acceptButton = document.getElementById('btn-accept');
+  if (acceptButton) acceptButton.addEventListener('click', function () { postDecision('accept'); document.getElementById('feedback').textContent = 'Submitting accept…'; });
+  var holdButton = document.getElementById('btn-hold');
+  if (holdButton) holdButton.addEventListener('click', function () { postDecision('hold'); document.getElementById('feedback').textContent = 'Submitting hold…'; });
   document.getElementById('btn-reject').addEventListener('click', function () { postDecision('reject'); document.getElementById('feedback').textContent = 'Submitting reject…'; });
   document.getElementById('btn-unconfirmed').addEventListener('click', function () { if (postDecision('could-not-confirm')) document.getElementById('feedback').textContent = 'Submitting could not confirm…'; });
 
@@ -421,9 +437,10 @@ async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, optio
     const itemText = updatedItem ? itemDetailText(updatedItem, snapshot, newEvents) : `Item: ${itemName}`;
     const remainingText = queueSummaryText(snapshot, newEvents);
     const definition = workbenchDecisionDefinitions[wbDecision];
+    const conflictRejected = wbDecision === "reject-proposed" && updatedItem !== undefined && decisionSelectsNoCandidate(updatedItem, wbDecision);
     const text = [
-        `Decision recorded: ${definition.label}`,
-        `Effect: ${definition.effect}`,
+        `Decision recorded: ${conflictRejected ? "Reject all values" : definition.label}`,
+        `Effect: ${conflictRejected ? "Every proposed value is rejected; none becomes the claim's value." : definition.effect}`,
         "",
         itemText,
         "",

package/dist/src/review-workbench/extraction-inspector.d.ts

@@ -1,4 +1,4 @@
-import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import { type ExtractionEnvelopeImportDiagnostic, type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
 import { type PortablePdfRegionContext } from "../pdf-layout.js";
 export type ExtractionAlignmentState = "aligned" | "excerpt-mismatch" | "artifact-unavailable" | "digest-mismatch";
 export type ArtifactUnavailableCode = "not-found" | "storage-error" | "access-denied" | "invalid-artifact" | "unknown";
@@ -89,6 +89,14 @@ export interface ExtractionInspectorSource {
     artifactText?: string;
     ocrDerived?: true;
     alignment: ExtractionAlignmentState;
+    /**
+     * Present when the extraction failed, or stopped short without proposing
+     * anything: the import's `extraction-failed` / `extraction-incomplete`
+     * diagnostic. An empty source with this set is not a run that found nothing.
+     */
+    extractionDiagnostic?: Extract<ExtractionEnvelopeImportDiagnostic, {
+        kind: "extraction-failed" | "extraction-incomplete";
+    }>;
     message: string;
 }
 export interface ExtractionInspectorModel {
@@ -146,6 +154,12 @@ export interface ExtractionInspectorMountOptions {
  * and fails closed if mutable caller data has drifted since import.
  */
 export declare function buildExtractionInspectorModel(input: ExtractionInspectorInput): BuiltExtractionInspectorModel;
+/**
+ * The posture a source is shown with: the extraction's own failure or early
+ * stop when there is one, otherwise the artifact alignment. A failed
+ * extraction over an aligned artifact must not show the aligned posture.
+ */
+export declare function inspectorSourcePosture(source: Pick<ExtractionInspectorSource, "alignment" | "extractionDiagnostic">): ExtractionAlignmentState | "extraction-failed" | "extraction-incomplete";
 export declare function filterExtractionInspectorCandidates(model: ExtractionInspectorModel, filters: ExtractionInspectorFilters): ExtractionInspectorCandidate[];
 export declare function exportExtractionInspector(model: ExtractionInspectorModel, options?: ExtractionInspectorExportOptions): string;
 export declare function mountExtractionInspector(container: HTMLElement, model: ExtractionInspectorModel, options?: ExtractionInspectorMountOptions): () => void;

package/dist/src/review-workbench/extraction-inspector.js

@@ -26,14 +26,19 @@ export function buildExtractionInspectorModel(input) {
         if (sourceKeys.has(sourceKey))
             throw new Error("Extraction inspector source identity collision.");
         sourceKeys.add(sourceKey);
-        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.state, entry.artifact, envelope.result.ocrDerived);
+        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.diagnostics, entry.artifact, envelope.result.ocrDerived);
         sources.push(source);
         const candidateStart = candidates.length;
+        const itemByProposalIndex = new Map();
+        for (const item of entry.importResult.reviewItems) {
+            for (const proposalIndex of envelopeItemProposalIndices(item))
+                itemByProposalIndex.set(proposalIndex, item.metadata.name);
+        }
         envelope.result.proposals.forEach((proposal, proposalIndex) => {
-            const item = entry.importResult.reviewItems[proposalIndex];
-            if (!item)
+            const itemName = itemByProposalIndex.get(proposalIndex);
+            if (!itemName)
                 return; // unresolved imports legitimately produce no ReviewItems
-            candidates.push(candidateModel(source, item.metadata.name, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass, envelope.result.pdfPageOffsets, envelope.result.pdfLayout, envelope.result.ocrDerived));
+            candidates.push(candidateModel(source, itemName, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass, envelope.result.pdfPageOffsets, envelope.result.pdfLayout, envelope.result.ocrDerived));
         });
         if (source.alignment === "excerpt-mismatch") {
             delete source.artifactText;
@@ -141,28 +146,53 @@ function assertImportedResult(result, record) {
     if (!record.metadata?.name || !record.metadata.producerNamespace || !record.spec?.envelope?.result || !Array.isArray(record.spec.envelope.result.proposals))
         throw new Error("Malformed extraction import result.");
     const grounded = record.status?.state === "grounded";
-    if ((!grounded && reviewItems.length !== 0) || (grounded && reviewItems.length !== record.spec.envelope.result.proposals.length))
+    const proposals = record.spec.envelope.result.proposals;
+    const covered = reviewItems.flatMap(envelopeItemProposalIndices).sort((left, right) => left - right);
+    if ((!grounded && reviewItems.length !== 0) || (grounded && canonicalJson(covered) !== canonicalJson(proposals.map((_proposal, index) => index))))
         throw new Error("Extraction import ReviewItems do not match its grounding state.");
     const canonicalItems = buildReviewItemsFromExtractionEnvelopeImport(record);
     if (canonicalJson(reviewItems) !== canonicalJson(canonicalItems))
         throw new Error("Extraction import ReviewItems do not match their canonical identities and bindings.");
-    reviewItems.forEach((item, index) => {
-        const proposal = record.spec.envelope.result.proposals[index];
+    reviewItems.forEach((item, itemIndex) => {
         const metadata = item.metadata?.producer?.["survey.kontourai.io/extraction-envelope"];
-        const candidate = item.spec?.candidates?.[0];
-        const binding = candidate?.producer?.["survey.kontourai.io/extraction-envelope"];
-        if (item.kind !== "ReviewItem" || !item.metadata.name || item.spec.candidates.length !== 1
-            || metadata?.importName !== record.metadata.name || binding?.importName !== record.metadata.name
-            || binding.proposalIndex !== index || binding.runId !== record.spec.envelope.result.runId || binding.provider !== record.spec.envelope.result.provider
-            || item.spec.target !== proposal.fieldPath || candidate?.locator?.locator !== proposal.provenance.locator || candidate.locator.excerpt !== proposal.provenance.excerpt) {
-            throw new Error(`Extraction import ReviewItem ${index} is inconsistent with its validated proposal.`);
+        if (item.kind !== "ReviewItem" || !item.metadata.name || item.spec.candidates.length === 0 || metadata?.importName !== record.metadata.name) {
+            throw new Error(`Extraction import ReviewItem ${itemIndex} is inconsistent with its validated proposals.`);
+        }
+        for (const candidate of item.spec.candidates) {
+            const binding = candidate.producer?.["survey.kontourai.io/extraction-envelope"];
+            const proposal = typeof binding?.proposalIndex === "number" ? proposals[binding.proposalIndex] : undefined;
+            if (!proposal || binding?.importName !== record.metadata.name || binding.runId !== record.spec.envelope.result.runId || binding.provider !== record.spec.envelope.result.provider
+                || candidate.extraction.target !== proposal.fieldPath || candidate.locator?.locator !== proposal.provenance.locator || candidate.locator.excerpt !== proposal.provenance.excerpt) {
+                throw new Error(`Extraction import ReviewItem ${itemIndex} is inconsistent with its validated proposals.`);
+            }
         }
     });
 }
-function sourceModel(key, importName, prepared, state, artifact, ocrDerived) {
+/** The proposal indices one imported ReviewItem stands for, as its producer metadata records them. */
+function envelopeItemProposalIndices(item) {
+    const metadata = item.metadata?.producer?.["survey.kontourai.io/extraction-envelope"];
+    const indices = metadata?.proposalIndices;
+    if (!Array.isArray(indices) || indices.length === 0 || !indices.every((index) => Number.isSafeInteger(index) && index >= 0)) {
+        throw new Error(`Extraction import ReviewItem ${item.metadata?.name ?? "(unnamed)"} does not record its proposals.`);
+    }
+    return indices;
+}
+/**
+ * The posture a source is shown with: the extraction's own failure or early
+ * stop when there is one, otherwise the artifact alignment. A failed
+ * extraction over an aligned artifact must not show the aligned posture.
+ */
+export function inspectorSourcePosture(source) {
+    if (source.extractionDiagnostic)
+        return source.extractionDiagnostic.kind;
+    return source.alignment;
+}
+function sourceModel(key, importName, prepared, diagnostics, artifact, ocrDerived) {
     let alignment;
     let message;
-    if (state !== "grounded" || artifact.status === "unavailable") {
+    const artifactUnresolved = diagnostics.some((diagnostic) => diagnostic.kind === "artifact-unavailable" || diagnostic.kind === "digest-mismatch");
+    const extractionDiagnostic = diagnostics.find((diagnostic) => diagnostic.kind === "extraction-failed" || diagnostic.kind === "extraction-incomplete");
+    if (artifactUnresolved || artifact.status === "unavailable") {
         alignment = "artifact-unavailable";
         message = `Prepared artifact unavailable (${artifact.status === "unavailable" ? artifact.code : "invalid-artifact"}). Candidates are not grounded.`;
     }
@@ -177,9 +207,15 @@ function sourceModel(key, importName, prepared, state, artifact, ocrDerived) {
     }
     else {
         alignment = "aligned";
-        message = `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
+        message = extractionDiagnostic
+            ? "Prepared artifact identity verified."
+            : `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
     }
-    return { key, importName, ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), ...(ocrDerived ? { ocrDerived: true } : {}), alignment, message };
+    // The extraction's own failure leads: an aligned artifact with no candidates
+    // must not read as a complete run that found nothing.
+    if (extractionDiagnostic)
+        message = `${extractionDiagnostic.message} ${message}`;
+    return { key, importName, ...(extractionDiagnostic ? { extractionDiagnostic } : {}), ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), ...(ocrDerived ? { ocrDerived: true } : {}), alignment, message };
 }
 function candidateModel(source, reviewItemName, proposal, index, provider, model, attempt, pass, pdfPageOffsets, pdfLayout, ocrDerived) {
     const match = /^chars:(\d+)-(\d+)$/.exec(proposal.provenance.locator);
@@ -270,7 +306,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         next.hidden = pageCount === 1;
         previous.disabled = page === 0;
         next.disabled = page >= pageCount - 1;
-        postures.innerHTML = model.sources.map(s => `<div class="inspector-posture ${s.alignment}" role="status"><strong>${escapeHtml(s.importName)}: ${escapeHtml(s.alignment)}</strong><span>${escapeHtml(s.message)}</span></div>`).join("");
+        postures.innerHTML = model.sources.map(s => { const posture = inspectorSourcePosture(s); return `<div class="inspector-posture ${s.alignment}${posture !== s.alignment ? ` ${posture}` : ""}" role="status" data-posture="${escapeHtml(posture)}"><strong>${escapeHtml(s.importName)}: ${escapeHtml(posture)}</strong><span>${escapeHtml(s.message)}</span></div>`; }).join("");
         sourcesRoot.innerHTML = model.sources.map(s => { const anchored = model.candidates.filter(c => c.sourceKey === s.key); const marked = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `${anchored.map(c => anchorHtml(c, highlightIdFor(c))).join("")}<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, anchored, marked, highlightIdFor)}</pre></div>`; }).join("");
     };
     root.querySelectorAll("select").forEach(select => select.addEventListener("change", event => { event.stopPropagation(); const key = select.dataset.filter; if (select.value)

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

@@ -229,7 +229,7 @@ export function validateReviewQueueAgainstExtractionImport(items, importResult)
     if (record.status.state !== "grounded") {
         return [{
                 code: "import-not-grounded",
-                message: `Extraction import ${record.metadata.name} is ${record.status.state}, not grounded; it cannot attest a review queue.`,
+                message: `Extraction import ${record.metadata.name} is ${record.status.state}, not grounded (${record.status.diagnostics.map((diagnostic) => diagnostic.message).join(" ")}); it cannot attest a review queue.`,
             }];
     }
     if (items.length === 0) {

package/dist/src/review-workbench/review-presentation.d.ts

@@ -57,7 +57,8 @@ export interface ReviewResultPresentation {
     readonly target: string;
     readonly targetLabel: string;
     readonly decisionLabel: string;
-    readonly selectedValueText: string;
+    /** Absent when the decision selects no candidate (reject-all or could-not-confirm on a conflict). */
+    readonly selectedValueText?: string;
     readonly applyMeaning: string;
     readonly reviewItemLink?: ReviewPresentationLink;
     readonly traceRefs: readonly ReviewTraceRef[];

package/dist/src/review-workbench/review-presentation.js

@@ -85,6 +85,28 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
         ? adapter.labelForTarget?.(target, itemContext) ?? humanizeIdentifier(target)
         : humanizeIdentifier(target);
     const selectedCandidate = item ? selectedCandidateForResult(item, result) : undefined;
+    // A decision that selects no candidate presents no selected value and no
+    // selected trace; it names every candidate instead.
+    if (result.selectedCandidateId === undefined) {
+        const rejected = result.decision === "reject-proposed";
+        return {
+            result,
+            item,
+            target,
+            targetLabel,
+            decisionLabel: humanizeIdentifier(result.decision),
+            applyMeaning: rejected
+                ? "Saved decision rejects every proposed value; none is applied"
+                : "Saved decision records that no proposed value could be confirmed; none is applied",
+            reviewItemLink: item && itemContext ? adapter.linkForReviewItem?.(item, itemContext) : undefined,
+            traceRefs: [
+                { label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item", context: undefined },
+                ...result.unselectedCandidates.map((candidate) => ({
+                    label: rejected ? "Rejected candidate" : "Unconfirmed candidate", value: candidate.id, kind: "candidate", context: candidate,
+                })),
+            ].flatMap(({ context, ...ref }) => (item ? withTraceLinks([ref], { item, candidate: context }, adapter) : [ref])),
+        };
+    }
     return {
         result,
         item,
@@ -168,7 +190,7 @@ function traceRefsForCandidate(item, candidate, adapter) {
 function traceRefsForResult(item, result, selectedCandidate, adapter) {
     return withTraceLinks([
         { label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" },
-        { label: "Selected candidate", value: result.selectedCandidateId, kind: "candidate" },
+        { label: "Selected candidate", value: result.selectedCandidateId ?? "none", kind: "candidate" },
         {
             label: "Selected claim",
             value: selectedCandidate?.claimTarget.claimId ?? "not provided",

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

@@ -94,15 +94,29 @@ export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boole
 /**
  * The candidate a workbench decision applies to.
  *
- * Selection is by role, but the id this returns is what every caller makes
- * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
- * replay expectation. So the id has to name exactly one candidate before it
- * leaves here. Guarding the render path alone let the workbench emit an
- * undecidable decision through the export path and then present a different
+ * Selection is by role, so the role has to name exactly one candidate before a
+ * decision may trust it. Guarding the render path alone let the workbench emit
+ * an undecidable decision through the export path and then present a different
  * candidate's value against it; this is the shared selector all of those go
  * through, which is why the check belongs here rather than at each of them.
+ *
+ * A decision that would make one of several candidates in its role the trusted
+ * value is refused: picking the first would settle the conflict for the
+ * reviewer without showing it. A value-neutral decision (reject, could not
+ * confirm) on such an item selects none of them. It still returns the first
+ * candidate so in-process callers that need one candidate (rendering, the
+ * in-memory `ReviewWorkbenchResult`) have one, but that anchor is not recorded:
+ * {@link decisionCandidateId} is `undefined` for it, so the decision, its
+ * session events and the canonical projection name no candidate.
  */
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
+/** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
+export declare function decisionSelectsNoCandidate(item: ReviewItem, decision: ReviewWorkbenchDecision): boolean;
+/**
+ * The candidate id a decision records: the selected candidate's, or
+ * `undefined` when the decision selects no candidate.
+ */
+export declare function decisionCandidateId(item: ReviewItem, decision: ReviewWorkbenchDecision): string | undefined;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline
  * edit when one was made for an accept-proposed decision, otherwise the selected

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

@@ -143,32 +143,65 @@ export function reviewSessionSummary(session) {
  * would invent a prior value, with provenance, that the source never had.
  */
 export function keepActionDecision(item, flaggedWrong) {
-    const hasRole = (role) => item.spec.candidates.some((candidate) => candidate.role === role);
-    if (flaggedWrong || !hasRole("current")) {
-        return hasRole("proposed") ? "reject-proposed" : undefined;
+    // Keeping the current value is recordable only when exactly one candidate is
+    // current (see candidateForDecision); rejecting the proposed values is
+    // recordable however many there are.
+    const count = (role) => item.spec.candidates.filter((candidate) => candidate.role === role).length;
+    if (flaggedWrong || count("current") === 0) {
+        return count("proposed") > 0 ? "reject-proposed" : undefined;
     }
-    return "keep-current";
+    return count("current") === 1 ? "keep-current" : undefined;
 }
+/**
+ * Decisions that make no candidate the trusted value: rejecting the proposed
+ * values and ending the round as could-not-confirm. On an item whose role holds
+ * several candidates (conflicting values for one claim) they select none of them.
+ */
+const VALUE_NEUTRAL_DECISIONS = new Set(["reject-proposed", "could-not-confirm"]);
 /**
  * The candidate a workbench decision applies to.
  *
- * Selection is by role, but the id this returns is what every caller makes
- * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
- * replay expectation. So the id has to name exactly one candidate before it
- * leaves here. Guarding the render path alone let the workbench emit an
- * undecidable decision through the export path and then present a different
+ * Selection is by role, so the role has to name exactly one candidate before a
+ * decision may trust it. Guarding the render path alone let the workbench emit
+ * an undecidable decision through the export path and then present a different
  * candidate's value against it; this is the shared selector all of those go
  * through, which is why the check belongs here rather than at each of them.
+ *
+ * A decision that would make one of several candidates in its role the trusted
+ * value is refused: picking the first would settle the conflict for the
+ * reviewer without showing it. A value-neutral decision (reject, could not
+ * confirm) on such an item selects none of them. It still returns the first
+ * candidate so in-process callers that need one candidate (rendering, the
+ * in-memory `ReviewWorkbenchResult`) have one, but that anchor is not recorded:
+ * {@link decisionCandidateId} is `undefined` for it, so the decision, its
+ * session events and the canonical projection name no candidate.
  */
 export function candidateForDecision(item, decision) {
     const definition = workbenchDecisionDefinitions[decision];
-    const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);
+    const matches = item.spec.candidates.filter((entry) => entry.role === definition.candidateRole);
+    const candidate = matches[0];
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no ${definition.candidateRole} candidate.`);
     }
+    if (matches.length > 1 && !VALUE_NEUTRAL_DECISIONS.has(decision)) {
+        throw new Error(`ReviewItem ${item.metadata.name} has ${matches.length} ${definition.candidateRole} candidates; the ${decision} decision cannot choose between them.`);
+    }
     assertSoleCandidateId(item, candidate.id);
     return candidate;
 }
+/** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
+export function decisionSelectsNoCandidate(item, decision) {
+    const role = workbenchDecisionDefinitions[decision].candidateRole;
+    return VALUE_NEUTRAL_DECISIONS.has(decision) && item.spec.candidates.filter((entry) => entry.role === role).length > 1;
+}
+/**
+ * The candidate id a decision records: the selected candidate's, or
+ * `undefined` when the decision selects no candidate.
+ */
+export function decisionCandidateId(item, decision) {
+    const candidate = candidateForDecision(item, decision);
+    return decisionSelectsNoCandidate(item, decision) ? undefined : candidate.id;
+}
 /**
  * The value that should actually be applied for a decision: the reviewer's inline
  * edit when one was made for an accept-proposed decision, otherwise the selected
@@ -254,7 +287,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
         if (decision === "could-not-confirm" && !note?.trim()) {
             throw new Error(`ReviewItem ${item.metadata.name} could not confirm requires a non-empty reason.`);
         }
-        const candidate = candidateForDecision(item, decision);
+        const candidateId = decisionCandidateId(item, decision);
         const definition = workbenchDecisionDefinitions[decision];
         const reviewDecisionName = `${item.metadata.name}-${decision}`;
         // Carry the reviewer's inline edit in the event itself (accept-proposed
@@ -284,7 +317,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             occurredAt: session.reviewedAt,
             reviewItemName: item.metadata.name,
             reviewDecisionName,
-            candidateId: candidate.id,
+            ...(candidateId !== undefined ? { candidateId } : {}),
             status: definition.status,
             ...(decision === "could-not-confirm"
                 ? {
@@ -302,7 +335,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             occurredAt: session.reviewedAt,
             reviewItemName: item.metadata.name,
             reviewDecisionName,
-            candidateId: candidate.id,
+            ...(candidateId !== undefined ? { candidateId } : {}),
             status: definition.status,
             rationale: note,
             ...(decision === "could-not-confirm"

package/dist/src/review-workbench/review-session-replay.js

@@ -1,4 +1,4 @@
-import { candidateForDecision, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, decisionSelectsNoCandidate, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { checkEditedValueForItem } from "./edited-value.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
@@ -56,17 +56,19 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
             else if (itemName && itemsByName.has(itemName)) {
                 const item = itemsByName.get(itemName);
                 const expectedCandidate = item ? candidateForDecision(item, decision) : undefined;
+                // A decision that selects no candidate must reference none.
+                const expectedCandidateId = item && !decisionSelectsNoCandidate(item, decision) ? expectedCandidate?.id : undefined;
                 const expectedStatus = workbenchDecisionDefinitions[decision].status;
                 const referencedCandidateExists = event.spec.candidateId
                     ? item?.spec.candidates.some((candidate) => candidate.id === event.spec.candidateId)
                     : false;
-                if (expectedCandidate && (!event.spec.candidateId || referencedCandidateExists) && event.spec.candidateId !== expectedCandidate.id) {
+                if (expectedCandidate && (!event.spec.candidateId || referencedCandidateExists) && event.spec.candidateId !== expectedCandidateId) {
                     issues.push({
                         ...eventRef,
                         code: "decision-candidate-mismatch",
                         reviewItemName: itemName,
                         candidateId: event.spec.candidateId,
-                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects candidate ${expectedCandidate.id}, but references ${event.spec.candidateId ?? "no candidate"}.`,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects ${expectedCandidateId ? `candidate ${expectedCandidateId}` : "no candidate"}, but references ${event.spec.candidateId ?? "no candidate"}.`,
                     });
                 }
                 if (event.spec.status !== expectedStatus) {

package/dist/src/review-workbench/review-workbench-css.generated.js

@@ -247,6 +247,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .inspector-heading h2{ margin: 0; }
 .survey-workbench-embed .inspector-posture{ display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
 .survey-workbench-embed .inspector-posture.digest-mismatch, .survey-workbench-embed .inspector-posture.artifact-unavailable, .survey-workbench-embed .inspector-posture.excerpt-mismatch{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-failed{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-incomplete{ background: var(--k-caution-wash); color: var(--k-caution); border: 2px solid currentColor; }
 .survey-workbench-embed .inspector-filters{ display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .survey-workbench-embed .inspector-filters label{ display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
 .survey-workbench-embed .inspector-filters select, .survey-workbench-embed .inspector-filters input{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }

package/dist/src/review-workbench/review-workbench.css

@@ -244,6 +244,8 @@
 .survey-workbench-embed .inspector-heading h2{ margin: 0; }
 .survey-workbench-embed .inspector-posture{ display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
 .survey-workbench-embed .inspector-posture.digest-mismatch, .survey-workbench-embed .inspector-posture.artifact-unavailable, .survey-workbench-embed .inspector-posture.excerpt-mismatch{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-failed{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-incomplete{ background: var(--k-caution-wash); color: var(--k-caution); border: 2px solid currentColor; }
 .survey-workbench-embed .inspector-filters{ display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .survey-workbench-embed .inspector-filters label{ display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
 .survey-workbench-embed .inspector-filters select, .survey-workbench-embed .inspector-filters input{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }