@kontourai/survey 6.0.0 → 7.0.0

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

@@ -1,3 +1,4 @@
+import { type CandidateVerificationStatus, type SupportAbstainReason, type SupportVerificationMethod, type SupportVerificationResult } from "../candidate-verification.js";
 import { type ReviewCandidate, type ReviewItem } from "../review-resource.js";
 import type { InterpretationAnswerImpact, InterpretationReadingKind } from "../types.js";
 import { type ReviewWorkbenchResult } from "./review-workbench.js";
@@ -56,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
@@ -70,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;
@@ -130,6 +149,47 @@ 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;
+    readonly verifierVersion: string;
+    readonly method: SupportVerificationMethod;
+    readonly result: SupportVerificationResult;
+    readonly abstainReason?: SupportAbstainReason;
+    readonly createdAt: string;
+}
+/**
+ * What the verifier records on one candidate say about the value under
+ * review. Only candidates that carry `verifications` get a note, so a
+ * candidate no verifier looked at shows nothing rather than a verdict.
+ */
+export interface CandidateVerificationNote {
+    /** Position in `item.spec.candidates`; ids are not assumed unique. */
+    readonly candidateIndex: number;
+    readonly candidateId: string;
+    readonly subjectLabel: string;
+    /** As {@link foldCandidateVerifications}: `not-evaluated`, `abstained` (only abstentions apply) or `evaluated`. */
+    readonly status: CandidateVerificationStatus;
+    readonly records: readonly CandidateVerificationRecordPresentation[];
+    /** Valid records bound to another value, candidate or input. */
+    readonly inapplicableCount: number;
+    /** Records that failed validation (edited, inconsistent or malformed); never shown as verdicts. */
+    readonly rejectedCount: number;
+    readonly sentence: string;
+}
+/**
+ * Verifier notes for every candidate that carries records, read against the
+ * value each surface is deciding on: the candidate's own value, or the
+ * reviewer's edit when an accept carries one (records on the proposed value do
+ * not apply to an edited value). Records are validated here, so an inconsistent
+ * record is counted and ignored on every surface alike.
+ */
+export declare function candidateVerificationNotes(item: ReviewItem, editedValue?: unknown): CandidateVerificationNote[];
 export declare function buildReviewItemPresentation(item: ReviewItem, adapter?: ReviewPresentationAdapter): ReviewItemPresentation;
 export declare function buildReviewCandidatePresentation(item: ReviewItem, candidate: ReviewCandidate, adapter?: ReviewPresentationAdapter, targetLabel?: string): ReviewCandidatePresentation;
 export declare function buildReviewResultPresentation(result: ReviewWorkbenchResult, item: ReviewItem | undefined, adapter?: ReviewPresentationAdapter): ReviewResultPresentation;

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

