@kontourai/survey 7.0.0 → 8.0.0

package/dist/src/field-states.d.ts

@@ -0,0 +1,100 @@
+import { type CandidateVerification } from "./candidate-verification.js";
+import { type DecisionBasis, type DecisionCarryForward, type DecisionSupersession } from "./decision-carry-forward.js";
+import { type ExtractionEnvelopeImport } from "./extraction-envelope.js";
+import type { ReviewDecision } from "./review-resource.js";
+/**
+ * Per-field content and lifecycle states (#294), derived from records Survey
+ * holds and never stored as labels.
+ *
+ * Only states with a producer ship. `not_found` (the source was read in full
+ * and holds no value for the field) needs per-field chunk coverage and a
+ * per-field dropped-proposal count from the extractor, which no producer
+ * reports yet, so a field with no candidate in a complete run has no content
+ * state at all. Absence of a state never means verified.
+ */
+/** The claim-metadata key under which the Surface projection carries a field's states. */
+export declare const FIELD_STATE_METADATA_KEY = "survey.kontourai.io/field-state";
+/**
+ * What the extraction says about a field.
+ *
+ * - `value`: at least one candidate with evidence.
+ * - `conflicting`: two or more distinct candidate values for the one claim.
+ * - `unsupported`: every candidate has a verifier record saying contradicted
+ *   or not-addressed for its current value, and none saying supported.
+ * - `excluded`: the extraction proposed values for the field, but the import
+ *   left every one out because its excerpt was not at its cited span. The
+ *   field was read; its proposals are unverifiable, not disproven.
+ * - `not_covered`: no proposal at all, and the extraction reported that part
+ *   of the content was not read (a partial or failed run).
+ */
+export type FieldContentState = "value" | "conflicting" | "unsupported" | "excluded" | "not_covered";
+/**
+ * Where review stands for a field: `pending` (no decision), `accepted`,
+ * `rejected`, `could_not_confirm`, or `superseded` (a supersession record
+ * names the decision as replaced).
+ */
+export type FieldLifecycleState = "pending" | "accepted" | "rejected" | "could_not_confirm" | "superseded";
+/** A claim slot: the claim a proposal would project to, at its path indices. */
+export interface FieldSlot {
+    readonly subjectType: string;
+    readonly subjectId: string;
+    readonly facet: string;
+    readonly claimType: string;
+    readonly fieldOrBehavior: string;
+    readonly claimId?: string;
+    readonly pathIndices?: readonly number[];
+}
+/** Facts about a field that are not states. */
+export interface FieldStateSignals {
+    /** The run that produced this import stopped short or failed: other text may hold values. */
+    readonly incompleteRun?: true;
+    /** Proposals for this slot the import left out because their excerpt was not at their span. */
+    readonly excludedProposals?: number;
+    /** The import could not ground any candidate (its prepared artifact did not resolve or verify). */
+    readonly unresolvedImport?: true;
+}
+export interface FieldState {
+    readonly importName: string;
+    readonly slot: FieldSlot;
+    /** The ReviewItem for this slot, when the import produced one. */
+    readonly reviewItemName?: string;
+    /** Absent when no producer can state one (see the module note on `not_found`). */
+    readonly content?: FieldContentState;
+    /** Absent when the slot has no review item, so there is nothing to decide. */
+    readonly lifecycle?: FieldLifecycleState;
+    /** The decision the lifecycle comes from, when there is one. */
+    readonly decisionName?: string;
+    /** Whether that decision was made on this round's item or carried forward from an earlier one. */
+    readonly decisionBasis?: DecisionBasis;
+    readonly signals: FieldStateSignals;
+}
+export interface FieldStateImport {
+    readonly record: ExtractionEnvelopeImport;
+    /**
+     * The fields the extraction was asked for, so a field with no proposal is
+     * reported too. Without it only slots that have a proposal appear.
+     */
+    readonly expectedFields?: readonly FieldSlot[];
+}
+export interface DeriveFieldStatesInput {
+    readonly imports: readonly FieldStateImport[];
+    /** Decisions on this round's items. At most one per item. */
+    readonly decisions?: readonly ReviewDecision[];
+    /** Verifier records for this round's candidates (see `CandidateVerification`). */
+    readonly verifications?: readonly CandidateVerification[];
+    /** Records that the decisions they name as prior were replaced. */
+    readonly supersessions?: readonly DecisionSupersession[];
+    /** Earlier decisions carried forward onto this round's items. */
+    readonly carryForwards?: readonly DecisionCarryForward[];
+}
+/**
+ * Derives the content and lifecycle state of every field in the given
+ * imports. Pure: reads only its input. Each state appears only when the input
+ * that produces it is present: no verifications, no `unsupported`; no
+ * supersessions, no `superseded`.
+ */
+export declare function deriveFieldStates(input: DeriveFieldStatesInput): FieldState[];
+/** The lifecycle a workbench decision gives its item, as `deriveFieldStates` reads it. */
+export declare function lifecycleForDecision(decision: ReviewDecision | undefined): Exclude<FieldLifecycleState, "superseded">;
+/** The claim metadata the Surface projection carries for one field state. */
+export declare function fieldStateClaimMetadata(state: FieldState): Record<string, unknown>;

