@kontourai/survey 4.0.0 → 5.0.0

package/dist/example-data/public-directory-review-resource.d.ts

@@ -35,12 +35,12 @@ export declare const publicDirectoryReviewItemExample: {
                 excerpt: string;
             };
             extraction: {
+                model?: undefined;
                 extractionId: string;
                 target: string;
                 confidence: number;
                 extractor: string;
                 extractedAt: string;
-                model?: undefined;
             };
             claimTarget: {
                 claimId: string;
@@ -61,13 +61,13 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
             };
             producer: {
+                proposalId?: undefined;
+                oldValue?: undefined;
                 sourceAuthority: {
                     authorityClass: string;
                     declaredBy: string;
                     scope: string;
                 };
-                proposalId?: undefined;
-                oldValue?: undefined;
             };
         } | {
             id: string;

package/dist/examples/review-workbench/server-apply-consumer.js

@@ -24,6 +24,11 @@ export function prepareFacilityCredentialServerApply(input) {
     if (!currentCandidate || JSON.stringify(currentCandidate.value) !== JSON.stringify(input.currentRecord.credential)) {
         return { ok: false, message: "Current credential no longer matches the review session snapshot." };
     }
+    // A decision that selects no candidate (reject-all or could-not-confirm on a
+    // conflict) has no value to apply.
+    if (result.selectedCandidateId === undefined) {
+        return { ok: false, message: "Review result selects no candidate, so there is nothing to apply." };
+    }
     if (input.currentRecord.appliedReviewItemNames.includes(result.reviewItemName)) {
         return { ok: false, message: "Review result was already applied." };
     }

package/dist/src/canonical-reviewed-trust-input.js

@@ -1,6 +1,6 @@
 import { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 import { canonicalJson } from "./review-workbench/canonical.js";
-import { workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
+import { decisionSelectsNoCandidate, workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
 /**
  * Projects server-applied review records into the complete SurveyInput consumed
  * by buildSurveyTrustBundle. The ReviewItem and ReviewWorkbenchResult are the
@@ -33,15 +33,24 @@ export function buildCanonicalReviewedTrustInput(options) {
             throw new Error(`ReviewItem ${item.metadata.name} has no canonical server-applied result.`);
         }
         assertCanonicalResult(item, result);
+        // Reject-all or could-not-confirm on a conflict selects no candidate: the
+        // set, the review outcome and the claim then name none of its values.
+        const selectsNone = decisionSelectsNoCandidate(item, result.decision);
+        const rejectsAll = selectsNone && result.decision === "reject-proposed";
+        const rejectedRole = workbenchDecisionDefinitions[result.decision].candidateRole;
+        const rejectAllReason = result.rationale?.trim() || "Every proposed value for this claim was rejected.";
         const candidates = item.spec.candidates.map((candidate) => {
-            const records = projectCandidate(item, candidate);
+            const records = projectCandidate(item, rejectsAll && candidate.role === rejectedRole
+                ? { ...candidate, rejectionReason: candidate.rejectionReason ?? rejectAllReason }
+                : candidate);
             addConsistent(rawSources, records.rawSource, "raw source");
             addConsistent(extractions, records.extraction, "extraction");
             return records.candidate;
         });
-        const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
-        const selectedRecordId = selected.projection?.candidateId ?? selected.id;
-        const candidateSetId = selected.projection?.candidateSetId
+        const selected = selectsNone ? undefined : item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        const selectedRecordId = selected ? selected.projection?.candidateId ?? selected.id : undefined;
+        // Every candidate carries the same candidate-set id (checked below).
+        const candidateSetId = (selected ?? item.spec.candidates[0])?.projection?.candidateSetId
             ?? item.spec.projection?.candidateSetId
             ?? `${item.metadata.name}.candidates`;
         if (candidates.some((candidate) => candidate.metadata?.candidateSetId !== candidateSetId)) {
@@ -56,10 +65,10 @@ export function buildCanonicalReviewedTrustInput(options) {
                     ? { metadata: Object.fromEntries(Object.entries(metadata).filter(([key]) => key !== "candidateSetId")) }
                     : {}),
             })),
-            selectedCandidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { selectedCandidateId: selectedRecordId } : {}),
             status: result.decision === "could-not-confirm"
                 ? (item.spec.candidateSetStatus ?? "needs-review")
-                : "resolved",
+                : rejectsAll ? "rejected" : "resolved",
             ...(result.rationale ?? item.spec.rationale
                 ? { rationale: result.rationale ?? item.spec.rationale }
                 : {}),
@@ -67,12 +76,12 @@ export function buildCanonicalReviewedTrustInput(options) {
         addConsistent(candidateSets, candidateSet, "candidate set");
         const decision = result.reviewDecision.spec;
         const reviewOutcomeId = decision.projection?.reviewOutcomeId
-            ?? selected.projection?.reviewOutcomeId
+            ?? (selected ?? item.spec).projection?.reviewOutcomeId
             ?? `${item.metadata.name}.${result.decision}.review-outcome`;
         const reviewOutcome = {
             id: reviewOutcomeId,
             candidateSetId,
-            candidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { candidateId: selectedRecordId } : {}),
             status: result.status,
             ...(decision.resolution ? { resolution: decision.resolution } : {}),
             ...(decision.resolutionReason ? { resolutionReason: decision.resolutionReason } : {}),
@@ -90,34 +99,42 @@ export function buildCanonicalReviewedTrustInput(options) {
             },
         };
         addConsistent(reviewOutcomes, reviewOutcome, "review outcome");
-        const hint = selected.claimTarget;
+        // Every candidate names the same claim target (checked by assertCanonicalResult).
+        const hint = (selected ?? item.spec.candidates[0]).claimTarget;
         assertSingleProjectionId("claim", item.metadata.name, [
             decision.projection?.claimId,
             item.spec.projection?.claimId,
             ...item.spec.candidates.flatMap((candidate) => [candidate.projection?.claimId, candidate.claimTarget.claimId]),
         ]);
         const claimId = decision.projection?.claimId
-            ?? selected.projection?.claimId
+            ?? selected?.projection?.claimId
             ?? item.spec.projection?.claimId
             ?? hint.claimId
             ?? `${item.metadata.name}.claim`;
         const claim = {
             id: claimId,
             candidateSetId,
-            candidateId: selectedRecordId,
+            ...(selectedRecordId !== undefined ? { candidateId: selectedRecordId } : {}),
             subjectType: hint.subjectType,
             subjectId: hint.subjectId,
             facet: hint.facet,
             claimType: hint.claimType,
             fieldOrBehavior: hint.fieldOrBehavior,
-            value: result.effectiveValue,
-            status: result.status,
+            // Surface requires a claim value; a claim that selects none of its
+            // candidates carries null, and buildSurveyTrustBundle lists every value.
+            value: selectsNone ? null : result.effectiveValue,
+            // Could-not-confirm keeps the pre-review posture, and a conflicting or
+            // escalated candidate set is disputed before any review (see
+            // docs/decisions/could-not-confirm.md), never merely proposed.
+            status: result.decision === "could-not-confirm" && (candidateSet.status === "conflict" || candidateSet.status === "escalated")
+                ? "disputed"
+                : result.status,
             impactLevel: hint.impactLevel,
             updatedAt: decision.reviewedAt ?? options.generatedAt,
             ...(hint.evidenceType ? { evidenceType: hint.evidenceType } : {}),
             ...(hint.evidenceMethod ? { evidenceMethod: hint.evidenceMethod } : {}),
             ...(hint.derivedFrom ? { derivedFrom: [...hint.derivedFrom] } : {}),
-            collectedBy: hint.collectedBy ?? selected.extraction.extractor ?? options.source,
+            collectedBy: hint.collectedBy ?? sharedExtractor(selected ? [selected] : item.spec.candidates) ?? options.source,
             ...(decision.actor?.id ? { actor: decision.actor.id } : {}),
         };
         addConsistent(claims, claim, "claim target");
@@ -137,24 +154,38 @@ export function buildCanonicalReviewedTrustInput(options) {
     };
 }
 function assertCanonicalResult(item, result) {
-    const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
-    if (!selected) {
-        throw new Error(`Review result ${result.reviewItemName} selects an unknown candidate.`);
-    }
-    if (canonicalJson(selected) !== canonicalJson(result.selectedCandidate)) {
-        throw new Error(`Review result ${result.reviewItemName} selected candidate does not match its canonical ReviewItem.`);
-    }
-    const unselected = item.spec.candidates.filter((candidate) => candidate.id !== selected.id);
-    if (canonicalJson(unselected) !== canonicalJson(result.unselectedCandidates)) {
-        throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+    const selectsNone = decisionSelectsNoCandidate(item, result.decision);
+    let selected;
+    if (selectsNone) {
+        if (result.selectedCandidate !== undefined || result.selectedCandidateId !== undefined || result.selectedCandidateRole !== undefined
+            || result.selectedValue !== undefined || result.selectedDisplayValue !== undefined
+            || result.effectiveValue !== undefined || result.effectiveDisplayValue !== undefined || result.editedValue !== undefined) {
+            throw new Error(`Review result ${result.reviewItemName} names a selected value, but its ${result.decision} decision selects no candidate.`);
+        }
+        if (canonicalJson(item.spec.candidates) !== canonicalJson(result.unselectedCandidates)) {
+            throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+        }
     }
-    if (result.selectedCandidateRole !== selected.role || canonicalJson(result.selectedValue) !== canonicalJson(selected.value)) {
-        throw new Error(`Review result ${result.reviewItemName} selected identity does not match its canonical ReviewItem.`);
+    else {
+        selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        if (!selected) {
+            throw new Error(`Review result ${result.reviewItemName} selects an unknown candidate.`);
+        }
+        if (canonicalJson(selected) !== canonicalJson(result.selectedCandidate)) {
+            throw new Error(`Review result ${result.reviewItemName} selected candidate does not match its canonical ReviewItem.`);
+        }
+        const unselected = item.spec.candidates.filter((candidate) => candidate.id !== selected.id);
+        if (canonicalJson(unselected) !== canonicalJson(result.unselectedCandidates)) {
+            throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+        }
+        if (result.selectedCandidateRole !== selected.role || canonicalJson(result.selectedValue) !== canonicalJson(selected.value)) {
+            throw new Error(`Review result ${result.reviewItemName} selected identity does not match its canonical ReviewItem.`);
+        }
     }
     const decision = result.reviewDecision.spec;
     const definition = workbenchDecisionDefinitions[result.decision];
     if (decision.reviewItemName !== item.metadata.name
-        || decision.candidateId !== result.selectedCandidateId
+        || decision.candidateId !== selected?.id
         || decision.status !== result.status
         || decision.status !== definition.status
         || decision.rationale !== result.rationale
@@ -164,14 +195,17 @@ function assertCanonicalResult(item, result) {
     if ((result.decision === "could-not-confirm") !== (decision.resolution === "could_not_confirm")) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical review resolution.`);
     }
-    const expectedEffective = result.editedValue !== undefined && result.decision === "accept-proposed"
-        ? result.editedValue
-        : selected.value;
-    if (canonicalJson(expectedEffective) !== canonicalJson(result.effectiveValue)) {
-        throw new Error(`Review result ${result.reviewItemName} effective value is not canonical.`);
+    if (selected) {
+        const expectedEffective = result.editedValue !== undefined && result.decision === "accept-proposed"
+            ? result.editedValue
+            : selected.value;
+        if (canonicalJson(expectedEffective) !== canonicalJson(result.effectiveValue)) {
+            throw new Error(`Review result ${result.reviewItemName} effective value is not canonical.`);
+        }
     }
+    const reference = selected ?? item.spec.candidates[0];
     for (const candidate of item.spec.candidates) {
-        if (canonicalJson(claimTargetIdentity(candidate.claimTarget)) !== canonicalJson(claimTargetIdentity(selected.claimTarget))) {
+        if (canonicalJson(claimTargetIdentity(candidate.claimTarget)) !== canonicalJson(claimTargetIdentity(reference.claimTarget))) {
             throw new Error(`ReviewItem ${item.metadata.name} candidates carry conflicting claim targets.`);
         }
     }
@@ -263,3 +297,8 @@ function assertSingleProjectionId(label, itemName, values) {
         throw new Error(`ReviewItem ${itemName} carries conflicting ${label} projection ids.`);
     }
 }
+/** The extractor every candidate shares, or undefined when they differ. */
+function sharedExtractor(candidates) {
+    const extractors = new Set(candidates.map((candidate) => candidate.extraction.extractor));
+    return extractors.size === 1 ? [...extractors][0] : undefined;
+}

package/dist/src/extraction-envelope.d.ts

@@ -38,7 +38,12 @@ export interface PortableExtractionEvidenceMatch {
 export interface PortableExtractionProposal {
     fieldPath: string;
     candidateValue: unknown;
-    confidence: number;
+    /**
+     * The proposer's own uncalibrated self-report in `0..1`, absent when the
+     * proposer reported none. Survey carries it only when present and never
+     * substitutes a default.
+     */
+    confidence?: number;
     provenance: {
         excerpt: string;
         locator: string;
@@ -71,6 +76,25 @@ export type PortablePreparedArtifactState = {
     actualDigest: string;
     actualContentLength: number;
 };
+/**
+ * Why a run stopped short. The first four are early stops; the last three mean
+ * a dispatched chunk was not (fully) read or answered, and such an envelope
+ * names the affected ranges in `result.coverage`.
+ */
+export type PortableExtractionPartialReason = "cancelled" | "max-provider-calls" | "max-total-tokens" | "max-chunks" | "provider-failure" | "content-truncated" | "output-truncated";
+/**
+ * One prepared-text range (UTF-16 offsets, the space of `chars:` locators) and
+ * whether it was read and answered. `reason` is present exactly when `status`
+ * is `unread`, and then covers exactly the unread span.
+ */
+export interface PortableExtractionCoverageEntry {
+    /** 1-based chunk number. */
+    chunk: number;
+    start: number;
+    end: number;
+    status: "complete" | "unread" | "output-truncated";
+    reason?: "provider-failure" | "content-truncated" | "missing-tool-call" | "not-dispatched";
+}
 export interface PortableExtractionResultEnvelope {
     format: typeof portableExtractionResultFormat;
     version: typeof portableExtractionResultVersion;
@@ -90,7 +114,7 @@ export interface PortableExtractionResultEnvelope {
             status: "success";
         } | {
             status: "partial";
-            reason: "cancelled" | "max-provider-calls" | "max-total-tokens" | "max-chunks";
+            reason: PortableExtractionPartialReason;
         } | {
             status: "failure";
             category: "invalid-config" | "invalid-task" | "preparation" | "provider" | "unexpected";
@@ -104,11 +128,13 @@ export interface PortableExtractionResultEnvelope {
         providerCalls: number;
         totalTokensUsed: number;
         partial?: {
-            reason: "cancelled" | "max-provider-calls" | "max-total-tokens" | "max-chunks";
+            reason: PortableExtractionPartialReason;
             completedChunks: number;
             remainingChunks: number;
             tokenOvershoot?: number;
         };
+        /** Per-chunk read coverage, ordered by `start`; ranges may overlap. Requires `preparedArtifact`. */
+        coverage?: PortableExtractionCoverageEntry[];
         /** `code` is the upstream error code, informational only; `kind` stays authoritative. */
         providerFailures?: Array<{
             provider: string;
@@ -143,6 +169,13 @@ export interface ExtractionEnvelopeImportOptions {
     /** Survey meaning is supplied at the boundary; it is not added to the upstream wire contract. */
     claimTarget: (proposal: PortableExtractionProposal, index: number) => ClaimTargetHint;
 }
+/**
+ * Why an import is `unresolved`: its prepared artifact did not resolve, or the
+ * extraction itself produced nothing reviewable. `extraction-failed` is a
+ * failure outcome; `extraction-incomplete` is a partial outcome that proposed
+ * nothing, so no candidate can carry the reason. Either way the import is not
+ * a complete run that found no values.
+ */
 export type ExtractionEnvelopeImportDiagnostic = {
     kind: "artifact-unavailable";
     status: "unavailable" | "storage-error" | "identity-mismatch" | "invalid-artifact";
@@ -154,6 +187,15 @@ export type ExtractionEnvelopeImportDiagnostic = {
     expectedDigest: string;
     actualDigest: string;
     message: string;
+} | {
+    kind: "extraction-failed";
+    category: string;
+    code: string;
+    message: string;
+} | {
+    kind: "extraction-incomplete";
+    reason: PortableExtractionPartialReason;
+    message: string;
 };
 export interface ExtractionEnvelopeImport {
     apiVersion: typeof extractionEnvelopeImportApiVersion;
@@ -182,6 +224,20 @@ export interface ExtractionEnvelopeResolutionIdentity {
 }
 /** Parse an untrusted upstream document and create Survey's durable import projection. */
 export declare function importExtractionEnvelope(serialized: string | PortableExtractionResultEnvelope, options: ExtractionEnvelopeImportOptions): ExtractionEnvelopeImportResult;
+/**
+ * One ReviewItem per claim slot: every proposal whose claim target names the
+ * same claim (subject, facet, claim type, field or behavior, and claim id when
+ * one is set) at the same `pathIndices` is one candidate set, so two values for
+ * one claim can never be accepted as two separate verified claims. The slot is
+ * the claim the proposal would project to, not the upstream `fieldPath` (two
+ * field paths mapped to one claim are one slot) and not the value.
+ *
+ * Within a slot there is one candidate per distinct canonical value; further
+ * proposals of an already-seen value are recorded on that candidate as
+ * `sameValueProposals`. Two or more distinct values make the set `conflict`.
+ * Distinct `pathIndices` (array items) or distinct claim ids are separate slots,
+ * which is how a producer declares a multi-valued field.
+ */
 export declare function buildReviewItemsFromExtractionEnvelopeImport(record: ExtractionEnvelopeImport): ReviewItem[];
 export declare function exportExtractionEnvelopeImport(record: ExtractionEnvelopeImport): string;
 export declare function reimportExtractionEnvelope(serialized: string): ExtractionEnvelopeImport;

package/dist/src/extraction-envelope.js

@@ -36,11 +36,48 @@ export function importExtractionEnvelope(serialized, options) {
     };
     return { record, reviewItems: buildReviewItemsFromExtractionEnvelopeImport(record) };
 }
+/**
+ * One ReviewItem per claim slot: every proposal whose claim target names the
+ * same claim (subject, facet, claim type, field or behavior, and claim id when
+ * one is set) at the same `pathIndices` is one candidate set, so two values for
+ * one claim can never be accepted as two separate verified claims. The slot is
+ * the claim the proposal would project to, not the upstream `fieldPath` (two
+ * field paths mapped to one claim are one slot) and not the value.
+ *
+ * Within a slot there is one candidate per distinct canonical value; further
+ * proposals of an already-seen value are recorded on that candidate as
+ * `sameValueProposals`. Two or more distinct values make the set `conflict`.
+ * Distinct `pathIndices` (array items) or distinct claim ids are separate slots,
+ * which is how a producer declares a multi-valued field.
+ */
 export function buildReviewItemsFromExtractionEnvelopeImport(record) {
     validateImport(record);
     if (record.status.state !== "grounded")
         return [];
-    return record.spec.envelope.result.proposals.map((proposal, index) => buildReviewItem(record, proposal, index));
+    return claimSlotGroups(record).map((group) => buildReviewItem(record, group));
+}
+function claimSlotGroups(record) {
+    const groups = new Map();
+    record.spec.envelope.result.proposals.forEach((proposal, index) => {
+        const target = record.spec.claimTargets[index];
+        const slot = {
+            subjectType: target.subjectType, subjectId: target.subjectId, facet: target.facet, claimType: target.claimType,
+            fieldOrBehavior: target.fieldOrBehavior, claimId: target.claimId ?? null, pathIndices: proposal.pathIndices ?? null,
+        };
+        const key = canonicalJson(slot);
+        const group = groups.get(key);
+        if (!group) {
+            groups.set(key, { slot, members: [{ proposal, index }] });
+            return;
+        }
+        const first = group.members[0].index;
+        // One claim cannot carry two impact levels or evidence descriptions.
+        if (canonicalJson(record.spec.claimTargets[first]) !== canonicalJson(target)) {
+            throw new Error(`Proposals ${first} and ${index} map to the same claim with different claim targets.`);
+        }
+        group.members.push({ proposal, index });
+    });
+    return [...groups.values()];
 }
 export function exportExtractionEnvelopeImport(record) {
     validateImport(record);
@@ -66,15 +103,50 @@ export function createExtractionEnvelopeResolutionIdentity(record, proposalIndex
     const nonce = globalThis.crypto.randomUUID();
     return { evidenceId: `survey.extraction.${base}.resolution-evidence.${nonce}`, eventId: `survey.extraction.${base}.resolution-event.${nonce}` };
 }
-function buildReviewItem(record, proposal, index) {
+function buildReviewItem(record, group) {
+    const envelope = record.spec.envelope;
+    const byValue = new Map();
+    for (const member of group.members) {
+        const key = canonicalJson(member.proposal.candidateValue);
+        byValue.set(key, [...(byValue.get(key) ?? []), member]);
+    }
+    const candidates = [...byValue.values()].map((members) => buildCandidate(record, members));
+    const lead = group.members[0].proposal;
+    const valueType = lead.valueType ?? inferValueType(lead.candidateValue);
+    const identity = identityHash({ producerNamespace: record.metadata.producerNamespace, importName: record.metadata.name, source: envelope.source,
+        preparedArtifact: envelope.result.preparedArtifact, pdfLayout: envelope.result.pdfLayout, runId: envelope.result.runId, claimSlot: group.slot });
+    return {
+        apiVersion: reviewResourceApiVersion, kind: "ReviewItem",
+        metadata: { name: `extraction-envelope.${identity}`, producer: { "survey.kontourai.io/extraction-envelope": {
+                    importName: record.metadata.name,
+                    evidenceId: `survey.extraction.${identityHash(evidenceInputs(record, lead))}.source-evidence`,
+                    proposalIndices: group.members.map((member) => member.index),
+                    source: envelope.source,
+                    ...(envelope.result.preparedArtifact ? { preparedArtifact: envelope.result.preparedArtifact } : {}),
+                } } },
+        spec: {
+            target: lead.fieldPath, candidates,
+            candidateSetStatus: candidates.length > 1 ? "conflict" : "needs-review",
+            valueDescriptor: { type: valueType }, editable: false,
+        },
+        status: { observedCandidateCount: candidates.length },
+    };
+}
+/** One candidate for one distinct value; `members` are that value's proposals in envelope order. */
+function buildCandidate(record, members) {
     const envelope = record.spec.envelope;
-    const identity = identityHash(identityInputs(record, proposal, index));
+    const { proposal, index } = members[0];
+    const others = members.slice(1);
+    // A candidate commits to every proposal it stands for; a single-proposal
+    // candidate keeps exactly the identity it had before grouping.
+    const identity = identityHash(others.length === 0 ? identityInputs(record, proposal, index)
+        : { ...identityInputs(record, proposal, index), sameValueProposals: others.map((other) => ({ proposalIndex: other.index, proposal: other.proposal })) });
     const evidence = identityHash(evidenceInputs(record, proposal));
     const target = record.spec.claimTargets[index];
     const valueType = proposal.valueType ?? inferValueType(proposal.candidateValue);
-    const candidate = {
+    return {
         id: `extraction-envelope.${identity}.proposed`, role: "proposed", value: proposal.candidateValue,
-        confidence: proposal.confidence,
+        ...(proposal.confidence !== undefined ? { confidence: proposal.confidence } : {}),
         source: {
             sourceRef: envelope.source.ref,
             sourceId: envelope.source.snapshotRef ?? envelope.source.ref,
@@ -87,8 +159,9 @@ function buildReviewItem(record, proposal, index) {
         extraction: {
             extractionId: `extraction-envelope.${identity}`,
             target: proposal.fieldPath,
-            confidence: proposal.confidence,
+            ...(proposal.confidence !== undefined ? { confidence: proposal.confidence } : {}),
             extractor: proposal.extractor,
+            extractedAt: envelope.result.extractedAt,
             // The proposal's own served model when recorded; in a multi-chunk run
             // `result.model` names only the last chunk's model.
             ...(proposal.producedBy ? { model: proposal.producedBy.model } : envelope.result.model ? { model: envelope.result.model } : {}),
@@ -105,22 +178,21 @@ function buildReviewItem(record, proposal, index) {
                 ...(proposal.producedBy ? { producedBy: proposal.producedBy } : {}),
                 ...(proposal.evidenceMatch ? { evidenceMatch: proposal.evidenceMatch } : {}),
                 occurrence: proposal.provenance.occurrence,
+                ...(others.length ? { sameValueProposals: others.map((other) => ({
+                        proposalIndex: other.index,
+                        evidenceId: `survey.extraction.${identityHash(evidenceInputs(record, other.proposal))}.source-evidence`,
+                        locator: other.proposal.provenance.locator,
+                        excerpt: other.proposal.provenance.excerpt,
+                    })) } : {}),
                 attempt: { id: envelope.result.runId, providerCalls: envelope.result.providerCalls },
                 ...(envelope.result.warningClassifications ? { warnings: envelope.result.warningClassifications } : {}),
                 outcome: envelope.result.outcome,
+                // A partial run may have left this field's other values unread: the
+                // reason and the per-chunk coverage travel with every candidate.
+                ...(envelope.result.partial ? { partial: envelope.result.partial } : {}),
+                ...(envelope.result.coverage ? { coverage: envelope.result.coverage } : {}),
             } },
     };
-    return {
-        apiVersion: reviewResourceApiVersion, kind: "ReviewItem",
-        metadata: { name: `extraction-envelope.${identity}`, producer: { "survey.kontourai.io/extraction-envelope": {
-                    importName: record.metadata.name,
-                    evidenceId: `survey.extraction.${evidence}.source-evidence`,
-                    source: envelope.source,
-                    ...(envelope.result.preparedArtifact ? { preparedArtifact: envelope.result.preparedArtifact } : {}),
-                } } },
-        spec: { target: proposal.fieldPath, candidates: [candidate], candidateSetStatus: "needs-review", valueDescriptor: { type: valueType }, editable: false },
-        status: { observedCandidateCount: 1 },
-    };
 }
 function identityInputs(record, proposal, index) {
     return { producerNamespace: record.metadata.producerNamespace, importName: record.metadata.name, source: record.spec.envelope.source,
@@ -136,6 +208,9 @@ function evidenceInputs(record, proposal) {
         provenance: proposal.provenance };
 }
 function diagnosticsFor(envelope) {
+    return [...artifactDiagnostics(envelope), ...outcomeDiagnostics(envelope)];
+}
+function artifactDiagnostics(envelope) {
     const state = envelope.result.preparedArtifactState;
     if (!state || state.status === "available")
         return [];
@@ -147,6 +222,21 @@ function diagnosticsFor(envelope) {
             ...(state.status === "invalid-artifact" ? { artifactRef: state.canonicalRef } : { artifactRef: state.requestedRef }),
             message: `Prepared artifact resolution is ${state.status}.` }];
 }
+/**
+ * A failed run, or a partial run with no proposal, must not look like a
+ * complete run that found nothing. A partial run with proposals stays
+ * grounded: its reason and coverage travel on every candidate.
+ */
+function outcomeDiagnostics(envelope) {
+    const outcome = envelope.result.outcome;
+    if (outcome.status === "failure")
+        return [{ kind: "extraction-failed", category: outcome.category, code: outcome.code,
+                message: `Extraction failed (${outcome.category}/${outcome.code}); no usable answer was recorded for this source, so the import has no candidates.` }];
+    if (outcome.status === "partial" && envelope.result.proposals.length === 0)
+        return [{ kind: "extraction-incomplete", reason: outcome.reason,
+                message: `Extraction stopped short (${outcome.reason}) without proposing any value; unread text may hold values.` }];
+    return [];
+}
 function validateImport(value) {
     jsonSafe(value, "Extraction envelope import");
     const record = obj(value, "Extraction envelope import");
@@ -189,7 +279,7 @@ function validateEnvelope(input) {
     if (source.snapshotRef !== undefined)
         safeReference(source.snapshotRef, "source.snapshotRef");
     const r = obj(e.result, "result");
-    exact(r, ["proposals", "provider", "runId", "raw", "outcome", "extractedAt", "providerCalls", "totalTokensUsed"], "result", ["model", "warningClassifications", "partial", "providerFailures", "taskDigest", "exampleDigests", "pdfPageOffsets", "pdfLayout", "ocrDerived", "preparedArtifact", "preparedArtifactState"]);
+    exact(r, ["proposals", "provider", "runId", "raw", "outcome", "extractedAt", "providerCalls", "totalTokensUsed"], "result", ["model", "warningClassifications", "partial", "coverage", "providerFailures", "taskDigest", "exampleDigests", "pdfPageOffsets", "pdfLayout", "ocrDerived", "preparedArtifact", "preparedArtifactState"]);
     stableIdentity(r.provider, "result.provider");
     if (r.model !== undefined)
         stableIdentity(r.model, "result.model");
@@ -224,6 +314,9 @@ function validateEnvelope(input) {
         : artifact === undefined
             ? (() => { throw new Error("result.pdfLayout requires result.preparedArtifact."); })()
             : validatePortablePdfLayout(r.pdfLayout, artifact.contentLength);
+    if (r.coverage !== undefined)
+        validateCoverage(r.coverage, artifact);
+    validateCoverageAgreement(r.outcome, r.coverage);
     const state = r.preparedArtifactState === undefined ? undefined : validateArtifactState(r.preparedArtifactState, artifact);
     if (source.snapshotRef !== undefined && artifact?.sourceSnapshotRef !== undefined && source.snapshotRef !== artifact.sourceSnapshotRef)
         throw new Error("Source snapshot identity mismatch.");
@@ -232,10 +325,12 @@ function validateEnvelope(input) {
 }
 function validateProposal(input, index, contentLength) {
     const p = obj(input, `proposal[${index}]`);
-    exact(p, ["fieldPath", "candidateValue", "confidence", "provenance", "extractor"], `proposal[${index}]`, ["pathIndices", "inferenceType", "valueType", "enumValues", "producedBy", "evidenceMatch"]);
+    exact(p, ["fieldPath", "candidateValue", "provenance", "extractor"], `proposal[${index}]`, ["confidence", "pathIndices", "inferenceType", "valueType", "enumValues", "producedBy", "evidenceMatch"]);
     wireNonEmpty(p.fieldPath, "proposal.fieldPath");
     stableIdentity(p.extractor, "proposal.extractor");
-    finite(p.confidence, "proposal.confidence", 0, 1);
+    // Absent means the proposer reported none; `null` is not absent and is rejected.
+    if (Object.hasOwn(p, "confidence"))
+        finite(p.confidence, "proposal.confidence", 0, 1);
     const provenance = obj(p.provenance, "proposal.provenance");
     exact(provenance, ["excerpt", "locator", "occurrence"], "proposal.provenance");
     wireNonEmpty(provenance.excerpt, "proposal.provenance.excerpt");
@@ -323,6 +418,45 @@ else if (o.status === "failure") {
 else
     throw new Error("outcome status is invalid."); if (o.status !== "partial" && partial !== undefined)
     throw new Error("partial requires partial outcome."); }
+function validateCoverage(input, artifact) {
+    if (!artifact)
+        throw new Error("result.coverage requires result.preparedArtifact.");
+    const entries = array(input, "result.coverage");
+    entries.forEach((value, index) => {
+        const subject = `result.coverage[${index}]`;
+        const c = obj(value, subject);
+        exact(c, ["chunk", "start", "end", "status"], subject, ["reason"]);
+        integer(c.chunk, `${subject}.chunk`);
+        if (c.chunk === 0)
+            throw new Error(`${subject}.chunk must be positive.`);
+        integer(c.start, `${subject}.start`);
+        integer(c.end, `${subject}.end`);
+        if (c.end <= c.start)
+            throw new Error(`${subject} must have start < end.`);
+        if (c.end > artifact.contentLength)
+            throw new Error(`${subject}.end exceeds the prepared artifact contentLength.`);
+        if (!COVERAGE_STATUSES.has(c.status))
+            throw new Error(`${subject}.status is invalid.`);
+        if ((c.status === "unread") !== (c.reason !== undefined))
+            throw new Error(`${subject}.reason is required exactly when status is unread.`);
+        if (c.reason !== undefined && !COVERAGE_REASONS.has(c.reason))
+            throw new Error(`${subject}.reason is invalid.`);
+        // Chunks overlap by design, so ranges may overlap; only the order is fixed.
+        if (index > 0 && c.start < (entries[index - 1].start))
+            throw new Error("result.coverage entries must be ordered by start.");
+    });
+}
+/** The outcome and the coverage must tell the same story about unread text. */
+function validateCoverageAgreement(outcome, coverage) {
+    const lost = coverage?.some((entry) => entry.status !== "complete") ?? false;
+    if (outcome.status === "success" && lost)
+        throw new Error("result.coverage names unread or unanswered text, but the outcome is success.");
+    // A loss reason means a dispatched chunk lost text; a never-dispatched range
+    // is an early stop, not that loss.
+    const dispatchedLoss = coverage?.some((entry) => entry.status !== "complete" && entry.reason !== "not-dispatched") ?? false;
+    if (outcome.status === "partial" && LOSS_PARTIAL.has(outcome.reason) && !dispatchedLoss)
+        throw new Error(`partial reason ${outcome.reason} requires a result.coverage entry for a dispatched chunk that was not read or answered.`);
+}
 function validateWarning(v) { const w = obj(v, "warning"); exact(w, ["category", "code"], "warning"); if (!WARNING_CATEGORIES.has(w.category))
     throw new Error("warning category invalid."); stableIdentity(w.code, "warning.code"); }
 function validateFailure(v) { const f = obj(v, "providerFailure"); exact(f, ["provider", "kind", "retryable"], "providerFailure", ["code"]); stableIdentity(f.provider, "failure.provider"); if (!FAILURE_KINDS.has(f.kind) || typeof f.retryable !== "boolean")
@@ -447,7 +581,11 @@ function isWellFormedUnicode(value) { for (let index = 0; index < value.length;
 } return true; }
 const RAW_SOURCE_KINDS = new Set(["uploaded-document", "web-page", "api-record", "manual-entry", "policy-standard", "inquiry-question", "agent-utterance", "system-schema"]);
 const VALUE_TYPES = new Set(["string", "number", "boolean", "date", "enum", "array", "object"]);
-const PARTIAL = new Set(["cancelled", "max-provider-calls", "max-total-tokens", "max-chunks"]);
+/** Partial reasons meaning a dispatched chunk was not (fully) read or answered. */
+const LOSS_PARTIAL = new Set(["provider-failure", "content-truncated", "output-truncated"]);
+const PARTIAL = new Set(["cancelled", "max-provider-calls", "max-total-tokens", "max-chunks", ...LOSS_PARTIAL]);
+const COVERAGE_STATUSES = new Set(["complete", "unread", "output-truncated"]);
+const COVERAGE_REASONS = new Set(["provider-failure", "content-truncated", "missing-tool-call", "not-dispatched"]);
 const FAILURE_CATEGORIES = new Set(["invalid-config", "invalid-task", "preparation", "provider", "unexpected"]);
 const WARNING_CATEGORIES = new Set(["provider", "normalization", "preparation", "limit", "storage", "content", "other"]);
 const FAILURE_KINDS = new Set(["authentication", "rate-limit", "timeout", "invalid-request", "unavailable", "unknown"]);