@kontourai/survey 6.1.0 → 8.0.0

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;

package/dist/src/review-workbench/field-state-view.js

@@ -0,0 +1,84 @@
+import { isScoreBlind } from "./review-queue-session.js";
+const CONTENT_TEXT = {
+    value: "Value found",
+    conflicting: "Conflicting values",
+    unsupported: "Not supported by verifier",
+    excluded: "Proposals excluded",
+    not_covered: "Not read",
+};
+const LIFECYCLE_TEXT = {
+    pending: "Needs review",
+    accepted: "Accepted",
+    rejected: "Rejected",
+    could_not_confirm: "Could not confirm",
+    superseded: "Superseded",
+};
+const WORKBENCH_LIFECYCLE = {
+    "accept-proposed": "accepted",
+    "select-proposed": "accepted",
+    "keep-current": "accepted",
+    "reject-proposed": "rejected",
+    "could-not-confirm": "could_not_confirm",
+};
+/**
+ * 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 function renderFieldStatesHtml(states, session) {
+    if (states.length === 0)
+        return "";
+    const itemsByName = new Map(session.items.map((item) => [item.metadata.name, item]));
+    const rows = states.map((state) => {
+        const item = state.reviewItemName !== undefined ? itemsByName.get(state.reviewItemName) : undefined;
+        const content = state.content === "unsupported" && isScoreBlind(session)
+            ? (item && item.spec.candidates.filter((candidate) => candidate.role === "proposed").length > 1 ? "conflicting" : "value")
+            : state.content;
+        const live = item ? session.decisionsByItemName[item.metadata.name] : undefined;
+        const lifecycle = live !== undefined
+            ? WORKBENCH_LIFECYCLE[live]
+            : state.lifecycle === "superseded" || state.decisionBasis === "carried-forward"
+                ? state.lifecycle
+                : state.reviewItemName !== undefined ? "pending" : undefined;
+        const carried = live === undefined && state.decisionBasis === "carried-forward";
+        const signals = [
+            ...(state.signals.incompleteRun ? ["The extraction stopped before reading all of the source."] : []),
+            ...(state.signals.excludedProposals ? [`${state.signals.excludedProposals} proposal${state.signals.excludedProposals === 1 ? " was" : "s were"} excluded: the excerpt is not at the cited span.`] : []),
+            ...(state.signals.unresolvedImport ? ["The import could not ground any value."] : []),
+        ];
+        const label = `${state.slot.fieldOrBehavior}${state.slot.pathIndices?.length ? `[${state.slot.pathIndices.join("][")}]` : ""}`;
+        return `
+      <li class="field-state-row" data-testid="field-state" data-field="${escapeHtml(label)}" data-content="${content ?? "none"}" data-lifecycle="${lifecycle ?? "none"}"${carried ? ' data-basis="carried-forward"' : ""}>
+        <span class="field-state-name">${escapeHtml(label)}</span>
+        <span class="field-state-chips">
+          <span class="chip state-content ${content ?? "none"}" data-testid="field-state-content">${escapeHtml(content === undefined ? "No proposal" : CONTENT_TEXT[content])}</span>
+          ${lifecycle === undefined ? "" : `<span class="chip state-lifecycle ${lifecycle}" data-testid="field-state-lifecycle">${escapeHtml(LIFECYCLE_TEXT[lifecycle])}${carried ? " · carried forward" : ""}</span>`}
+        </span>
+        ${content === undefined ? `<span class="field-state-note">No value was proposed. That is not the same as the source not stating one.</span>` : ""}
+        ${signals.map((signal) => `<span class="field-state-note signal" data-testid="field-state-signal">${escapeHtml(signal)}</span>`).join("")}
+      </li>`;
+    }).join("");
+    const unread = states.filter((state) => state.content === "not_covered").length;
+    return `
+    <section class="field-states" data-testid="field-states" aria-label="Field states">
+      <h2>Field states</h2>
+      ${unread > 0 ? `<p class="field-states-lead" data-testid="field-states-incomplete">${unread} field${unread === 1 ? " was" : "s were"} not read: the extraction stopped short. ${unread === 1 ? "It has" : "They have"} no value to review, and that does not mean the source lacks ${unread === 1 ? "it" : "them"}.</p>` : ""}
+      <ul>${rows}</ul>
+    </section>
+  `;
+}
+function escapeHtml(value) {
+    return String(value)
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/src/review-workbench/queue-binding.d.ts

@@ -1,6 +1,6 @@
 import type { ReviewQueueSessionState } from "./review-queue-session.js";
 import { reviewResourceApiVersion, type ReviewItem } from "../review-resource.js";
-import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import { type ExtractionEnvelopeImport, type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
 /**
  * The durable attestation record. Serializable; a consumer stores it beside the
  * queue when the round opens and presents it, unchanged, at every later
@@ -78,7 +78,7 @@ export declare function bindReviewQueue(snapshot: ReviewQueueSessionState, optio
  */
 export declare function validateReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): ReviewQueueBindingIssue[];
 export declare function assertReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): void;
