@kontourai/survey 5.0.0 → 6.1.0

package/dist/src/extraction-envelope.js

@@ -26,13 +26,16 @@ export function importExtractionEnvelope(serialized, options) {
     const producerNamespace = options.producerNamespace ?? envelope.result.provider;
     nonEmpty(name, "Extraction envelope import name");
     nonEmpty(producerNamespace, "Extraction envelope producer namespace");
-    const diagnostics = diagnosticsFor(envelope);
+    const verification = options.artifact === undefined
+        ? { provenance: "unverified", diagnostics: [] }
+        : verifyAgainstArtifact(envelope, options.artifact);
+    const diagnostics = [...diagnosticsFor(envelope), ...verification.diagnostics];
     const record = {
         apiVersion: extractionEnvelopeImportApiVersion,
         kind: "ExtractionEnvelopeImport",
         metadata: { name, producerNamespace },
         spec: { envelope, sourceKind: options.sourceKind, claimTargets: cloneJson(claimTargets) },
-        status: { state: diagnostics.length ? "unresolved" : "grounded", diagnostics },
+        status: { state: stateFor(diagnostics, envelope.result.proposals.length), diagnostics, provenance: verification.provenance },
     };
     return { record, reviewItems: buildReviewItemsFromExtractionEnvelopeImport(record) };
 }
