@kontourai/survey 4.0.0 → 6.0.0

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

@@ -3,8 +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, 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 { buildReviewItemPresentation, excludedProposalsSentence } 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";
@@ -53,7 +54,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,16 +70,31 @@ 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}`] : []),
+        ])),
+        ...extractionImportLines(item),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
     }
     return lines.join("\n");
 }
+/** What an envelope import says about the item's evidence, including rival values it excluded. */
+function extractionImportLines(item) {
+    const presentation = buildReviewItemPresentation(item);
+    const excluded = excludedProposalsSentence(presentation.excludedProposals);
+    return [
+        ...(excluded ? [``, `Excluded: ${excluded} Check the source before accepting.`] : []),
+        ...(presentation.excerptVerification ? [``, `Excerpts ${presentation.excerptVerification === "verified" ? "were" : "were not"} checked against the prepared source text at import.`] : []),
+    ];
+}
 // ---- UI card -------------------------------------------------------------
 function escapeJsonInHtml(value) {
     return JSON.stringify(value)
@@ -99,20 +115,34 @@ 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 excludedNote = excludedProposalsSentence(buildReviewItemPresentation(item).excludedProposals);
     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-pending">${escapeHtml(status)}</span>`;
@@ -200,6 +230,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 +242,10 @@ 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>
+${excludedNote ? `<p class="feedback" id="excluded-note">${escapeHtml(excludedNote)}</p>` : ""}
+${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 +253,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 +286,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…'; });
 
@@ -323,6 +352,13 @@ async function toolItem(itemName, options) {
         decision: current.decisionsByItemName[item.metadata.name],
         note: current.notesByItemName[item.metadata.name],
         candidateSetStatus: item.spec.candidateSetStatus,
+        ...(() => {
+            const presentation = buildReviewItemPresentation(item);
+            return {
+                ...(presentation.excerptVerification ? { excerptVerification: presentation.excerptVerification } : {}),
+                ...(presentation.excludedProposals.length ? { excludedProposals: presentation.excludedProposals.map(({ proposalIndex, value, locator, excerpt }) => ({ proposalIndex, value, locator, excerpt })) } : {}),
+            };
+        })(),
         candidates: item.spec.candidates.map((c) => ({
             id: c.id,
             role: c.role,
@@ -421,9 +457,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/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", "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", "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

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

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

@@ -1,18 +1,7 @@
-import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import { type ExtractionEnvelopeImportDiagnostic, type ExtractionEnvelopeImportResult, type ResolvedExtractionArtifact } 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";
-export type ResolvedExtractionArtifact = {
-    status: "available";
-    text: string;
-    actualDigest: string;
-} | {
-    status: "unavailable";
-    code: ArtifactUnavailableCode;
-} | {
-    status: "digest-mismatch";
-    actualDigest: string;
-};
+export type { ArtifactUnavailableCode, ResolvedExtractionArtifact } from "../extraction-envelope.js";
 export interface ExtractionInspectorEntry {
     /** Result returned by importExtractionEnvelope; includes authoritative ReviewItem identities. */
     importResult: ExtractionEnvelopeImportResult;
@@ -89,6 +78,29 @@ 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";
+    }>;
+    /**
+     * Whether the import checked excerpts against the prepared artifact
+     * (`status.provenance`; a record without it is `unverified`). Always set by
+     * {@link buildExtractionInspectorModel}; optional for hand-authored models.
+     */
+    importProvenance?: "verified" | "unverified";
+    /**
+     * Proposals the import left out because the prepared text at their span is
+     * not their excerpt. They have no candidate row; this is where they are shown.
+     */
+    excludedProposals?: Array<{
+        proposalIndex: number;
+        field: string;
+        locator: string;
+    }>;
     message: string;
 }
 export interface ExtractionInspectorModel {
@@ -146,6 +158,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" | "excludedProposals">): ExtractionAlignmentState | "extraction-failed" | "extraction-incomplete" | "proposals-excluded";
 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

@@ -1,6 +1,5 @@
-import { buildReviewItemsFromExtractionEnvelopeImport, validateExtractionEnvelopeImport } from "../extraction-envelope.js";
+import { assertResolvedExtractionArtifact, buildReviewItemsFromExtractionEnvelopeImport, checkPreparedArtifact, excerptMismatchProposalIndices, proposalSpanMatches, validateExtractionEnvelopeImport } from "../extraction-envelope.js";
 import { canonicalJson } from "./canonical.js";
-import { sha256Hex } from "../sha256.js";
 import { resolvePortablePdfRegion, } from "../pdf-layout.js";
 /**
  * Build a read-only view from one or more results already produced by Survey's
@@ -19,21 +18,26 @@ export function buildExtractionInspectorModel(input) {
             throw new Error("Invalid extraction import result.");
         const record = validateExtractionEnvelopeImport(entry.importResult.record);
         assertImportedResult(entry.importResult, record);
-        assertResolvedArtifact(entry.artifact);
+        assertResolvedExtractionArtifact(entry.artifact);
         const envelope = record.spec.envelope;
         const prepared = envelope.result.preparedArtifact;
         const sourceKey = `${record.metadata.producerNamespace}:${record.metadata.name}:${entryIndex}`;
         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, envelope.result.proposals, record.status.provenance ?? "unverified");
         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;
@@ -113,25 +117,6 @@ function resolveHighlightElementIds(model) {
     }
     return resolved;
 }
-function assertResolvedArtifact(artifact) {
-    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
-        throw new Error("Invalid resolved extraction artifact.");
-    const keys = Object.keys(artifact).sort();
-    if (artifact.status === "available") {
-        if (keys.join(",") !== "actualDigest,status,text" || typeof artifact.text !== "string" || !/^[a-f0-9]{64}$/.test(artifact.actualDigest))
-            throw new Error("Invalid available extraction artifact.");
-    }
-    else if (artifact.status === "digest-mismatch") {
-        if (keys.join(",") !== "actualDigest,status" || !/^[a-f0-9]{64}$/.test(artifact.actualDigest))
-            throw new Error("Invalid digest-mismatch extraction artifact.");
-    }
-    else if (artifact.status === "unavailable") {
-        if (keys.join(",") !== "code,status" || !["not-found", "storage-error", "access-denied", "invalid-artifact", "unknown"].includes(artifact.code))
-            throw new Error("Invalid unavailable extraction artifact.");
-    }
-    else
-        throw new Error("Invalid resolved extraction artifact status.");
-}
 function assertImportedResult(result, record) {
     if (!result || typeof result !== "object" || !result.record || !Array.isArray(result.reviewItems))
         throw new Error("Invalid extraction import result.");
@@ -141,45 +126,90 @@ 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);
+    const excluded = excerptMismatchProposalIndices(record);
+    const expectedCovered = proposals.map((_proposal, index) => index).filter((index) => !excluded.has(index));
+    if ((!grounded && reviewItems.length !== 0) || (grounded && canonicalJson(covered) !== canonicalJson(expectedCovered)))
         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) {
+    // Dropped proposals are a loss of evidence: they lead over an aligned
+    // artifact and over an extraction that merely stopped short.
+    if (source.alignment === "aligned" && source.excludedProposals?.length && source.extractionDiagnostic?.kind !== "extraction-failed")
+        return "proposals-excluded";
+    if (source.extractionDiagnostic)
+        return source.extractionDiagnostic.kind;
+    return source.alignment;
+}
+function sourceModel(key, importName, prepared, diagnostics, artifact, ocrDerived, proposals, importProvenance) {
     let alignment;
     let message;
-    if (state !== "grounded" || artifact.status === "unavailable") {
+    const artifactUnresolved = diagnostics.some((diagnostic) => diagnostic.kind === "artifact-unavailable" || diagnostic.kind === "digest-mismatch");
+    const excludedProposals = diagnostics.flatMap((diagnostic) => diagnostic.kind === "excerpt-mismatch"
+        ? [{ proposalIndex: diagnostic.proposalIndex, field: proposals[diagnostic.proposalIndex]?.fieldPath ?? "", locator: diagnostic.locator }]
+        : []);
+    const extractionDiagnostic = diagnostics.find((diagnostic) => diagnostic.kind === "extraction-failed" || diagnostic.kind === "extraction-incomplete");
+    const check = checkPreparedArtifact(prepared, artifact);
+    if (artifactUnresolved || check.status === "unavailable") {
         alignment = "artifact-unavailable";
-        message = `Prepared artifact unavailable (${artifact.status === "unavailable" ? artifact.code : "invalid-artifact"}). Candidates are not grounded.`;
+        message = `Prepared artifact unavailable (${check.status === "unavailable" ? check.code : "invalid-artifact"}). Candidates are not grounded.`;
     }
-    else if (artifact.status === "digest-mismatch" || !prepared || artifact.actualDigest !== prepared.digest
-        || sha256Hex(artifact.text) !== artifact.actualDigest) {
+    else if (check.status === "digest-mismatch") {
         alignment = "digest-mismatch";
         message = "Prepared artifact digest does not match the extraction artifact. Candidates are not grounded.";
     }
-    else if (artifact.text.length !== prepared.contentLength) {
+    else if (check.status === "wrong-length") {
         alignment = "artifact-unavailable";
         message = "Prepared artifact content has the wrong length. Candidates are not grounded.";
     }
     else {
         alignment = "aligned";
-        message = `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
+        message = extractionDiagnostic || excludedProposals.length
+            ? "Prepared artifact identity verified."
+            : `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
+    }
+    if (excludedProposals.length) {
+        const named = excludedProposals.map((p) => `#${p.proposalIndex} ${p.field} (${p.locator})`).join(", ");
+        message = `${excludedProposals.length} proposal${excludedProposals.length === 1 ? " was" : "s were"} excluded at import because the prepared text at the span is not the excerpt: ${named}. ${message}`;
     }
-    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 };
+    message = `${message} ${importProvenance === "verified" ? "Excerpts were checked against the prepared artifact at import." : "Excerpts were not checked against the prepared artifact at import."}`;
+    // 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, importProvenance, ...(excludedProposals.length ? { excludedProposals } : {}), ...(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);
@@ -188,10 +218,10 @@ function candidateModel(source, reviewItemName, proposal, index, provider, model
     const start = Number(match[1]), end = Number(match[2]);
     if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start)
         throw new Error(`Extraction proposal ${index} has an invalid text span.`);
-    const alignment = source.alignment === "aligned" && source.artifactText.slice(start, end) !== proposal.provenance.excerpt ? "excerpt-mismatch" : source.alignment;
+    const alignment = source.alignment === "aligned" && !proposalSpanMatches(source.artifactText, proposal) ? "excerpt-mismatch" : source.alignment;
     if (alignment === "excerpt-mismatch") {
         source.alignment = alignment;
-        source.message = "One or more source spans do not match their recorded excerpts. Affected candidates are not grounded.";
+        source.message = `One or more source spans do not match their recorded excerpts. Affected candidates are not grounded.${source.importProvenance === "unverified" ? " Excerpts were not checked against the prepared artifact at import." : ""}`;
     }
     let pdfRegion = pdfLayout ? resolvePortablePdfRegion(pdfLayout, proposal.provenance.locator) : undefined;
     const page = resolvePdfPage(pdfPageOffsets, start);
@@ -270,7 +300,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); const classes = [...new Set([s.alignment, s.extractionDiagnostic?.kind, s.excludedProposals?.length ? "proposals-excluded" : undefined, posture].filter(Boolean))].join(" "); return `<div class="inspector-posture ${classes}" 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

@@ -50,6 +50,25 @@ export interface ReviewItemPresentation {
     readonly reviewItemLink?: ReviewPresentationLink;
     readonly traceRefs: readonly ReviewTraceRef[];
     readonly candidates: readonly ReviewCandidatePresentation[];
+    /**
+     * Proposals for this claim that an envelope import left out because the
+     * source text at their cited span is not their excerpt. Unverifiable, not
+     * disproven: every decision surface shows them. Empty for other items.
+     */
+    readonly excludedProposals: readonly ExcludedProposalPresentation[];
+    /**
+     * For an envelope-imported item, whether its import checked excerpts
+     * against the prepared artifact. Absent for other items, and for an item
+     * whose envelope binding is missing, which cannot claim either.
+     */
+    readonly excerptVerification?: "verified" | "unverified";
+}
+export interface ExcludedProposalPresentation {
+    readonly proposalIndex: number;
+    readonly value: unknown;
+    readonly valueText: string;
+    readonly locator: string;
+    readonly excerpt: string;
 }
 export interface ReviewResultPresentation {
     readonly result: ReviewWorkbenchResult;
@@ -57,7 +76,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[];
@@ -105,6 +125,11 @@ export interface InterpretationReadingPresentation {
  * authored record under a label nothing derived.
  */
 export declare function buildInterpretationReadingPresentation(source: InterpretationReadingSource): InterpretationReadingPresentation;
+/**
+ * One sentence naming every excluded proposal, for surfaces that speak in
+ * text (the MCP item, the recorded decision prompt). Undefined when none.
+ */
+export declare function excludedProposalsSentence(excluded: readonly ExcludedProposalPresentation[]): string | undefined;
 export declare function buildReviewItemPresentation(item: ReviewItem, adapter?: ReviewPresentationAdapter): ReviewItemPresentation;
 export declare function buildReviewCandidatePresentation(item: ReviewItem, candidate: ReviewCandidate, adapter?: ReviewPresentationAdapter, targetLabel?: string): ReviewCandidatePresentation;
 export declare function buildReviewResultPresentation(result: ReviewWorkbenchResult, item: ReviewItem | undefined, adapter?: ReviewPresentationAdapter): ReviewResultPresentation;

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

@@ -49,6 +49,50 @@ export function buildInterpretationReadingPresentation(source) {
         provenanceLabel: "Authored judgment",
     };
 }
+const EXTRACTION_ENVELOPE_PRODUCER = "survey.kontourai.io/extraction-envelope";
+/**
+ * The envelope-import binding an item carries, or undefined when it has none.
+ * A binding names its import and proposals, and every candidate points back
+ * at the same import; anything less cannot vouch for what the import checked.
+ */
+function extractionEnvelopeBinding(item) {
+    const metadata = item.metadata?.producer?.[EXTRACTION_ENVELOPE_PRODUCER];
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return undefined;
+    const binding = metadata;
+    if (typeof binding.importName !== "string" || !binding.importName || !Array.isArray(binding.proposalIndices) || binding.proposalIndices.length === 0)
+        return undefined;
+    const bound = item.spec.candidates.length > 0 && item.spec.candidates.every((candidate) => {
+        const own = candidate.producer?.[EXTRACTION_ENVELOPE_PRODUCER];
+        return own?.importName === binding.importName;
+    });
+    return bound ? binding : undefined;
+}
+/** The well-formed `excludedProposals` entries of a bound envelope item; malformed entries are ignored, never rendered. */
+function excludedProposalsOf(item, binding, adapter) {
+    if (!binding || !Array.isArray(binding.excludedProposals))
+        return [];
+    return binding.excludedProposals.flatMap((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return [];
+        const e = entry;
+        if (!Number.isSafeInteger(e.proposalIndex) || typeof e.locator !== "string" || typeof e.excerpt !== "string" || !("value" in e))
+            return [];
+        const proposed = item.spec.candidates.find((candidate) => candidate.role === "proposed");
+        const valueText = (proposed ? adapter.summarizeValue?.(e.value, { item, candidate: proposed, value: e.value }) : undefined) ?? formatValue(e.value);
+        return [{ proposalIndex: e.proposalIndex, value: e.value, valueText, locator: e.locator, excerpt: e.excerpt }];
+    });
+}
+/**
+ * One sentence naming every excluded proposal, for surfaces that speak in
+ * text (the MCP item, the recorded decision prompt). Undefined when none.
+ */
+export function excludedProposalsSentence(excluded) {
+    if (excluded.length === 0)
+        return undefined;
+    const named = excluded.map((entry) => `${entry.valueText} (proposal ${entry.proposalIndex}, ${entry.locator})`).join(", ");
+    return `${excluded.length === 1 ? "Another proposed value was" : `${excluded.length} other proposed values were`} excluded at import because the source text at the cited span is not the excerpt: ${named}. Unverifiable is not disproven.`;
+}
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
     const targetLabel = adapter.labelForTarget?.(item.spec.target, context) ?? humanizeIdentifier(item.spec.target);
@@ -61,6 +105,14 @@ export function buildReviewItemPresentation(item, adapter = {}) {
         reviewItemLink: adapter.linkForReviewItem?.(item, context),
         traceRefs: traceRefsForReviewItem(item, adapter),
         candidates: item.spec.candidates.map((candidate) => buildReviewCandidatePresentation(item, candidate, adapter, targetLabel)),
+        ...extractionPresentation(item, adapter),
+    };
+}
+function extractionPresentation(item, adapter) {
+    const binding = extractionEnvelopeBinding(item);
+    return {
+        excludedProposals: excludedProposalsOf(item, binding, adapter),
+        ...(binding ? { excerptVerification: binding.excerptVerification === "verified" ? "verified" : "unverified" } : {}),
     };
 }
 export function buildReviewCandidatePresentation(item, candidate, adapter = {}, targetLabel = adapter.labelForTarget?.(item.spec.target, { item }) ?? humanizeIdentifier(item.spec.target)) {
@@ -85,6 +137,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 +242,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",