@@ -1,3 +1,4 @@
+import { foldCandidateVerifications } from "../candidate-verification.js";
 import { findSoleCandidateById } from "../review-resource.js";
 import { formatValue } from "./review-surface-preview.js";
 const INTERPRETATION_KIND_LABELS = {
@@ -68,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
@@ -93,6 +113,75 @@ 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",
+    "not-addressed": "not addressed by the evidence",
+};
+/**
+ * Verifier notes for every candidate that carries records, read against the
+ * value each surface is deciding on: the candidate's own value, or the
+ * reviewer's edit when an accept carries one (records on the proposed value do
+ * not apply to an edited value). Records are validated here, so an inconsistent
+ * record is counted and ignored on every surface alike.
+ */
+export function candidateVerificationNotes(item, editedValue) {
+    const proposed = item.spec.candidates.filter((candidate) => candidate.role === "proposed");
+    return item.spec.candidates.flatMap((candidate, candidateIndex) => {
+        if (candidate.verifications === undefined)
+            return [];
+        const edited = editedValue !== undefined && proposed.length === 1 && candidate === proposed[0];
+        const subjectLabel = edited
+            ? "the edited value"
+            : candidate.role === "current"
+                ? "the current value"
+                : candidate.role === "proposed"
+                    ? proposed.length > 1 ? `proposed value ${proposed.indexOf(candidate) + 1} of ${proposed.length}` : "the proposed value"
+                    : `candidate ${candidate.id}`;
+        const records = Array.isArray(candidate.verifications) ? candidate.verifications : [candidate.verifications];
+        const fold = foldCandidateVerifications({ candidateId: candidate.id, value: edited ? editedValue : candidate.value }, records);
+        const presented = fold.applicable.map((record) => ({
+            recordId: record.id,
+            verifierId: record.verifier.id,
+            verifierVersion: record.verifier.version,
+            method: record.method,
+            result: record.result,
+            ...(record.abstainReason ? { abstainReason: record.abstainReason } : {}),
+            createdAt: record.createdAt,
+        }));
+        const said = presented.map((record) => `${record.verifierId} ${record.verifierVersion} (${record.method}) ${record.result === "abstain" ? `abstained: ${record.abstainReason}` : `said ${VERIFICATION_RESULT_TEXT[record.result]}`}`);
+        const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+        const sentence = [
+            said.length ? `Verifier records for ${subjectLabel} (what a verifier said: not proof, not a review decision): ${said.join("; ")}.` : `No verifier record applies to ${subjectLabel}.`,
+            ...(fold.inapplicable.length ? [`${plural(fold.inapplicable.length, "record was", "records were")} made for a different value or evidence and ${fold.inapplicable.length === 1 ? "does" : "do"} not apply.`] : []),
+            ...(fold.rejected.length ? [`${plural(fold.rejected.length, "record", "records")} failed validation and ${fold.rejected.length === 1 ? "was" : "were"} ignored.`] : []),
+        ].join(" ");
+        return [{
+                candidateIndex,
+                candidateId: candidate.id,
+                subjectLabel,
+                status: fold.status,
+                records: presented,
+                inapplicableCount: fold.inapplicable.length,
+                rejectedCount: fold.rejected.length,
+                sentence,
+            }];
+    });
+}
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
     const targetLabel = adapter.labelForTarget?.(item.spec.target, context) ?? humanizeIdentifier(item.spec.target);
@@ -111,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" } : {}),
     };
 }
@@ -168,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,15 @@
 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";
+/**
+ * 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 +26,11 @@ 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;
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -32,6 +47,12 @@ 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>>;
 }
 export interface ReviewSessionSummary {
     readonly accepted: number;
@@ -48,6 +69,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 +136,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 +168,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[];

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

@@ -11,6 +11,12 @@ export const workbenchDecisionDefinitions = {
         candidateRole: "proposed",
         status: "verified",
     },
+    "select-proposed": {
+        label: "Use this value",
+        effect: "The chosen value becomes the verified review outcome; the other proposed values were seen and not chosen.",
+        candidateRole: "proposed",
+        status: "verified",
+    },
     "keep-current": {
         label: "Keep current",
         effect: "Current value remains the verified review outcome.",
@@ -58,6 +64,7 @@ export function currentReviewWorkbenchState(session) {
         decision: session.decisionsByItemName[item.metadata.name],
         editedValue: session.editedValuesByItemName?.[item.metadata.name],
         attemptEvidenceIds: session.attemptEvidenceIdsByItemName?.[item.metadata.name],
+        selectedCandidateId: session.selectedCandidateIdsByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
     };
@@ -77,7 +84,7 @@ export function deriveQueueRowStatus(item, session) {
     if (decision === "could-not-confirm") {
         return "could-not-confirm";
     }
-    if (decision === "accept-proposed" || decision === "keep-current" || item.spec.candidateSetStatus === "resolved") {
+    if (decision === "accept-proposed" || decision === "select-proposed" || decision === "keep-current" || item.spec.candidateSetStatus === "resolved") {
         return "resolved";
     }
     if (item.spec.candidateSetStatus === "escalated") {
@@ -99,7 +106,7 @@ export function nextUnresolvedItemName(session) {
 export function reviewSessionSummary(session) {
     return session.items.reduce((summary, item) => {
         const decision = session.decisionsByItemName[item.metadata.name];
-        if (decision === "accept-proposed") {
+        if (decision === "accept-proposed" || decision === "select-proposed") {
             return { ...summary, accepted: summary.accepted + 1 };
         }
         if (decision === "keep-current") {
@@ -176,7 +183,14 @@ const VALUE_NEUTRAL_DECISIONS = new Set(["reject-proposed", "could-not-confirm"]
  * {@link decisionCandidateId} is `undefined` for it, so the decision, its
  * session events and the canonical projection name no candidate.
  */