@@ -58,16 +61,23 @@ export function buildReviewItemsFromExtractionEnvelopeImport(record) {
 }
 function claimSlotGroups(record) {
     const groups = new Map();
-    record.spec.envelope.result.proposals.forEach((proposal, index) => {
+    const excluded = excerptMismatchProposalIndices(record);
+    const slotOf = (proposal, index) => {
         const target = record.spec.claimTargets[index];
-        const slot = {
+        return {
             subjectType: target.subjectType, subjectId: target.subjectId, facet: target.facet, claimType: target.claimType,
             fieldOrBehavior: target.fieldOrBehavior, claimId: target.claimId ?? null, pathIndices: proposal.pathIndices ?? null,
         };
+    };
+    record.spec.envelope.result.proposals.forEach((proposal, index) => {
+        if (excluded.has(index))
+            return;
+        const target = record.spec.claimTargets[index];
+        const slot = slotOf(proposal, index);
         const key = canonicalJson(slot);
         const group = groups.get(key);
         if (!group) {
-            groups.set(key, { slot, members: [{ proposal, index }] });
+            groups.set(key, { slot, members: [{ proposal, index }], excluded: [] });
             return;
         }
         const first = group.members[0].index;
@@ -77,6 +87,14 @@ function claimSlotGroups(record) {
         }
         group.members.push({ proposal, index });
     });
+    // An excluded proposal is unverifiable, not disproven: the slot it would have
+    // joined keeps a record of it, so a rival value cannot vanish without trace.
+    // A slot whose every proposal was excluded has no item; the import
+    // diagnostics are then the only record, as for any excluded proposal.
+    record.spec.envelope.result.proposals.forEach((proposal, index) => {
+        if (excluded.has(index))
+            groups.get(canonicalJson(slotOf(proposal, index)))?.excluded.push({ proposal, index });
+    });
     return [...groups.values()];
 }
 export function exportExtractionEnvelopeImport(record) {
@@ -123,6 +141,13 @@ function buildReviewItem(record, group) {
                     proposalIndices: group.members.map((member) => member.index),
                     source: envelope.source,
                     ...(envelope.result.preparedArtifact ? { preparedArtifact: envelope.result.preparedArtifact } : {}),
+                    // Present only on verified imports, so an unverified import's items stay
+                    // byte-identical to the ones earlier releases produced.
+                    ...(record.status.provenance === "verified" ? { excerptVerification: "verified" } : {}),
+                    ...(group.excluded.length ? { excludedProposals: group.excluded.map(({ proposal, index }) => ({
+                            proposalIndex: index, value: proposal.candidateValue, locator: proposal.provenance.locator,
+                            excerpt: proposal.provenance.excerpt, reason: "excerpt-mismatch",
+                        })) } : {}),
                 } } },
         spec: {
             target: lead.fieldPath, candidates,
@@ -207,6 +232,146 @@ function evidenceInputs(record, proposal) {
         extractedAt: record.spec.envelope.result.extractedAt,
         provenance: proposal.provenance };
 }
+/** Proposals the import excluded because their span did not match their excerpt. */
+export function excerptMismatchProposalIndices(record) {
+    return new Set(record.status.diagnostics.flatMap((diagnostic) => diagnostic.kind === "excerpt-mismatch" ? [diagnostic.proposalIndex] : []));
+}
+/**
+ * An import is grounded when nothing but excerpt mismatches was diagnosed and
+ * at least one proposal survived them. Every proposal excluded must not read as
+ * a complete run that found nothing.
+ */
+function stateFor(diagnostics, proposalCount) {
+    const mismatches = diagnostics.filter((diagnostic) => diagnostic.kind === "excerpt-mismatch").length;
+    if (mismatches !== diagnostics.length)
+        return "unresolved";
+    return mismatches > 0 && mismatches === proposalCount ? "unresolved" : "grounded";
+}
+/** Validate the caller-resolved artifact shape; resolver detail beyond the code is refused. */
+export function assertResolvedExtractionArtifact(artifact) {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
+        throw new Error("Invalid resolved extraction artifact.");
+    const a = artifact;
+    const keys = Object.keys(a).sort();
+    if (a.status === "available") {
+        if (keys.join(",") !== "actualDigest,status,text" || typeof a.text !== "string" || typeof a.actualDigest !== "string" || !/^[a-f0-9]{64}$/.test(a.actualDigest))
+            throw new Error("Invalid available extraction artifact.");
+    }
+    else if (a.status === "digest-mismatch") {
+        if (keys.join(",") !== "actualDigest,status" || typeof a.actualDigest !== "string" || !/^[a-f0-9]{64}$/.test(a.actualDigest))
+            throw new Error("Invalid digest-mismatch extraction artifact.");
+    }
+    else if (a.status === "unavailable") {
+        if (keys.join(",") !== "code,status" || !ARTIFACT_UNAVAILABLE_CODES.has(a.code))
+            throw new Error("Invalid unavailable extraction artifact.");
+    }
+    else
+        throw new Error("Invalid resolved extraction artifact status.");
+}
+/**
+ * Checks resolved text against the envelope's prepared-artifact identity: the
+ * caller's reported digest, the digest of the text itself, and the declared
+ * length. Shared by import-time verification and the source inspector.
+ */
+export function checkPreparedArtifact(prepared, artifact) {
+    if (artifact.status === "unavailable")
+        return { status: "unavailable", code: artifact.code };
+    if (artifact.status === "digest-mismatch")
+        return { status: "digest-mismatch", actualDigest: artifact.actualDigest };
+    const textDigest = sha256Hex(artifact.text);
+    if (!prepared || artifact.actualDigest !== prepared.digest || textDigest !== artifact.actualDigest)
+        return { status: "digest-mismatch", actualDigest: textDigest };
+    if (artifact.text.length !== prepared.contentLength)
+        return { status: "wrong-length" };
+    return { status: "aligned", text: artifact.text };
+}
+/** Whether the verified prepared text at a proposal's `chars:` span is exactly its excerpt. */
+export function proposalSpanMatches(text, proposal) {
+    const match = /^chars:(\d+)-(\d+)$/.exec(proposal.provenance.locator);
+    if (!match)
+        return false;
+    return text.slice(Number(match[1]), Number(match[2])) === proposal.provenance.excerpt;
+}
+function verifyAgainstArtifact(envelope, artifact) {
+    assertResolvedExtractionArtifact(artifact);
+    const prepared = envelope.result.preparedArtifact;
+    if (!prepared)
+        throw new Error("The artifact option requires result.preparedArtifact to verify against.");
+    const check = checkPreparedArtifact(prepared, artifact);
+    if (check.status === "unavailable")
+        return { provenance: "unverified", diagnostics: [unreadableArtifactDiagnostic(prepared.ref, check.code)] };
+    if (check.status === "wrong-length")
+        return { provenance: "unverified", diagnostics: [wrongLengthDiagnostic(prepared.ref)] };
+    if (check.status === "digest-mismatch")
+        return { provenance: "unverified", diagnostics: [suppliedDigestMismatchDiagnostic(prepared, check.actualDigest)] };
+    const diagnostics = [];
+    envelope.result.proposals.forEach((proposal, index) => {
+        if (!proposalSpanMatches(check.text, proposal))
+            diagnostics.push(excerptMismatchDiagnostic(index, proposal));
+    });
+    return { provenance: "verified", diagnostics };
+}
+function unreadableArtifactDiagnostic(artifactRef, code) {
+    const status = code === "storage-error" ? "storage-error" : code === "invalid-artifact" ? "invalid-artifact" : "unavailable";
+    return { kind: "artifact-unavailable", status, artifactRef, code, message: `Prepared artifact could not be read to verify excerpts (${code}); no candidate is grounded.` };
+}
+function wrongLengthDiagnostic(artifactRef) {
+    return { kind: "artifact-unavailable", status: "invalid-artifact", artifactRef, message: "Prepared artifact text does not have the declared content length; no candidate is grounded." };
+}
+function suppliedDigestMismatchDiagnostic(prepared, actualDigest) {
+    return { kind: "digest-mismatch", artifactRef: prepared.ref, expectedDigest: prepared.digest, actualDigest,
+        message: "Prepared artifact text supplied at import does not match the extraction artifact digest; no candidate is grounded." };
+}
+function excerptMismatchDiagnostic(index, proposal) {
+    return { kind: "excerpt-mismatch", proposalIndex: index, locator: proposal.provenance.locator,
+        message: `Proposal ${index} (${proposal.fieldPath}): the prepared text at ${proposal.provenance.locator} is not its excerpt, so it produced no review item.` };
+}
+/**
+ * The import-time verification diagnostics a record may carry after the
+ * envelope-derived ones. They cannot be recomputed without the artifact text,
+ * so a reloaded record is checked for being one the import could have
+ * written: each diagnostic is rebuilt from its own fields and must match.
+ */
+function verificationDiagnosticsAreCoherent(envelope, provenance, diagnostics) {
+    if (provenance === undefined)
+        return diagnostics.length === 0;
+    const prepared = envelope.result.preparedArtifact;
+    const rebuild = (value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value) || !prepared)
+            return undefined;
+        const d = value;
+        if (provenance === "verified") {
+            const proposal = Number.isSafeInteger(d.proposalIndex) ? envelope.result.proposals[d.proposalIndex] : undefined;
+            return d.kind === "excerpt-mismatch" && proposal ? excerptMismatchDiagnostic(d.proposalIndex, proposal) : undefined;
+        }
+        if (d.kind === "artifact-unavailable") {
+            if (d.code === undefined)
+                return wrongLengthDiagnostic(prepared.ref);
+            return ARTIFACT_UNAVAILABLE_CODES.has(d.code) ? unreadableArtifactDiagnostic(prepared.ref, d.code) : undefined;
+        }
+        if (d.kind === "digest-mismatch" && typeof d.actualDigest === "string" && /^[a-f0-9]{64}$/.test(d.actualDigest))
+            return suppliedDigestMismatchDiagnostic(prepared, d.actualDigest);
+        return undefined;
+    };
+    if (provenance !== "verified" && provenance !== "unverified")
+        return false;
+    if (provenance === "verified" && !prepared)
+        return false;
+    if (provenance === "unverified" && diagnostics.length > 1)
+        return false;
+    let previous = -1;
+    for (const diagnostic of diagnostics) {
+        const expected = rebuild(diagnostic);
+        if (!expected || canonicalJson(expected) !== canonicalJson(diagnostic))
+            return false;
+        if (expected.kind === "excerpt-mismatch") {
+            if (expected.proposalIndex <= previous)
+                return false;
+            previous = expected.proposalIndex;
+        }
+    }
+    return true;
+}
 function diagnosticsFor(envelope) {
     return [...artifactDiagnostics(envelope), ...outcomeDiagnostics(envelope)];
 }