-export type ReviewQueueExtractionIssueCode = "import-not-grounded" | "empty-queue" | "item-missing-from-queue" | "item-not-in-extraction" | "item-diverges-from-extraction";
+export type ReviewQueueExtractionIssueCode = "import-invalid" | "import-not-grounded" | "empty-queue" | "item-missing-from-queue" | "item-not-in-extraction" | "item-diverges-from-extraction";
 export interface ReviewQueueExtractionIssue {
     readonly code: ReviewQueueExtractionIssueCode;
     readonly message: string;
@@ -124,4 +124,47 @@ export declare class UnattestedExtractionQueueError extends Error {
  * cross-check the label.
  */
 export declare function validateReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): ReviewQueueExtractionIssue[];
+/**
+ * What a reload path can say about a stored queue and the extraction import it
+ * came from:
+ *
+ * - `attested`: an import record was supplied and the queue matches it (see
+ *   {@link validateReviewQueueAgainstExtractionImport}).
+ * - `diverges`: an import record was supplied and the queue does not match it,
+ *   or the record itself is invalid. The queue must not be reviewed.
+ * - `unverified`: items carry the extraction-envelope binding but no import
+ *   record was supplied, so nothing checked them. A rival value deleted from
+ *   the stored queue would not show; every surface says so.
+ * - `not-extraction`: no item carries the binding and no record was supplied;
+ *   there is no import to check against.
+ *
+ * Detection reads the binding the import writes on every item and candidate.
+ * A writer that strips it from every item also strips every other extraction
+ * fact from the queue; keeping the stored import record beside the queue is
+ * what makes a reload path able to check it.
+ */
+export type ReviewQueueExtractionAttestation = {
+    readonly state: "attested";
+} | {
+    readonly state: "not-extraction";
+} | {
+    readonly state: "unverified";
+    readonly itemNames: readonly string[];
+    readonly message: string;
+} | {
+    readonly state: "diverges";
+    readonly issues: readonly ReviewQueueExtractionIssue[];
+    readonly message: string;
+};
+/** Whether a ReviewItem, or any of its candidates, carries the extraction-envelope binding. */
+export declare function reviewItemCarriesExtractionBinding(item: ReviewItem): boolean;
+/**
+ * Check a queue a reload path is about to present against its extraction
+ * import. Pass the import record (or import result) stored beside the queue;
+ * pass `undefined` when the path has none, and the result says whether that
+ * leaves the queue unverified.
+ */
+export declare function attestReviewQueueExtraction(items: readonly ReviewItem[], extractionImport: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult | undefined): ReviewQueueExtractionAttestation;
+/** The notice every surface shows for an `unverified` queue. */
+export declare function unverifiedExtractionQueueSentence(itemCount: number): string;
 export declare function assertReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): void;

package/dist/src/review-workbench/queue-binding.js

@@ -276,6 +276,51 @@ export function validateReviewQueueAgainstExtractionImport(items, importResult)
     }
     return issues;
 }
