@kontourai/survey 4.0.0 → 6.0.0

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;
@@ -142,11 +168,52 @@ export interface ExtractionEnvelopeImportOptions {
     sourceKind: RawSource["kind"];
     /** Survey meaning is supplied at the boundary; it is not added to the upstream wire contract. */
     claimTarget: (proposal: PortableExtractionProposal, index: number) => ClaimTargetHint;
+    /**
+     * The prepared artifact as the caller resolved it (the same shape the source
+     * inspector takes). When supplied, the import checks the text against the
+     * envelope's prepared-artifact digest and length, and every proposal's span
+     * against its excerpt: a proposal whose span does not match gets no
+     * ReviewItem and an `excerpt-mismatch` diagnostic, and an artifact that does
+     * not verify makes the import `unresolved`. The text is not stored in the
+     * record. Without it the import records `status.provenance: "unverified"`.
+     */
+    artifact?: ResolvedExtractionArtifact;
 }
+export type ArtifactUnavailableCode = "not-found" | "storage-error" | "access-denied" | "invalid-artifact" | "unknown";
+/** A prepared artifact as a caller resolved it: its text and digest, or why it could not be read. */
+export type ResolvedExtractionArtifact = {
+    status: "available";
+    text: string;
+    actualDigest: string;
+} | {
+    status: "unavailable";
+    code: ArtifactUnavailableCode;
+} | {
+    status: "digest-mismatch";
+    actualDigest: string;
+};
+/**
+ * Whether the import checked its proposals' excerpts against the prepared
+ * artifact text. `verified` means the supplied text matched the envelope's
+ * digest and length and every proposal that produced a ReviewItem matched its
+ * span; `unverified` means no text was supplied, or the text did not verify
+ * (a diagnostic then says why). Records written before this field existed have
+ * no `provenance` and are unverified.
+ */
+export type ExtractionEnvelopeImportProvenance = "verified" | "unverified";
+/**
+ * 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";
     artifactRef?: string;
+    /** The caller's resolver code, present when the artifact supplied at import could not be read. */
+    code?: ArtifactUnavailableCode;
     message: string;
 } | {
     kind: "digest-mismatch";
@@ -154,6 +221,22 @@ 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;
+}
+/** The prepared text at this proposal's span is not its excerpt; the proposal produced no ReviewItem. */
+ | {
+    kind: "excerpt-mismatch";
+    proposalIndex: number;
+    locator: string;
+    message: string;
 };
 export interface ExtractionEnvelopeImport {
     apiVersion: typeof extractionEnvelopeImportApiVersion;
@@ -170,6 +253,7 @@ export interface ExtractionEnvelopeImport {
     status: {
         state: "grounded" | "unresolved";
         diagnostics: ExtractionEnvelopeImportDiagnostic[];
+        provenance?: ExtractionEnvelopeImportProvenance;
     };
 }
 export interface ExtractionEnvelopeImportResult {
@@ -182,9 +266,47 @@ 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;
 export declare function createExtractionEnvelopeResolutionIdentity(record: ExtractionEnvelopeImport, proposalIndex: number): ExtractionEnvelopeResolutionIdentity;
+/** Proposals the import excluded because their span did not match their excerpt. */
+export declare function excerptMismatchProposalIndices(record: ExtractionEnvelopeImport): Set<number>;
+/** Validate the caller-resolved artifact shape; resolver detail beyond the code is refused. */
+export declare function assertResolvedExtractionArtifact(artifact: unknown): asserts artifact is ResolvedExtractionArtifact;
+export type PreparedArtifactCheck = {
+    status: "aligned";
+    text: string;
+} | {
+    status: "unavailable";
+    code: ArtifactUnavailableCode;
+} | {
+    status: "digest-mismatch";
+    actualDigest: string;
+} | {
+    status: "wrong-length";
+};
+/**
+ * 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 declare function checkPreparedArtifact(prepared: PortableExtractionResultEnvelope["result"]["preparedArtifact"], artifact: ResolvedExtractionArtifact): PreparedArtifactCheck;
+/** Whether the verified prepared text at a proposal's `chars:` span is exactly its excerpt. */
+export declare function proposalSpanMatches(text: string, proposal: PortableExtractionProposal): boolean;
 /** Validate and defensively clone a persisted or browser-delivered import. */
 export declare function validateExtractionEnvelopeImport(value: unknown): ExtractionEnvelopeImport;