@@ -257,9 +422,12 @@ function validateImport(value) {
     if (targets.length !== envelope.result.proposals.length)
         throw new Error("spec.claimTargets must align with proposals.");
     const status = obj(record.status, "status");
-    exact(status, ["state", "diagnostics"], "status");
+    exact(status, ["state", "diagnostics"], "status", ["provenance"]);
+    const diagnostics = array(status.diagnostics, "status.diagnostics");
     const expected = diagnosticsFor(envelope);
-    if (canonicalJson(status.diagnostics) !== canonicalJson(expected) || status.state !== (expected.length ? "unresolved" : "grounded"))
+    if (canonicalJson(diagnostics.slice(0, expected.length)) !== canonicalJson(expected)
+        || !verificationDiagnosticsAreCoherent(envelope, status.provenance, diagnostics.slice(expected.length))
+        || status.state !== stateFor(diagnostics, envelope.result.proposals.length))
         throw new Error("Import status does not match envelope state.");
 }
 /** Validate and defensively clone a persisted or browser-delivered import. */
@@ -592,6 +760,7 @@ const FAILURE_KINDS = new Set(["authentication", "rate-limit", "timeout", "inval
 const MODEL_SOURCES = new Set(["provider-reported", "configured"]);
 const SCHEMA_MATCHES = new Set(["ok", "type-mismatch", "enum-mismatch", "format-invalid"]);
 const VALUE_IN_EXCERPT_MATCHES = new Set(["match", "mismatch", "not-evaluated", "not-applicable"]);
+const ARTIFACT_UNAVAILABLE_CODES = new Set(["not-found", "storage-error", "access-denied", "invalid-artifact", "unknown"]);
 const PREPARATION_MODES = new Set(["text", "markdown", "transcript", "pdf-text", "image-ocr"]);
 const ARTIFACT_INVALID_REASONS = new Set(["not-an-object", "invalid-format", "invalid-version", "invalid-digest", "invalid-ref", "invalid-preparation-mode", "invalid-preparation-version", "invalid-content-length", "invalid-source-snapshot-ref", "ill-formed-unicode", "invalid-resolved-text"]);
 const STABLE_IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._:@/+~-]{0,255}$/;

package/dist/src/index.d.ts

@@ -8,7 +8,7 @@ export type { BindReviewQueueOptions, ReviewQueueBinding, ReviewQueueBindingIssu
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry, PortablePdfRegionContext, PortablePdfTable, PortablePdfTableCell, PortablePdfTextElement, PortablePdfTextRange, } from "./pdf-layout.js";
 export type { ExtractionAlignmentState, ArtifactUnavailableCode, BuiltExtractionInspectorCandidate, BuiltExtractionInspectorModel, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
-export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionCoverageEntry, PortableExtractionEvidenceMatch, PortableExtractionPartialReason, PortableExtractionOccurrence, PortableExtractionProducedBy, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
+export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportProvenance, 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";
@@ -35,8 +35,10 @@ export { repeatedObservation } from "./repeated-observation.js";
 export type { RepeatedObservationInput } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationBuilderArgs, SourceOfAuthorityObservationInput, } from "./source-of-authority-observation.js";
-export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
-export type { InterpretationReadingPresentation, InterpretationReadingSource, ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
+export { buildCandidateVerification, candidateVerificationKind, DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS, MAX_SUPPORT_VERIFIER_TIMEOUT_MS, foldCandidateVerifications, runSupportVerifier, supportVerificationInputDigest, validateCandidateVerification, valueDigest, } from "./candidate-verification.js";
+export type { BuildCandidateVerificationInput, CandidateVerification, CandidateVerificationInapplicableReason, CandidateVerificationStatus, CandidateVerificationSubject, FoldCandidateVerificationsResult, RunSupportVerifierOptions, SupportAbstainReason, SupportEvidence, SupportVerdict, SupportVerificationInput, SupportVerificationMethod, SupportVerificationResult, SupportVerifier, } from "./candidate-verification.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, candidateVerificationNotes, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export type { CandidateVerificationNote, CandidateVerificationRecordPresentation, InterpretationReadingPresentation, InterpretationReadingSource, ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, PolicyStandardMetadata, PolicyStandardSourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";

package/dist/src/index.js

@@ -17,7 +17,8 @@ export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalRevi
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
-export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export { buildCandidateVerification, candidateVerificationKind, DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS, MAX_SUPPORT_VERIFIER_TIMEOUT_MS, foldCandidateVerifications, runSupportVerifier, supportVerificationInputDigest, validateCandidateVerification, valueDigest, } from "./candidate-verification.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, candidateVerificationNotes, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";

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

@@ -5,6 +5,7 @@ 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 { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { buildReviewItemPresentation, candidateVerificationNotes, 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";
@@ -78,12 +79,27 @@ function itemDetailText(item, snapshot, events) {
             `  source: ${candidate.source?.sourceRef ?? "none"}`,
             ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
         ])),
+        ...extractionImportLines(item),
+        ...candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`]),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
     }
     return lines.join("\n");
 }
+/** The reviewer's edit when the item's decision accepts one; verifier records are read against it. */
+function editedValueFor(item, state) {
+    return state.decisionsByItemName[item.metadata.name] === "accept-proposed" ? state.editedValuesByItemName?.[item.metadata.name] : undefined;
+}
+/** 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)
@@ -131,6 +147,8 @@ function buildReviewCardHtml(item, snapshot, events) {
         ? 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 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>`;
@@ -232,6 +250,8 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
   </div>
   ${proposedCards}
 </div>
+${excludedNote ? `<p class="feedback" id="excluded-note">${escapeHtml(excludedNote)}</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>` : ""}
 
 <div class="divider"></div>
@@ -339,14 +359,28 @@ async function toolItem(itemName, options) {
         decision: current.decisionsByItemName[item.metadata.name],
         note: current.notesByItemName[item.metadata.name],
         candidateSetStatus: item.spec.candidateSetStatus,
-        candidates: item.spec.candidates.map((c) => ({
-            id: c.id,
-            role: c.role,
-            value: c.value,
-            confidence: c.extraction?.confidence ?? c.confidence,
-            sourceRef: c.source?.sourceRef,
-            excerpt: c.locator?.excerpt,
-        })),
+        ...(() => {
+            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: (() => {
+            const notes = 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,
+                    sourceRef: c.source?.sourceRef,
+                    excerpt: c.locator?.excerpt,
+                    ...(note ? { verification: { subject: note.subjectLabel, status: note.status, records: note.records, inapplicableCount: note.inapplicableCount, rejectedCount: note.rejectedCount } } : {}),
+                };
+            });
+        })(),
     };
     const content = [
         { type: "text", text: `${text}\n\n${JSON.stringify(itemData, null, 2)}` },

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

@@ -1,3 +1,4 @@
+import type { CandidateVerification } from "./candidate-verification.js";
 import type { CandidateSetStatus, ClaimTarget, Extraction, RawSource, ReviewAuthorizing, ReviewOutcome } from "./types.js";
 export declare const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";
 export type ReviewResourceApiVersion = typeof reviewResourceApiVersion;
@@ -104,6 +105,14 @@ export interface ReviewCandidate {
     claimTarget: ClaimTargetHint;
     projection?: SurveyRecordProjectionHint;
     producer?: Record<string, unknown>;
+    /**
+     * Records of what independent support verifiers said about this candidate's
+     * value (see `CandidateVerification`). A record of a verifier's output, not a
+     * trust decision: nothing routes, accepts, or calibrates on it. Every decision
+     * surface validates each record on read, ignores any that fail, and shows only
+     * those bound to the value under review.
+     */
+    verifications?: CandidateVerification[];
 }
 /**
  * Well-known neutral value-type vocabulary for {@link ReviewValueDescriptor}.

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 ExtractionEnvelopeImportDiagnostic, 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;
@@ -97,6 +86,21 @@ export interface ExtractionInspectorSource {
     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 {
@@ -159,7 +163,7 @@ export declare function buildExtractionInspectorModel(input: ExtractionInspector
  * 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 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,14 +18,14 @@ 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.diagnostics, 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();
@@ -118,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.");
@@ -148,7 +128,9 @@ function assertImportedResult(result, record) {
     const grounded = record.status?.state === "grounded";
     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))))
+    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))
@@ -183,39 +165,51 @@ function envelopeItemProposalIndices(item) {
  * 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) {
+function sourceModel(key, importName, prepared, diagnostics, artifact, ocrDerived, proposals, importProvenance) {
     let alignment;
     let message;
     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");
-    if (artifactUnresolved || artifact.status === "unavailable") {
+    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 = extractionDiagnostic
+        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}`;
+    }
+    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, ...(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 };
+    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);
@@ -224,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);
@@ -306,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 => { 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("");
+        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)