package/dist/src/field-states.js

@@ -0,0 +1,169 @@
+import { foldCandidateVerifications } from "./candidate-verification.js";
+import { decisionReference, decisionResolution, validateDecisionCarryForward, validateDecisionSupersession, } from "./decision-carry-forward.js";
+import { buildReviewItemsFromExtractionEnvelopeImport, excerptMismatchProposalIndices, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
+import { canonicalJson } from "./review-workbench/canonical.js";
+/**
+ * Per-field content and lifecycle states (#294), derived from records Survey
+ * holds and never stored as labels.
+ *
+ * Only states with a producer ship. `not_found` (the source was read in full
+ * and holds no value for the field) needs per-field chunk coverage and a
+ * per-field dropped-proposal count from the extractor, which no producer
+ * reports yet, so a field with no candidate in a complete run has no content
+ * state at all. Absence of a state never means verified.
+ */
+/** The claim-metadata key under which the Surface projection carries a field's states. */
+export const FIELD_STATE_METADATA_KEY = "survey.kontourai.io/field-state";
+/**
+ * Derives the content and lifecycle state of every field in the given
+ * imports. Pure: reads only its input. Each state appears only when the input
+ * that produces it is present: no verifications, no `unsupported`; no
+ * supersessions, no `superseded`.
+ */
+export function deriveFieldStates(input) {
+    const decisionsByItem = new Map();
+    for (const decision of input.decisions ?? []) {
+        const name = decision.spec.reviewItemName;
+        if (decisionsByItem.has(name))
+            throw new Error(`ReviewItem ${name} has more than one decision; field states read one decision per item.`);
+        decisionsByItem.set(name, decision);
+    }
+    const carriedByItem = new Map();
+    for (const raw of input.carryForwards ?? []) {
+        const record = validateDecisionCarryForward(raw);
+        if (carriedByItem.has(record.reviewItemName))
+            throw new Error(`ReviewItem ${record.reviewItemName} has more than one carried-forward decision.`);
+        carriedByItem.set(record.reviewItemName, record);
+    }
+    const supersededDigests = new Set((input.supersessions ?? []).map((raw) => validateDecisionSupersession(raw).priorDecision.digest));
+    const verifications = input.verifications;
+    const states = [];
+    for (const entry of input.imports) {
+        const record = validateExtractionEnvelopeImport(entry.record);
+        const importName = record.metadata.name;
+        const outcome = record.spec.envelope.result.outcome.status;
+        const incompleteRun = outcome === "partial" || outcome === "failure";
+        const unresolvedImport = record.status.state === "unresolved";
+        const baseSignals = (excluded) => ({
+            ...(incompleteRun ? { incompleteRun: true } : {}),
+            ...(excluded > 0 ? { excludedProposals: excluded } : {}),
+            ...(unresolvedImport ? { unresolvedImport: true } : {}),
+        });
+        const excludedBySlot = new Map();
+        for (const index of excerptMismatchProposalIndices(record)) {
+            const key = slotKey(proposalSlot(record, index));
+            excludedBySlot.set(key, (excludedBySlot.get(key) ?? 0) + 1);
+        }
+        const seen = new Set();
+        for (const item of buildReviewItemsFromExtractionEnvelopeImport(record)) {
+            const slot = itemSlot(record, item);
+            const key = slotKey(slot);
+            seen.add(key);
+            const lifecycle = lifecycleFor(item, decisionsByItem, carriedByItem, supersededDigests);
+            states.push({
+                importName,
+                slot,
+                reviewItemName: item.metadata.name,
+                content: contentFor(item, verifications),
+                ...lifecycle,
+                signals: baseSignals(excludedBySlot.get(key) ?? 0),
+            });
+        }
+        // A slot whose every proposal was excluded has no item; it still appears,
+        // so a dropped proposal never vanishes from the field's record.
+        for (const [key, count] of excludedBySlot) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const index = [...excerptMismatchProposalIndices(record)].find((proposalIndex) => slotKey(proposalSlot(record, proposalIndex)) === key);
+            // Proposals were made, so the field was read: `excluded`, never `not_covered`.
+            states.push({ importName, slot: proposalSlot(record, index), content: "excluded", signals: baseSignals(count) });
+        }
+        for (const expected of entry.expectedFields ?? []) {
+            const slot = normalizeSlot(expected);
+            const key = slotKey(slot);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            states.push({ importName, slot, ...(incompleteRun ? { content: "not_covered" } : {}), signals: baseSignals(0) });
+        }
+    }
+    return states;
+}
+/** The lifecycle a workbench decision gives its item, as `deriveFieldStates` reads it. */
+export function lifecycleForDecision(decision) {
+    if (!decision)
+        return "pending";
+    return decisionResolution(decision) ?? "pending";
+}
+/** The claim metadata the Surface projection carries for one field state. */
+export function fieldStateClaimMetadata(state) {
+    return {
+        schemaVersion: 1,
+        ...(state.content !== undefined ? { content: state.content } : {}),
+        ...(state.lifecycle !== undefined ? { lifecycle: state.lifecycle } : {}),
+        ...(state.decisionBasis !== undefined ? { decisionBasis: state.decisionBasis } : {}),
+        ...(Object.keys(state.signals).length ? { signals: { ...state.signals } } : {}),
+    };
+}
+function lifecycleFor(item, decisionsByItem, carriedByItem, supersededDigests) {
+    const decision = decisionsByItem.get(item.metadata.name);
+    if (decision) {
+        const superseded = supersededDigests.has(decisionReference(decision).digest);
+        return { lifecycle: superseded ? "superseded" : lifecycleForDecision(decision), decisionName: decision.metadata.name, decisionBasis: "affirmed" };
+    }
+    const carried = carriedByItem.get(item.metadata.name);
+    if (carried) {
+        if (carried.candidateId !== undefined && !item.spec.candidates.some((candidate) => candidate.id === carried.candidateId)) {
+            throw new Error(`Carried-forward decision for ${item.metadata.name} names candidate ${carried.candidateId}, which the item does not hold.`);
+        }
+        const superseded = supersededDigests.has(carried.priorDecision.digest);
+        return { lifecycle: superseded ? "superseded" : carried.resolution, decisionName: carried.priorDecision.name, decisionBasis: "carried-forward" };
+    }
+    return { lifecycle: "pending" };
+}
+function contentFor(item, verifications) {
+    if (verifications !== undefined && item.spec.candidates.every((candidate) => candidateUnsupported(candidate, verifications)))
+        return "unsupported";
+    return item.spec.candidates.length > 1 ? "conflicting" : "value";
+}
+/** A candidate with a contradicted or not-addressed record for its current value, and no supported one. */
+function candidateUnsupported(candidate, verifications) {
+    const { applicable } = foldCandidateVerifications({ candidateId: candidate.id, value: candidate.value }, verifications);
+    const verdicts = applicable.filter((record) => record.result !== "abstain");
+    return verdicts.length > 0 && verdicts.every((record) => record.result === "contradicted" || record.result === "not-addressed");
+}
+function itemSlot(record, item) {
+    const binding = item.metadata.producer?.["survey.kontourai.io/extraction-envelope"];
+    const first = binding?.proposalIndices?.[0];
+    if (first === undefined)
+        throw new Error(`ReviewItem ${item.metadata.name} carries no proposal binding.`);
+    return proposalSlot(record, first);
+}
+function proposalSlot(record, index) {
+    const target = record.spec.claimTargets[index];
+    const proposal = record.spec.envelope.result.proposals[index];
+    return normalizeSlot({
+        subjectType: target.subjectType, subjectId: target.subjectId, facet: target.facet, claimType: target.claimType,
+        fieldOrBehavior: target.fieldOrBehavior, ...(target.claimId !== undefined ? { claimId: target.claimId } : {}),
+        ...(proposal.pathIndices !== undefined ? { pathIndices: proposal.pathIndices } : {}),
+    });
+}
+function normalizeSlot(slot) {
+    for (const key of ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior"]) {
+        if (typeof slot[key] !== "string" || slot[key].trim() === "")
+            throw new Error(`Field slot ${key} must be a non-empty string.`);
+    }
+    return {
+        subjectType: slot.subjectType, subjectId: slot.subjectId, facet: slot.facet, claimType: slot.claimType, fieldOrBehavior: slot.fieldOrBehavior,
+        ...(slot.claimId !== undefined ? { claimId: slot.claimId } : {}),
+        ...(slot.pathIndices !== undefined ? { pathIndices: [...slot.pathIndices] } : {}),
+    };
+}
+/** The same identity the importer groups a claim slot by. */
+function slotKey(slot) {
+    return canonicalJson({
+        subjectType: slot.subjectType, subjectId: slot.subjectId, facet: slot.facet, claimType: slot.claimType,
+        fieldOrBehavior: slot.fieldOrBehavior, claimId: slot.claimId ?? null, pathIndices: slot.pathIndices ?? null,
+    });
+}

