@kontourai/survey 3.0.0 → 5.0.0

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

@@ -17,10 +17,33 @@ export interface PortableExtractionOccurrence {
     hintUsed: boolean;
     ambiguous: boolean;
 }
+/** Which model produced one proposal, as the extractor recorded it for that proposal's own request. */
+export interface PortableExtractionProducedBy {
+    model: string;
+    modelSource: "provider-reported" | "configured";
+    /** Content-free digest of the provider request (`sha256:<hex>`). */
+    requestDigest: string;
+}
+/**
+ * Deterministic, versioned facts about how a proposal's value relates to the
+ * declared schema and to its own excerpt. Annotations only: Survey carries
+ * them to review and does not route or block on them.
+ */
+export interface PortableExtractionEvidenceMatch {
+    checkerVersion: string;
+    schema: "ok" | "type-mismatch" | "enum-mismatch" | "format-invalid";
+    valueInExcerpt: "match" | "mismatch" | "not-evaluated" | "not-applicable";
+    tokenBoundary?: boolean;
+}
 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;
@@ -31,6 +54,8 @@ export interface PortableExtractionProposal {
     inferenceType?: "explicit" | "inferred";
     valueType?: ReviewValueType;
     enumValues?: string[];
+    producedBy?: PortableExtractionProducedBy;
+    evidenceMatch?: PortableExtractionEvidenceMatch;
 }
 export type PortablePreparedArtifactState = {
     status: "available" | "unavailable" | "storage-error";
@@ -51,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;
@@ -70,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";
@@ -84,15 +128,19 @@ 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;
             kind: "authentication" | "rate-limit" | "timeout" | "invalid-request" | "unavailable" | "unknown";
             retryable: boolean;
+            code?: string;
         }>;
         taskDigest?: string;
         exampleDigests?: string[];