-export function candidateForDecision(item, decision) {
+export function candidateForDecision(item, decision, selectedCandidateId) {
+    if (decision === "select-proposed") {
+        const issue = conflictSelectionIssue(item, selectedCandidateId);
+        if (issue) {
+            throw new Error(issue);
+        }
+        return item.spec.candidates.find((entry) => entry.id === selectedCandidateId);
+    }
     const definition = workbenchDecisionDefinitions[decision];
     const matches = item.spec.candidates.filter((entry) => entry.role === definition.candidateRole);
     const candidate = matches[0];
@@ -189,6 +203,45 @@ export function candidateForDecision(item, decision) {
     assertSoleCandidateId(item, candidate.id);
     return candidate;
 }
+/**
+ * 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 function conflictSelectionIssue(item, candidateId) {
+    const proposed = item.spec.candidates.filter((entry) => entry.role === "proposed");
+    if (proposed.length < 2) {
+        return `ReviewItem ${item.metadata.name} has ${proposed.length} proposed candidate${proposed.length === 1 ? "" : "s"}; select-proposed chooses between conflicting proposed values, so it needs at least two.`;
+    }
+    if (!candidateId) {
+        return `ReviewItem ${item.metadata.name}: select-proposed must name the chosen candidate id.`;
+    }
+    const matches = item.spec.candidates.filter((entry) => entry.id === candidateId);
+    if (matches.length === 0) {
+        return `ReviewItem ${item.metadata.name} has no candidate ${candidateId}; select-proposed can only choose one of its proposed candidates.`;
+    }
+    if (matches.length > 1) {
+        return `ReviewItem ${item.metadata.name} has ${matches.length} candidates with id ${candidateId}; candidate ids must be unique.`;
+    }
+    if (matches[0].role !== "proposed") {
+        return `ReviewItem ${item.metadata.name} candidate ${candidateId} has role ${matches[0].role ?? "none"}; select-proposed can only choose a proposed candidate.`;
+    }
+    return undefined;
+}
+/**
+ * The proposed candidates a `select-proposed` decision saw and did not choose,
+ * in item order. Empty for every other decision.
+ */
+export function unchosenProposedCandidates(item, decision, selectedCandidateId) {
+    return decision === "select-proposed"
+        ? item.spec.candidates.filter((entry) => entry.role === "proposed" && entry.id !== selectedCandidateId)
+        : [];
+}
 /** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
 export function decisionSelectsNoCandidate(item, decision) {
     const role = workbenchDecisionDefinitions[decision].candidateRole;
@@ -198,8 +251,8 @@ export function decisionSelectsNoCandidate(item, decision) {
  * The candidate id a decision records: the selected candidate's, or
  * `undefined` when the decision selects no candidate.
  */
-export function decisionCandidateId(item, decision) {
-    const candidate = candidateForDecision(item, decision);
+export function decisionCandidateId(item, decision, selectedCandidateId) {
+    const candidate = candidateForDecision(item, decision, selectedCandidateId);
     return decisionSelectsNoCandidate(item, decision) ? undefined : candidate.id;
 }
 /**
@@ -210,8 +263,8 @@ export function decisionCandidateId(item, decision) {
  * this rule; this helper exists for callers deriving the value from raw session
  * state directly.
  */
-export function effectiveValueForDecision(item, decision, editedValue) {
-    const candidate = candidateForDecision(item, decision);
+export function effectiveValueForDecision(item, decision, editedValue, selectedCandidateId) {
+    const candidate = candidateForDecision(item, decision, selectedCandidateId);
     return decision === "accept-proposed" && editedValue !== undefined ? editedValue : candidate.value;
 }
 export function selectedCandidateRole(state) {
@@ -287,7 +340,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
         if (decision === "could-not-confirm" && !note?.trim()) {
             throw new Error(`ReviewItem ${item.metadata.name} could not confirm requires a non-empty reason.`);
         }
-        const candidateId = decisionCandidateId(item, decision);
+        const candidateId = decisionCandidateId(item, decision, session.selectedCandidateIdsByItemName?.[item.metadata.name]);
         const definition = workbenchDecisionDefinitions[decision];
         const reviewDecisionName = `${item.metadata.name}-${decision}`;
         // Carry the reviewer's inline edit in the event itself (accept-proposed
@@ -383,11 +436,13 @@ export function replayReviewSessionEvents(startState, events) {
                 const { [itemName]: _removedDecision, ...remainingDecisions } = session.decisionsByItemName;
                 const { [itemName]: _removedEdit, ...remainingEdits } = session.editedValuesByItemName ?? {};
                 const { [itemName]: _removedAttempts, ...remainingAttempts } = session.attemptEvidenceIdsByItemName ?? {};
+                const { [itemName]: _removedSelection, ...remainingSelections } = session.selectedCandidateIdsByItemName ?? {};
                 return {
                     ...session,
                     decisionsByItemName: remainingDecisions,
                     editedValuesByItemName: remainingEdits,
                     attemptEvidenceIdsByItemName: remainingAttempts,
+                    ...(session.selectedCandidateIdsByItemName ? { selectedCandidateIdsByItemName: remainingSelections } : {}),
                 };
             }
             const decision = workbenchDecisionFromEvent(event);
@@ -419,6 +474,15 @@ export function replayReviewSessionEvents(startState, events) {
             else {
                 delete attemptEvidenceIdsByItemName[itemName];
             }
+            // A choice between conflicting values is the event's candidateId: that
+            // id is the authority for select-proposed (validated replay checks it).
+            const selectedCandidateIdsByItemName = { ...session.selectedCandidateIdsByItemName };
+            if (decision === "select-proposed" && event.spec.candidateId) {
+                selectedCandidateIdsByItemName[itemName] = event.spec.candidateId;
+            }
+            else {
+                delete selectedCandidateIdsByItemName[itemName];
+            }
             return {
                 ...session,
                 decisionsByItemName: {
@@ -427,6 +491,7 @@ export function replayReviewSessionEvents(startState, events) {
                 },
                 editedValuesByItemName,
                 attemptEvidenceIdsByItemName,
+                ...(session.selectedCandidateIdsByItemName || decision === "select-proposed" ? { selectedCandidateIdsByItemName } : {}),
             };
         }
         return session;

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

@@ -1,6 +1,6 @@
 import type { ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
-export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch";
+export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "invalid-conflict-selection" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch";
 export interface ReviewSessionReplayIssue {
     readonly code: ReviewSessionReplayIssueCode;
     readonly eventName: string;
@@ -37,6 +37,16 @@ export type ReviewSessionReplayWarning = {
     readonly refusedCode: "edited-value-not-editable" | "edited-value-type-mismatch";
     readonly editedValue: unknown;
     readonly message: string;
+} | {
+    /**
+     * The session's items came from an extraction import, but the apply
+     * boundary was not given the import record to check them against (see
+     * `DeriveServerReviewSessionApplyResultOptions.extractionImport`). Emitted
+     * by the server apply boundary, never by replay itself.
+     */
+    readonly code: "unverified-extraction-queue";
+    readonly itemNames: readonly string[];
+    readonly message: string;
 };
 /**
  * Lists the legacy text edits replay converts to typed values, and refused