package/dist/src/index.d.ts

@@ -9,7 +9,7 @@ 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, 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 type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewSessionPresentation, ReviewSessionSampling, 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";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
@@ -58,3 +58,5 @@ export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversight
 export type { AggregateOversightMetrics, DeriveOversightMetricsOptions, OversightMetrics, OversightMetricsClaimsSubject, OversightQualityClaim, ReviewerOversightMetrics, } from "./oversight-metrics.js";
 export { calibrationToClaims, deriveCalibration, mergeTrustBundleWithCalibration, } from "./calibration.js";
 export type { CalibrationBin, CalibrationClaim, CalibrationClaimsSubject, CalibrationGroup, CalibrationInput, CalibrationMetrics, CalibrationSample, DeriveCalibrationOptions, } from "./calibration.js";
+export { deriveFieldStates, fieldStateClaimMetadata, lifecycleForDecision, FIELD_STATE_METADATA_KEY, type DeriveFieldStatesInput, type FieldContentState, type FieldLifecycleState, type FieldSlot, type FieldState, type FieldStateImport, type FieldStateSignals, } from "./field-states.js";
+export { buildDecisionSupersession, decisionCarryForwardKind, decisionReference, decisionResolution, decisionSupersessionKind, defaultCarryForwardPolicy, splitRoundForCarryForward, validateDecisionCarryForward, validateDecisionSupersession, type BuildDecisionSupersessionInput, type CarriedForwardItem, type CarriedResolution, type CarryForwardPolicy, type DecisionBasis, type DecisionCarryForward, type DecisionReference, type DecisionSupersession, type NeedsReviewItem, type NeedsReviewReason, type PriorRoundDecision, type RoundReviewItem, type SplitRoundForCarryForwardInput, type SplitRoundForCarryForwardResult, type SupersessionReason, } from "./decision-carry-forward.js";