@@ -121,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";
@@ -132,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;
@@ -160,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,9 +159,12 @@ 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,
-            ...(envelope.result.model ? { model: envelope.result.model } : {}),
+            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 } : {}),
         },
         claimTarget: target,
         producer: { "survey.kontourai.io/extraction-envelope": {
@@ -100,23 +175,24 @@ function buildReviewItem(record, proposal, index) {
                 ...(envelope.result.taskDigest ? { taskDigest: envelope.result.taskDigest } : {}),
                 ...(envelope.result.exampleDigests ? { exampleDigests: envelope.result.exampleDigests } : {}),
                 valueType: { type: valueType, origin: proposal.inferenceType ?? "inferred" },
+                ...(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,
@@ -132,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 [];
@@ -143,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");
@@ -185,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");
@@ -220,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.");
@@ -228,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"]);
+    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");
@@ -252,6 +351,10 @@ function validateProposal(input, index, contentLength) {
         throw new Error("proposal valueType is invalid.");
     if (p.enumValues !== undefined)
         array(p.enumValues, "enumValues").forEach((v) => wellFormedString(v, "enumValue"));
+    if (p.producedBy !== undefined)
+        validateProducedBy(p.producedBy);
+    if (p.evidenceMatch !== undefined)
+        validateEvidenceMatch(p.evidenceMatch);
     return cloneJson(p);
 }
 function validateOccurrence(input, start, end) { const o = obj(input, "occurrence"); exact(o, ["resolverVersion", "count", "selected", "selection", "hintUsed", "ambiguous"], "occurrence"); if (o.resolverVersion !== "exact-occurrence-v1")
@@ -315,10 +418,59 @@ 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"); stableIdentity(f.provider, "failure.provider"); if (!FAILURE_KINDS.has(f.kind) || typeof f.retryable !== "boolean")
-    throw new Error("provider failure invalid."); }
+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")
+    throw new Error("provider failure invalid."); if (f.code !== undefined) {
+    stableIdentity(f.code, "failure.code");
+    if (f.code.length > 128)
+        throw new Error("failure.code must be at most 128 characters.");
+} }
+function validateProducedBy(v) { const b = obj(v, "proposal.producedBy"); exact(b, ["model", "modelSource", "requestDigest"], "proposal.producedBy"); stableIdentity(b.model, "proposal.producedBy.model"); if (!MODEL_SOURCES.has(b.modelSource))
+    throw new Error("proposal.producedBy.modelSource is invalid."); digest(b.requestDigest, "proposal.producedBy.requestDigest"); }
+function validateEvidenceMatch(v) { const m = obj(v, "proposal.evidenceMatch"); exact(m, ["checkerVersion", "schema", "valueInExcerpt"], "proposal.evidenceMatch", ["tokenBoundary"]); stableIdentity(m.checkerVersion, "proposal.evidenceMatch.checkerVersion"); if (!SCHEMA_MATCHES.has(m.schema))
+    throw new Error("proposal.evidenceMatch.schema is invalid."); if (!VALUE_IN_EXCERPT_MATCHES.has(m.valueInExcerpt))
+    throw new Error("proposal.evidenceMatch.valueInExcerpt is invalid."); if (m.tokenBoundary !== undefined && typeof m.tokenBoundary !== "boolean")
+    throw new Error("proposal.evidenceMatch.tokenBoundary must be a boolean."); }
 function validateClaimTarget(v) { const t = obj(v, "claimTarget"); exact(t, ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior", "impactLevel"], "claimTarget", ["claimId", "evidenceType", "evidenceMethod", "collectedBy", "derivedFrom"]); for (const key of ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior"])
     nonEmpty(t[key], `claimTarget.${key}`); if (!["low", "medium", "high", "critical"].includes(t.impactLevel))
     throw new Error("claimTarget.impactLevel invalid."); for (const key of ["claimId", "evidenceType", "evidenceMethod", "collectedBy"])
@@ -429,10 +581,17 @@ 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 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

@@ -1,14 +1,14 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, InterpretationAnswerImpact, InterpretationReadingKind, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
 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, PortableExtractionOccurrence, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
+export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionCoverageEntry, PortableExtractionEvidenceMatch, PortableExtractionPartialReason, PortableExtractionOccurrence, PortableExtractionProducedBy, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
 export type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
 export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
@@ -17,7 +17,7 @@ export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js"
 export type { ReviewedCandidateResolutionInput } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-resolution.js";
-export { buildSurveyTrustBundle } from "./to-surface.js";
+export { buildSurveyTrustBundle, ReviewAgreementError } from "./to-surface.js";
 export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
 export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
 export type { BuildCanonicalReviewedTrustInputOptions, CanonicalReviewedTrustInput, } from "./canonical-reviewed-trust-input.js";
@@ -35,16 +35,17 @@ 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 { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
-export type { ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.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 { 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";
-export type { AutoAcceptPolicy, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
+export type { AutoAcceptWarning } from "./producer-profile.js";
+export type { AutoAcceptPolicy, AutoAcceptPolicyOptions, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
 export type { ExtractedStatement, LocatorResolution, StatementBadge, StatementValueComparison, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
-export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";
+export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SchemaMappingValue, SystemFieldRef, } from "./schema-mapping.js";
 export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
 export type { BuildAuthorizedActionAuthorizingInput, BuildPromptRefInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";
 export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";

package/dist/src/index.js

@@ -1,14 +1,14 @@
 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";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
-export { buildSurveyTrustBundle } from "./to-surface.js";
+export { buildSurveyTrustBundle, ReviewAgreementError } from "./to-surface.js";
 export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
@@ -17,7 +17,7 @@ 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 { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, 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/inquiry-mapping.d.ts

@@ -20,6 +20,7 @@
 import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
 import type { CanonicalClaimTarget } from "@kontourai/surface";
 import type { Candidate, CandidateSet, ReviewOutcome } from "./types.js";
+import type { AutoAcceptWarning } from "./producer-profile.js";
 import type { ReviewItem } from "./review-resource.js";
 /**
  * A single machine- or human-generated suggestion that a natural-language
@@ -140,18 +141,31 @@ export declare function applyMappingReview(candidateSet: CandidateSet, reviewOut
 export interface AutoAcceptPolicy {
     minConfidence: number;
 }
+/** Optional hooks for {@link applyAutoAcceptPolicy}. */
+export interface AutoAcceptPolicyOptions {
+    /**
+     * Called once for each proposal the policy refused because its confidence
+     * is not a finite number in [0, 1]. The proposal gets no mapping and stays
+     * in human review.
+     */
+    onWarning?: (warning: AutoAcceptWarning) => void;
+}
 /**
  * Apply an auto-accept policy to a list of proposals, returning InquiryMappings.
  *
  * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
  * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ * Proposals whose confidence is not a finite number in [0, 1] are never
+ * auto-accepted. Throws `RangeError` unless `policy.minConfidence` is a finite
+ * number in (0, 1]. Refused out-of-range proposals are reported through
+ * `options.onWarning`.
  *
  * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
  * need human review regardless of confidence.
  *
  * Returns an array of InquiryMappings (only for accepted proposals).
  */
-export declare function applyAutoAcceptPolicy(proposals: MappingProposal[], policy: AutoAcceptPolicy): InquiryMapping[];
+export declare function applyAutoAcceptPolicy(proposals: MappingProposal[], policy: AutoAcceptPolicy, options?: AutoAcceptPolicyOptions): InquiryMapping[];
 /**
  * Look up an InquiryMapping for a question by exact normalized-text match.
  *

package/dist/src/inquiry-mapping.js

@@ -18,7 +18,7 @@
  * and lives in the flow-agents repo.
  */
 import { resolveInquiry } from "@kontourai/surface";
-import { evaluateAutoAccept, getProducerProposal, hasCandidateConflict, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { assertValidAutoAcceptThreshold, evaluateAutoAccept, getProducerProposal, hasCandidateConflict, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { reviewResourceApiVersion } from "./review-resource.js";
 // ---------------------------------------------------------------------------
 // Question normalization
@@ -140,13 +140,18 @@ export function applyMappingReview(candidateSet, reviewOutcome) {
  *
  * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
  * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ * Proposals whose confidence is not a finite number in [0, 1] are never
+ * auto-accepted. Throws `RangeError` unless `policy.minConfidence` is a finite
+ * number in (0, 1]. Refused out-of-range proposals are reported through
+ * `options.onWarning`.
  *
  * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
  * need human review regardless of confidence.
  *
  * Returns an array of InquiryMappings (only for accepted proposals).
  */
-export function applyAutoAcceptPolicy(proposals, policy) {
+export function applyAutoAcceptPolicy(proposals, policy, options = {}) {
+    assertValidAutoAcceptThreshold(policy.minConfidence);
     if (proposals.length === 0)
         return [];
     // If proposals disagree, none can be auto-accepted
@@ -154,6 +159,9 @@ export function applyAutoAcceptPolicy(proposals, policy) {
         return [];
     return proposals.flatMap((proposal) => {
         const decision = evaluateAutoAccept({ confidence: proposal.confidence, rationale: proposal.rationale, proposedAt: proposal.proposedAt }, false, policy, proposal.proposedAt);
+        if (decision.warning) {
+            options.onWarning?.({ code: decision.warning, proposalId: proposal.id, confidence: decision.confidence });
+        }
         if (!decision.accepted)
             return [];
         return [