@kontourai/survey 4.0.0 → 6.0.0

package/dist/src/extraction-envelope.js

@@ -26,21 +26,76 @@ 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) };
 }
+/**
+ * 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();
+    const excluded = excerptMismatchProposalIndices(record);
+    const slotOf = (proposal, index) => {
+        const target = record.spec.claimTargets[index];
+        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 }], excluded: [] });
+            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 });
+    });
+    // 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) {
     validateImport(record);
@@ -66,15 +121,57 @@ 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 } : {}),
+                    // 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,
+            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 +184,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 +203,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,
@@ -135,7 +232,150 @@ 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)];
+}
+function artifactDiagnostics(envelope) {
     const state = envelope.result.preparedArtifactState;
     if (!state || state.status === "available")
         return [];
@@ -147,6 +387,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");
@@ -167,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. */
@@ -189,7 +447,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 +482,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 +493,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 +586,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,13 +749,18 @@ 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"]);
 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

@@ -2,13 +2,13 @@ export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, Escalati
 export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeResolutionIdentity, exportExtractionEnvelopeImport, extractionEnvelopeImportApiVersion, importExtractionEnvelope, portableExtractionResultFormat, portableExtractionResultVersion, reimportExtractionEnvelope, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
-export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
+export { buildExtractionInspectorModel, exportExtractionInspector, inspectorSourcePosture, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./review-workbench/queue-binding.js";
 export type { BindReviewQueueOptions, ReviewQueueBinding, ReviewQueueBindingIssue, ReviewQueueBindingIssueCode, ReviewQueueExtractionIssue, ReviewQueueExtractionIssueCode, ValidateReviewQueueBindingOptions, } from "./review-workbench/queue-binding.js";
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry, PortablePdfRegionContext, PortablePdfTable, PortablePdfTableCell, PortablePdfTextElement, PortablePdfTextRange, } from "./pdf-layout.js";
 export type { ExtractionAlignmentState, ArtifactUnavailableCode, BuiltExtractionInspectorCandidate, BuiltExtractionInspectorModel, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
-export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionEvidenceMatch, PortableExtractionOccurrence, PortableExtractionProducedBy, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
+export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, 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";

package/dist/src/index.js

@@ -1,7 +1,7 @@
 export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeResolutionIdentity, exportExtractionEnvelopeImport, extractionEnvelopeImportApiVersion, importExtractionEnvelope, portableExtractionResultFormat, portableExtractionResultVersion, reimportExtractionEnvelope, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
-export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
+export { buildExtractionInspectorModel, exportExtractionInspector, inspectorSourcePosture, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./review-workbench/queue-binding.js";
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";