package/dist/src/index.js

@@ -28,3 +28,5 @@ export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./v
 export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
 export { calibrationToClaims, deriveCalibration, mergeTrustBundleWithCalibration, } from "./calibration.js";
+export { deriveFieldStates, fieldStateClaimMetadata, lifecycleForDecision, FIELD_STATE_METADATA_KEY, } from "./field-states.js";
+export { buildDecisionSupersession, decisionCarryForwardKind, decisionReference, decisionResolution, decisionSupersessionKind, defaultCarryForwardPolicy, splitRoundForCarryForward, validateDecisionCarryForward, validateDecisionSupersession, } from "./decision-carry-forward.js";

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

@@ -3,7 +3,7 @@ import { resolve, dirname } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
-import { attestReviewQueueExtraction, buildReviewSessionEvents, conflictSelectionIssue, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
+import { attestReviewQueueExtraction, buildReviewSessionEvents, conflictSelectionIssue, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, isScoreBlind, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
 import { buildReviewItemPresentation, candidateVerificationNotes, excludedProposalsSentence, excludedProposalsUnreadableSentence } from "../review-workbench/review-presentation.js";
 import { appendReviewSessionEvents, readReviewSessionFile, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
@@ -41,6 +41,14 @@ function attestedQueue(file) {
 function attestationLines(attestation) {
     return attestation.state === "unverified" ? [attestation.message, ``] : [];
 }
+/**
+ * A score-blind session shows no confidence and no verifier result on any
+ * surface (text, data or card), so the decision is made without them.
+ */
+const SCORE_BLIND_NOTICE = "Score-blind review: confidence and verifier results are hidden for this whole session. Decide from the source and its excerpt.";
+function scoreBlindLines(state) {
+    return isScoreBlind(state) ? [`${state.sampling?.kind === "random-audit" ? "Random audit sample. " : ""}${SCORE_BLIND_NOTICE}`, ``] : [];
+}
 // ---- Queue helpers -------------------------------------------------------
 function queueSummaryText(snapshot, events, attestation) {
     const current = currentSessionState(snapshot, events);
@@ -57,6 +65,7 @@ function queueSummaryText(snapshot, events, attestation) {
     });
     return [
         ...attestationLines(attestation),
+        ...scoreBlindLines(current),
         `Review queue: ${resolved}/${total} resolved`,
         `Active item: ${activeItem.metadata.name} (${activeItem.spec.target})`,
         ...(nextItem ? [`Next unresolved: ${nextItem}`] : ["All items resolved."]),
@@ -77,8 +86,11 @@ function itemDetailText(item, snapshot, events, attestation) {
     const proposedCandidates = item.spec.candidates.filter((c) => c.role === "proposed");
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "unknown";
+    const blind = isScoreBlind(current);
+    const confidenceLine = (c) => blind ? [] : [`  confidence: ${confStr(c)}`];
     const lines = [
         ...attestationLines(attestation),
+        ...scoreBlindLines(current),
         `Item: ${item.metadata.name}`,
         `Target: ${item.spec.target}`,
         `Status: ${status}`,
@@ -87,7 +99,7 @@ function itemDetailText(item, snapshot, events, attestation) {
         ...(note ? [`Note: ${note}`] : []),
         ``,
         `Current value: ${valueStr(currentCandidate?.value ?? "(none)")}`,
-        `  confidence: ${confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence)}`,
+        ...confidenceLine(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence),
         `  source: ${currentCandidate?.source?.sourceRef ?? "none"}`,
         ...(currentCandidate?.locator?.excerpt ? [`  excerpt: ${currentCandidate.locator.excerpt}`] : []),
         ``,
@@ -100,12 +112,12 @@ function itemDetailText(item, snapshot, events, attestation) {
         ...(proposedCandidates.length === 0 ? [`Proposed value: (none)`] : proposedCandidates.flatMap((candidate) => [
             `Proposed value: ${valueStr(candidate.value)}${chosenId === undefined ? "" : candidate.id === chosenId ? " [chosen]" : " [not chosen]"}`,
             ...(proposedCandidates.length > 1 ? [`  candidateId: ${candidate.id}`] : []),
-            `  confidence: ${confStr(candidate.extraction?.confidence ?? candidate.confidence)}`,
+            ...confidenceLine(candidate.extraction?.confidence ?? candidate.confidence),
             `  source: ${candidate.source?.sourceRef ?? "none"}`,
             ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
         ])),
         ...extractionImportLines(item),
-        ...candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`]),
+        ...(blind ? [] : candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`])),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
@@ -113,6 +125,13 @@ function itemDetailText(item, snapshot, events, attestation) {
     return lines.join("\n");
 }
 /** The reviewer's edit when the item's decision accepts one; verifier records are read against it. */
+/** The session's presentation and sampling, as a client should read them. */
+function sessionConditions(snapshot) {
+    return {
+        ...(snapshot.presentation !== undefined ? { presentation: snapshot.presentation } : {}),
+        ...(snapshot.sampling !== undefined ? { sampling: snapshot.sampling } : {}),
+    };
+}
 function editedValueFor(item, state) {
     return state.decisionsByItemName[item.metadata.name] === "accept-proposed" ? state.editedValuesByItemName?.[item.metadata.name] : undefined;
 }
@@ -157,8 +176,10 @@ function buildReviewCardHtml(item, snapshot, events, attestation) {
     const status = deriveQueueRowStatus(item, current);
     const valueStr = (v) => typeof v === "string" ? v : JSON.stringify(v, null, 2);
     const confStr = (c) => c !== undefined ? `${Math.round(c * 100)}%` : "—";
+    const blind = isScoreBlind(current);
+    const confHtml = (c) => blind ? "" : `<div class="conf">confidence ${confStr(c)}</div>`;
     const currentValue = valueStr(currentCandidate?.value ?? "—");
-    const currentConf = confStr(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
+    const currentConf = confHtml(currentCandidate?.extraction?.confidence ?? currentCandidate?.confidence);
     const currentSource = currentCandidate?.source?.sourceRef ?? "—";
     const currentExcerpt = currentCandidate?.locator?.excerpt ?? "";
     const proposedCard = (candidate, label) => {
@@ -174,7 +195,7 @@ function buildReviewCardHtml(item, snapshot, events, attestation) {
         return `<div class="card is-proposed"${conflict && candidate ? ` data-candidate-id="${escapeHtml(candidate.id)}"` : ""}>
     <div class="card-label">${escapeHtml(label)}</div>
     <div class="value">${value.includes("\n") ? `<pre>${escapeHtml(value)}</pre>` : escapeHtml(value)}</div>
-    <div class="conf">confidence ${confStr(candidate?.extraction?.confidence ?? candidate?.confidence)}</div>
+    ${confHtml(candidate?.extraction?.confidence ?? candidate?.confidence)}
     <div class="source-ref">${escapeHtml(candidate?.source?.sourceRef ?? "—")}</div>
     ${excerpt ? `<div class="excerpt">${escapeHtml(excerpt)}</div>` : ""}
     ${choice}
@@ -187,7 +208,7 @@ function buildReviewCardHtml(item, snapshot, events, attestation) {
     const itemPresentation = buildReviewItemPresentation(item);
     const excludedNote = excludedProposalsSentence(itemPresentation.excludedProposals);
     const unreadableNote = excludedProposalsUnreadableSentence(itemPresentation.excludedProposalsUnreadable);
-    const verificationNotes = candidateVerificationNotes(item, editedValueFor(item, current));
+    const verificationNotes = blind ? [] : candidateVerificationNotes(item, editedValueFor(item, current));
     const decisionBadge = decision
         ? `<span class="badge badge-${decision === "accept-proposed" || decision === "select-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(decision === "select-proposed" ? `Chose 1 of ${proposedCandidates.length} values` : workbenchDecisionDefinitions[decision].label)}</span>`
         : `<span class="badge badge-pending">${escapeHtml(status)}</span>`;
@@ -276,6 +297,7 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 </head>
 <body>
 ${attestation.state === "unverified" ? `<p class="notice" id="unverified-queue-note">${escapeHtml(attestation.message)}</p>` : ""}
+${blind ? `<p class="notice" id="score-blind-note">${escapeHtml(scoreBlindLines(current)[0])}</p>` : ""}
 <p class="eyebrow">Survey Review</p>
 <h1>${escapeHtml(item.spec.target)}</h1>
 <div class="meta">
@@ -289,7 +311,7 @@ ${attestation.state === "unverified" ? `<p class="notice" id="unverified-queue-n
   <div class="card">
     <div class="card-label">Current</div>
     <div class="value">${currentValue.includes("\n") ? `<pre>${escapeHtml(currentValue)}</pre>` : escapeHtml(currentValue)}</div>
-    <div class="conf">confidence ${currentConf}</div>
+    ${currentConf}
     <div class="source-ref">${escapeHtml(currentSource)}</div>
     ${currentExcerpt ? `<div class="excerpt">${escapeHtml(currentExcerpt)}</div>` : ""}
   </div>
@@ -376,6 +398,7 @@ async function toolQueue(options) {
     const text = queueSummaryText(snapshot, events, attestation);
     const queueData = {
         queueAttestation: attestation.state,
+        ...sessionConditions(snapshot),
         items: snapshot.items.map((item) => {
             const current = currentSessionState(snapshot, events);
             const selectedCandidateId = current.decisionsByItemName[item.metadata.name] === "select-proposed"
@@ -413,8 +436,10 @@ async function toolItem(itemName, options) {
     const text = itemDetailText(item, snapshot, events, attestation);
     const decision = current.decisionsByItemName[item.metadata.name];
     const selectedCandidateId = decision === "select-proposed" ? current.selectedCandidateIdsByItemName?.[item.metadata.name] : undefined;
+    const blind = isScoreBlind(current);
     const itemData = {
         queueAttestation: attestation.state,
+        ...sessionConditions(snapshot),
         name: item.metadata.name,
         target: item.spec.target,
         status: deriveQueueRowStatus(item, current),
@@ -431,14 +456,14 @@ async function toolItem(itemName, options) {
             };
         })(),
         candidates: (() => {
-            const notes = candidateVerificationNotes(item, editedValueFor(item, current));
+            const notes = blind ? [] : candidateVerificationNotes(item, editedValueFor(item, current));
             return item.spec.candidates.map((c, index) => {
                 const note = notes.find((entry) => entry.candidateIndex === index);
                 return {
                     id: c.id,
                     role: c.role,
                     value: c.value,
-                    confidence: c.extraction?.confidence ?? c.confidence,
+                    ...(blind ? {} : { confidence: c.extraction?.confidence ?? c.confidence }),
                     sourceRef: c.source?.sourceRef,
                     excerpt: c.locator?.excerpt,
                     ...(selectedCandidateId !== undefined && c.role === "proposed" ? { chosen: c.id === selectedCandidateId } : {}),

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

@@ -207,7 +207,36 @@ export interface ReviewDecisionSpec {
      * decisions recorded before choosing between conflicting values existed.
      */
     unselectedCandidateIds?: string[];
+    /**
+     * The presentation of the session the decision was made in, copied from the
+     * session (never supplied by the reviewer). `{ scoreBlind: true }` means the
+     * reviewer saw no confidence and no verifier result before deciding.
+     * Absent on decisions from sessions that declare none.
+     */
+    presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen, copied from the session. */
+    sampling?: ReviewSessionSampling;
 }
+/**
+ * How a session presents items to its reviewer, fixed by the session (never
+ * by the reviewer). `scoreBlind` hides every proposer confidence and every
+ * verifier result on every decision surface for the whole session, so the
+ * decision is made without them.
+ */
+export interface ReviewSessionPresentation {
+    readonly scoreBlind: boolean;
+}
+/**
+ * How the session's items were chosen: the ordinary review `queue`, or a
+ * seeded `random-audit` draw at `rate` (see `drawRandomAuditSample`).
+ */
+export type ReviewSessionSampling = {
+    readonly kind: "queue";
+} | {
+    readonly kind: "random-audit";
+    readonly rate: number;
+    readonly seed: string;
+};
 export interface ReviewDecisionStatus {
     appliedToClaimIds?: string[];
 }

package/dist/src/review-workbench/audit-sample.d.ts

@@ -0,0 +1,32 @@
+import type { ReviewItem } from "../review-resource.js";
+import { type ReviewQueueSessionState } from "./review-queue-session.js";
+export interface RandomAuditSampleOptions {
+    /** Inclusion probability for each item, greater than 0 and at most 1. */
+    readonly rate: number;
+    /** Any non-empty string. The same seed and items always draw the same sample. */
+    readonly seed: string;
+}
+/**
+ * Draws a seeded random audit sample from `items`, for example the items an
+ * auto-accept threshold would have accepted without review.
+ *
+ * Each item is included on its own when a SHA-256 of `(seed, item name)`,
+ * read as a number in [0, 1), is below `rate`. The draw is deterministic, does
+ * not depend on the order of `items`, and an item's inclusion does not change
+ * when other items are added or removed. Items keep their input order. Item
+ * names must be unique.
+ */
+export declare function drawRandomAuditSample(items: readonly ReviewItem[], options: RandomAuditSampleOptions): ReviewItem[];
+/**
+ * Draws a random audit sample (see {@link drawRandomAuditSample}) and opens it
+ * as a score-blind review session: the session hides every confidence and
+ * verifier result, and each decision made in it records
+ * `presentation: { scoreBlind: true }` and
+ * `sampling: { kind: "random-audit", rate, seed }`.
+ *
+ * Throws when the draw selects no item, since a session needs one.
+ */
+export declare function openRandomAuditSession(items: readonly ReviewItem[], options: RandomAuditSampleOptions & {
+    readonly reviewedAt?: string;
+    readonly actorId?: string;
+}): ReviewQueueSessionState;

package/dist/src/review-workbench/audit-sample.js

@@ -0,0 +1,53 @@
+import { sha256Hex } from "../sha256.js";
+import { canonicalJson } from "./canonical.js";
+import { assertAuditRate, assertAuditSeed, initialReviewQueueSessionState, } from "./review-queue-session.js";
+/**
+ * Draws a seeded random audit sample from `items`, for example the items an
+ * auto-accept threshold would have accepted without review.
+ *
+ * Each item is included on its own when a SHA-256 of `(seed, item name)`,
+ * read as a number in [0, 1), is below `rate`. The draw is deterministic, does
+ * not depend on the order of `items`, and an item's inclusion does not change
+ * when other items are added or removed. Items keep their input order. Item
+ * names must be unique.
+ */
+export function drawRandomAuditSample(items, options) {
+    assertAuditRate(options.rate);
+    assertAuditSeed(options.seed);
+    const names = new Set();
+    for (const item of items) {
+        if (names.has(item.metadata.name)) {
+            throw new Error(`Audit sample items must have unique names; ${item.metadata.name} appears twice.`);
+        }
+        names.add(item.metadata.name);
+    }
+    return items.filter((item) => auditDraw(options.seed, item.metadata.name) < options.rate);
+}
+/**
+ * Draws a random audit sample (see {@link drawRandomAuditSample}) and opens it
+ * as a score-blind review session: the session hides every confidence and
+ * verifier result, and each decision made in it records
+ * `presentation: { scoreBlind: true }` and
+ * `sampling: { kind: "random-audit", rate, seed }`.
+ *
+ * Throws when the draw selects no item, since a session needs one.
+ */
+export function openRandomAuditSession(items, options) {
+    const sample = drawRandomAuditSample(items, options);
+    if (sample.length === 0) {
+        throw new Error(`The random audit sample at rate ${options.rate} drew no items from ${items.length}; use a higher rate or more items.`);
+    }
+    const base = initialReviewQueueSessionState(sample);
+    return {
+        ...base,
+        ...(options.reviewedAt !== undefined ? { reviewedAt: options.reviewedAt } : {}),
+        ...(options.actorId !== undefined ? { actorId: options.actorId } : {}),
+        presentation: { scoreBlind: true },
+        sampling: { kind: "random-audit", rate: options.rate, seed: options.seed },
+    };
+}
+/** A deterministic number in [0, 1) from the first 52 bits of a SHA-256. */
+function auditDraw(seed, itemName) {
+    const hex = sha256Hex(canonicalJson(["survey.random-audit.v1", seed, itemName])).slice(0, 13);
+    return Number.parseInt(hex, 16) / 2 ** 52;
+}

package/dist/src/review-workbench/extraction-inspector.d.ts

@@ -88,7 +88,7 @@ export interface ExtractionInspectorSource {
     }>;
     /**
      * Whether the import checked excerpts against the prepared artifact
-     * (`status.provenance`; a record without it is `unverified`). Always set by
+     * (`status.provenance`, required on every import record). Always set by
      * {@link buildExtractionInspectorModel}; optional for hand-authored models.
      */
     importProvenance?: "verified" | "unverified";

package/dist/src/review-workbench/extraction-inspector.js

@@ -25,7 +25,7 @@ export function buildExtractionInspectorModel(input) {
         if (sourceKeys.has(sourceKey))
             throw new Error("Extraction inspector source identity collision.");
         sourceKeys.add(sourceKey);
-        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.diagnostics, entry.artifact, envelope.result.ocrDerived, envelope.result.proposals, record.status.provenance ?? "unverified");
+        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.diagnostics, entry.artifact, envelope.result.ocrDerived, envelope.result.proposals, record.status.provenance);
         sources.push(source);
         const candidateStart = candidates.length;
         const itemByProposalIndex = new Map();

package/dist/src/review-workbench/field-state-view.d.ts

@@ -0,0 +1,15 @@
+import type { FieldState } from "../field-states.js";
+import { type ReviewQueueSessionState } from "./review-queue-session.js";
+/**
+ * The field-state panel: one row per field the extraction was asked for or
+ * proposed, with its derived content state, its lifecycle, and its signals.
+ * Fields with no review card (not read, only excluded proposals, no proposal)
+ * are listed too, so a run that lost content never reads as complete.
+ *
+ * The lifecycle of a field in the queue is read from the live session, so it
+ * follows the reviewer's decisions. Only what the session cannot know comes
+ * from the derived states: a decision carried forward from an earlier round,
+ * and a superseded one. In a score-blind session a content state derived from
+ * verifier records is shown as the state its candidates alone give.
+ */
+export declare function renderFieldStatesHtml(states: readonly FieldState[], session: ReviewQueueSessionState): string;