+const EXTRACTION_ENVELOPE_PRODUCER = "survey.kontourai.io/extraction-envelope";
+/** Whether a ReviewItem, or any of its candidates, carries the extraction-envelope binding. */
+export function reviewItemCarriesExtractionBinding(item) {
+    const bound = (producer) => producer !== undefined && producer !== null && typeof producer === "object" && Object.hasOwn(producer, EXTRACTION_ENVELOPE_PRODUCER);
+    return bound(item.metadata?.producer) || (Array.isArray(item.spec?.candidates) && item.spec.candidates.some((candidate) => bound(candidate?.producer)));
+}
+/**
+ * Check a queue a reload path is about to present against its extraction
+ * import. Pass the import record (or import result) stored beside the queue;
+ * pass `undefined` when the path has none, and the result says whether that
+ * leaves the queue unverified.
+ */
+export function attestReviewQueueExtraction(items, extractionImport) {
+    if (extractionImport === undefined || extractionImport === null) {
+        const itemNames = items.filter(reviewItemCarriesExtractionBinding).map((item) => item.metadata.name);
+        return itemNames.length === 0
+            ? { state: "not-extraction" }
+            : { state: "unverified", itemNames, message: unverifiedExtractionQueueSentence(itemNames.length) };
+    }
+    const record = isImportResult(extractionImport) ? extractionImport.record : extractionImport;
+    let issues;
+    try {
+        issues = validateReviewQueueAgainstExtractionImport(items, { record, reviewItems: [] });
+    }
+    catch (error) {
+        issues = [{
+                code: "import-invalid",
+                message: `The stored extraction import is invalid: ${error instanceof Error ? error.message : String(error)}`,
+            }];
+    }
+    return issues.length === 0
+        ? { state: "attested" }
+        : {
+            state: "diverges",
+            issues,
+            message: `This review queue does not match the extraction import stored with it, so it cannot be reviewed: ${issues.map((issue) => issue.message).join(" ")}`,
+        };
+}
+/** The notice every surface shows for an `unverified` queue. */
+export function unverifiedExtractionQueueSentence(itemCount) {
+    return `Unverified queue: ${itemCount === 1 ? "1 item came" : `${itemCount} items came`} from an extraction import, but no import record was stored with this queue, so its items were not checked against it. A rival value removed from the stored queue would not be shown.`;
+}
+function isImportResult(value) {
+    return typeof value === "object" && value !== null && "record" in value && !("kind" in value);
+}
 export function assertReviewQueueAgainstExtractionImport(items, importResult) {
     const issues = validateReviewQueueAgainstExtractionImport(items, importResult);
     if (issues.length > 0) {

package/dist/src/review-workbench/review-presentation.d.ts

@@ -57,6 +57,14 @@ export interface ReviewItemPresentation {
      * disproven: every decision surface shows them. Empty for other items.
      */
     readonly excludedProposals: readonly ExcludedProposalPresentation[];
+    /**
+     * Stored `excludedProposals` entries that {@link excludedProposals} cannot
+     * show: malformed entries, or every entry of an item whose envelope binding
+     * is not intact. Hiding a rival is the unsafe direction, so every surface
+     * that shows excluded proposals shows this notice too. Absent when every
+     * stored entry is shown.
+     */
+    readonly excludedProposalsUnreadable?: ExcludedProposalsUnreadable;
     /**
      * For an envelope-imported item, whether its import checked excerpts
      * against the prepared artifact. Absent for other items, and for an item
@@ -71,6 +79,16 @@ export interface ExcludedProposalPresentation {
     readonly locator: string;
     readonly excerpt: string;
 }
+export interface ExcludedProposalsUnreadable {
+    /**
+     * `malformed-entries`: some stored entries are not well-formed.
+     * `binding-broken`: the item's extraction binding is not intact, so none of
+     * its stored entries can be vouched for.
+     */
+    readonly reason: "malformed-entries" | "binding-broken";
+    /** How many stored entries are not shown; absent when the stored field is not a list. */
+    readonly count?: number;
+}
 export interface ReviewResultPresentation {
     readonly result: ReviewWorkbenchResult;
     readonly item?: ReviewItem;
@@ -131,6 +149,11 @@ export declare function buildInterpretationReadingPresentation(source: Interpret
  * text (the MCP item, the recorded decision prompt). Undefined when none.
  */
 export declare function excludedProposalsSentence(excluded: readonly ExcludedProposalPresentation[]): string | undefined;
+/**
+ * One sentence saying that stored excluded proposals cannot be shown, for
+ * every surface that shows excluded proposals. Undefined when none are hidden.
+ */
+export declare function excludedProposalsUnreadableSentence(unreadable: ExcludedProposalsUnreadable | undefined): string | undefined;
 export interface CandidateVerificationRecordPresentation {
     readonly recordId: string;
     readonly verifierId: string;

package/dist/src/review-workbench/review-presentation.js

@@ -69,20 +69,39 @@ function extractionEnvelopeBinding(item) {
     });
     return bound ? binding : undefined;
 }
-/** The well-formed `excludedProposals` entries of a bound envelope item; malformed entries are ignored, never rendered. */
+/**
+ * The well-formed `excludedProposals` entries of a bound envelope item, and
+ * what the item stores but cannot show: malformed entries, or every entry
+ * when the binding is not intact. Nothing stored is dropped silently.
+ */
 function excludedProposalsOf(item, binding, adapter) {
-    if (!binding || !Array.isArray(binding.excludedProposals))
-        return [];
-    return binding.excludedProposals.flatMap((entry) => {
+    const metadata = item.metadata?.producer?.[EXTRACTION_ENVELOPE_PRODUCER];
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        // Candidates that still carry the envelope binding came from an import,
+        // whose item metadata is gone or replaced: what it stored is unknown.
+        const candidatesBound = item.spec.candidates.some((candidate) => candidate.producer?.[EXTRACTION_ENVELOPE_PRODUCER] !== undefined);
+        return candidatesBound ? { excludedProposals: [], excludedProposalsUnreadable: { reason: "binding-broken" } } : { excludedProposals: [] };
+    }
+    const stored = metadata.excludedProposals;
+    if (stored === undefined)
+        return { excludedProposals: [] };
+    const count = Array.isArray(stored) ? stored.length : undefined;
+    if (!binding)
+        return count === 0 ? { excludedProposals: [] } : { excludedProposals: [], excludedProposalsUnreadable: { reason: "binding-broken", ...(count !== undefined ? { count } : {}) } };
+    if (!Array.isArray(stored))
+        return { excludedProposals: [], excludedProposalsUnreadable: { reason: "malformed-entries" } };
+    const proposed = item.spec.candidates.find((candidate) => candidate.role === "proposed");
+    const excludedProposals = stored.flatMap((entry) => {
         if (!entry || typeof entry !== "object" || Array.isArray(entry))
             return [];
         const e = entry;
         if (!Number.isSafeInteger(e.proposalIndex) || typeof e.locator !== "string" || typeof e.excerpt !== "string" || !("value" in e))
             return [];
-        const proposed = item.spec.candidates.find((candidate) => candidate.role === "proposed");
         const valueText = (proposed ? adapter.summarizeValue?.(e.value, { item, candidate: proposed, value: e.value }) : undefined) ?? formatValue(e.value);
         return [{ proposalIndex: e.proposalIndex, value: e.value, valueText, locator: e.locator, excerpt: e.excerpt }];
     });
+    const unreadable = stored.length - excludedProposals.length;
+    return { excludedProposals, ...(unreadable > 0 ? { excludedProposalsUnreadable: { reason: "malformed-entries", count: unreadable } } : {}) };
 }
 /**
  * One sentence naming every excluded proposal, for surfaces that speak in
@@ -94,6 +113,20 @@ export function excludedProposalsSentence(excluded) {
     const named = excluded.map((entry) => `${entry.valueText} (proposal ${entry.proposalIndex}, ${entry.locator})`).join(", ");
     return `${excluded.length === 1 ? "Another proposed value was" : `${excluded.length} other proposed values were`} excluded at import because the source text at the cited span is not the excerpt: ${named}. Unverifiable is not disproven.`;
 }
+/**
+ * One sentence saying that stored excluded proposals cannot be shown, for
+ * every surface that shows excluded proposals. Undefined when none are hidden.
+ */
+export function excludedProposalsUnreadableSentence(unreadable) {
+    if (!unreadable)
+        return undefined;
+    const { count } = unreadable;
+    const entries = count === undefined ? "Stored excluded proposals are" : `${count} stored excluded ${count === 1 ? "entry is" : "entries are"}`;
+    const why = unreadable.reason === "binding-broken"
+        ? "not shown because this item's extraction binding is broken"
+        : "unreadable and not shown";
+    return `${entries} ${why}. Another value may have been proposed for this field.`;
+}
 const VERIFICATION_RESULT_TEXT = {
     supported: "supported",
     contradicted: "contradicted",
@@ -167,7 +200,7 @@ export function buildReviewItemPresentation(item, adapter = {}) {
 function extractionPresentation(item, adapter) {
     const binding = extractionEnvelopeBinding(item);
     return {
-        excludedProposals: excludedProposalsOf(item, binding, adapter),
+        ...excludedProposalsOf(item, binding, adapter),
         ...(binding ? { excerptVerification: binding.excerptVerification === "verified" ? "verified" : "unverified" } : {}),
     };
 }
@@ -224,12 +257,20 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
         selectedValueText: selectedCandidate && item
             ? buildReviewCandidatePresentation(item, selectedCandidate, adapter, targetLabel).valueText
             : result.selectedDisplayValue,
-        applyMeaning: result.selectedCandidateRole === "proposed"
-            ? "Saved decision applies proposed value"
-            : "Saved decision keeps current value",
+        applyMeaning: result.decision === "select-proposed"
+            ? "Saved decision applies the chosen value; the other proposed values were seen and not chosen"
+            : result.selectedCandidateRole === "proposed"
+                ? "Saved decision applies proposed value"
+                : "Saved decision keeps current value",
         reviewItemLink: item && itemContext ? adapter.linkForReviewItem?.(item, itemContext) : undefined,
         traceRefs: item
-            ? traceRefsForResult(item, result, selectedCandidate, adapter)
+            ? [
+                ...traceRefsForResult(item, result, selectedCandidate, adapter),
+                // A choice between conflicting values names the values it passed over.
+                ...(result.decision === "select-proposed"
+                    ? result.unselectedCandidates.filter((candidate) => candidate.role === "proposed").flatMap((candidate) => withTraceLinks([{ label: "Not chosen candidate", value: candidate.id, kind: "candidate" }], { item, candidate }, adapter))
+                    : []),
+            ]
             : [{ label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" }],
     };
 }

package/dist/src/review-workbench/review-queue-session.d.ts

@@ -1,5 +1,16 @@
-import { type ReviewCandidate, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewSessionEventSpec } from "../../src/review-resource.js";
-export type ReviewWorkbenchDecision = "accept-proposed" | "keep-current" | "reject-proposed" | "could-not-confirm";
+import { type ReviewCandidate, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewSessionEventSpec, type ReviewSessionPresentation, type ReviewSessionSampling } from "../../src/review-resource.js";
+export type { ReviewSessionPresentation, ReviewSessionSampling } from "../../src/review-resource.js";
+/**
+ * The decisions a reviewer can record on a ReviewItem.
+ *
+ * `select-proposed` chooses one value of a conflict (two or more `proposed`
+ * candidates) by candidate id, which the state carries beside the decision
+ * (`selectedCandidateId` / `selectedCandidateIdsByItemName`). It is its own
+ * kind rather than `accept-proposed` with an id so that the record always says
+ * a rival was seen and not chosen, and `accept-proposed` keeps its meaning:
+ * accept the one proposed value, refused on a conflict.
+ */
+export type ReviewWorkbenchDecision = "accept-proposed" | "select-proposed" | "keep-current" | "reject-proposed" | "could-not-confirm";
 export type ReviewQueueRowStatus = "pending" | "in-review" | "resolved" | "rejected" | "could-not-confirm" | "escalated";
 export declare const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export declare const defaultReviewSessionName = "review-workbench-session";
@@ -16,6 +27,15 @@ export interface ReviewWorkbenchState {
      */
     readonly editedValue?: unknown;
     readonly attemptEvidenceIds?: readonly string[];
+    /**
+     * The candidate a `select-proposed` decision chose. Required for that
+     * decision and ignored for every other one.
+     */
+    readonly selectedCandidateId?: string;
+    /** The session's presentation; recorded on the decision. See {@link ReviewSessionPresentation}. */
+    readonly presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen; recorded on the decision. */
+    readonly sampling?: ReviewSessionSampling;
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -32,7 +52,53 @@ export interface ReviewQueueSessionState {
      */
     readonly editedValuesByItemName?: Readonly<Record<string, unknown>>;
     readonly attemptEvidenceIdsByItemName?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The candidate each `select-proposed` decision chose, keyed by ReviewItem
+     * name. Additive/optional: sessions stored before this field existed have no
+     * `select-proposed` decision and never read it.
+     */
+    readonly selectedCandidateIdsByItemName?: Readonly<Record<string, string>>;
+    /**
+     * Session-level presentation, set when the session is opened. Every
+     * decision event is stamped with it and replay refuses a mismatch; a
+     * `ReviewQueueBinding` also covers it. Without a binding, an edit to both the
+     * snapshot and every event stamp is not detectable. Absent: scores are shown
+     * and decisions record no presentation.
+     */
+    readonly presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen. Absent: decisions record no sampling. */
+    readonly sampling?: ReviewSessionSampling;
 }
+/** Whether the session hides confidence and verifier results from its reviewer. */
+export declare function isScoreBlind(session: {
+    readonly presentation?: ReviewSessionPresentation;
+}): boolean;
+/**
+ * Throws unless the session's presentation and sampling are well formed:
+ * `scoreBlind` a boolean, and a `random-audit` sampling with a rate in (0, 1]
+ * and a non-empty seed. Unknown keys are refused so a decision never records
+ * a condition nothing reads.
+ */
+export declare function assertReviewSessionConditions(session: {
+    readonly presentation?: unknown;
+    readonly sampling?: unknown;
+}): void;
+/**
+ * The session conditions a decision event carries, or `undefined` for a
+ * session that declares none. Stamped on every decision event so replay can
+ * refuse events recorded under other conditions than the snapshot's: sighted
+ * events replayed over a blind snapshot, or a snapshot whose presentation was
+ * changed after decisions were recorded.
+ */
+export declare function sessionConditionsStamp(session: {
+    readonly presentation?: ReviewSessionPresentation;
+    readonly sampling?: ReviewSessionSampling;
+}): {
+    presentation?: ReviewSessionPresentation;
+    sampling?: ReviewSessionSampling;
+} | undefined;
+export declare function assertAuditRate(rate: unknown): asserts rate is number;
+export declare function assertAuditSeed(seed: unknown): asserts seed is string;
 export interface ReviewSessionSummary {
     readonly accepted: number;
     readonly keptCurrent: number;
@@ -48,6 +114,12 @@ export declare const workbenchDecisionDefinitions: {
         candidateRole: "proposed";
         status: "verified";
     };
+    "select-proposed": {
+        label: string;
+        effect: string;
+        candidateRole: "proposed";
+        status: "verified";
+    };
     "keep-current": {
         label: string;
         effect: string;
@@ -109,14 +181,30 @@ export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boole
  * {@link decisionCandidateId} is `undefined` for it, so the decision, its
  * session events and the canonical projection name no candidate.
  */
-export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
+export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision, selectedCandidateId?: string): ReviewCandidate;
+/**
+ * Why a `select-proposed` decision naming `candidateId` cannot be recorded on
+ * this item, or `undefined` when it can.
+ *
+ * The choice must name, by a unique id, one of the item's `proposed`
+ * candidates, and the item must hold at least two of them: choosing "over a
+ * rival" on an item with no rival would record a conflict that never existed
+ * (use `accept-proposed` there). Proposals excluded at import are not
+ * candidates, so they can never be chosen.
+ */
+export declare function conflictSelectionIssue(item: ReviewItem, candidateId: string | undefined): string | undefined;
+/**
+ * The proposed candidates a `select-proposed` decision saw and did not choose,
+ * in item order. Empty for every other decision.
+ */
+export declare function unchosenProposedCandidates(item: ReviewItem, decision: ReviewWorkbenchDecision, selectedCandidateId: string | undefined): ReviewCandidate[];
 /** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
 export declare function decisionSelectsNoCandidate(item: ReviewItem, decision: ReviewWorkbenchDecision): boolean;
 /**
  * The candidate id a decision records: the selected candidate's, or
  * `undefined` when the decision selects no candidate.
  */
-export declare function decisionCandidateId(item: ReviewItem, decision: ReviewWorkbenchDecision): string | undefined;
+export declare function decisionCandidateId(item: ReviewItem, decision: ReviewWorkbenchDecision, selectedCandidateId?: string): string | undefined;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline
  * edit when one was made for an accept-proposed decision, otherwise the selected
@@ -125,7 +213,7 @@ export declare function decisionCandidateId(item: ReviewItem, decision: ReviewWo
  * this rule; this helper exists for callers deriving the value from raw session
  * state directly.
  */
-export declare function effectiveValueForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision, editedValue?: unknown): unknown;
+export declare function effectiveValueForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision, editedValue?: unknown, selectedCandidateId?: string): unknown;
 export declare function selectedCandidateRole(state: ReviewWorkbenchState): ReviewCandidate["role"] | undefined;
 export declare function buildReviewSessionResource(session: ReviewQueueSessionState, events?: readonly ReviewSessionEvent[], sessionName?: string): ReviewSession;
 export declare function buildReviewSessionEvents(session: ReviewQueueSessionState, sessionName?: string): ReviewSessionEvent[];