@kontourai/survey 6.0.0 → 7.0.0

package/dist/src/candidate-verification.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Support verification: a port for an independent check of whether a
+ * candidate's value is supported by its evidence, and the immutable record of
+ * what such a check said.
+ *
+ * A {@link CandidateVerification} is a record of a verifier's output, bound to
+ * the exact value and evidence it checked. It is not a trust decision: nothing
+ * in Survey reads it to route, auto-accept, or calibrate a candidate. Survey
+ * ships no verifier implementations; producers or separate adapter packages
+ * implement {@link SupportVerifier}.
+ *
+ * Runtime-neutral (no Node built-ins) so the review workbench bundle can
+ * validate records in the browser.
+ */
+export declare const candidateVerificationKind: "survey.candidate-verification";
+export type SupportVerificationMethod = "deterministic" | "model" | "human";
+export type SupportVerificationResult = "supported" | "contradicted" | "not-addressed" | "abstain";
+export type SupportAbstainReason = "malformed" | "empty" | "timeout" | "unsupported" | "error";
+export interface SupportEvidence {
+    id: string;
+    excerpt: string;
+    locator: string;
+    context?: string;
+}
+export interface SupportVerificationInput {
+    candidateId: string;
+    value: unknown;
+    /** Declared value type when the producer knows it (for example `ReviewValueType`). */
+    valueType?: string;
+    /** At least one item; ids are unique. */
+    evidence: SupportEvidence[];
+}
+/**
+ * What a verifier returns. `score` has no meaning unless a calibration record
+ * says otherwise: it is optional, never defaulted, and never feeds a
+ * confidence. An abstention carries its reason and no score.
+ */
+export type SupportVerdict = {
+    result: "supported" | "contradicted" | "not-addressed";
+    score?: number;
+} | {
+    result: "abstain";
+    abstainReason: SupportAbstainReason;
+};
+/** The port. Implementations live with producers or in adapter packages. */
+export interface SupportVerifier {
+    readonly id: string;
+    readonly version: string;
+    readonly method: SupportVerificationMethod;
+    verify(input: Readonly<SupportVerificationInput>, options?: {
+        signal?: AbortSignal;
+    }): Promise<SupportVerdict>;
+}
+export interface CandidateVerification {
+    /** `sha256:` digest of every other field; recomputed on validation. */
+    id: string;
+    kind: typeof candidateVerificationKind;
+    schemaVersion: 1;
+    candidateId: string;
+    /** Sorted, unique ids of the evidence the verifier was given. */
+    evidenceIds: string[];
+    /** {@link valueDigest} of the value checked. */
+    valueDigest: string;
+    /** {@link supportVerificationInputDigest} of the full input checked. */
+    inputDigest: string;
+    verifier: {
+        id: string;
+        version: string;
+    };
+    method: SupportVerificationMethod;
+    result: SupportVerificationResult;
+    /** Present exactly when `result` is `abstain`. */
+    abstainReason?: SupportAbstainReason;
+    /** Uncalibrated unless a calibration record says otherwise. Never defaulted. */
+    score?: number;
+    createdAt: string;
+}
+export interface BuildCandidateVerificationInput {
+    input: SupportVerificationInput;
+    verifier: {
+        id: string;
+        version: string;
+        method: SupportVerificationMethod;
+    };
+    verdict: SupportVerdict;
+    createdAt: string;
+}
+/**
+ * `"sha256:" + hex SHA-256` of the canonical JSON of a value: the same
+ * definition as Surface's `valueDigest`, so a record binds to a value the way a
+ * Surface claim does.
+ */
+export declare function valueDigest(value: unknown): string;
+/** Digest of everything a verifier was given: candidate id, value, value type and evidence (ordered by id). */
+export declare function supportVerificationInputDigest(input: SupportVerificationInput): string;
+/**
+ * Builds a frozen record from a verifier's verdict. Throws on a malformed
+ * verdict: use {@link runSupportVerifier} to turn a verifier's failure into an
+ * abstention instead.
+ */
+export declare function buildCandidateVerification(input: BuildCandidateVerificationInput): CandidateVerification;
+/** How long {@link runSupportVerifier} waits when no `timeoutMs` is given. */
+export declare const DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS = 30000;
+/**
+ * The largest `timeoutMs` {@link runSupportVerifier} accepts: the largest
+ * delay a timer honours (2^31 - 1 ms). A larger delay would be clamped to
+ * 1 ms, turning a long bound into an immediate timeout, so it is refused.
+ */
+export declare const MAX_SUPPORT_VERIFIER_TIMEOUT_MS = 2147483647;
+export interface RunSupportVerifierOptions {
+    /**
+     * Abstain with `timeout` when the verifier has not answered by then.
+     * Defaults to {@link DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS}; a verifier is
+     * never waited on without a bound. At most
+     * {@link MAX_SUPPORT_VERIFIER_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+    /** Clock for `createdAt`; defaults to the current time. */
+    now?: () => string;
+}
+/**
+ * Calls a verifier and records what it said. A verifier that throws abstains
+ * with `error`, one that returns nothing with `empty`, one that returns a
+ * malformed verdict with `malformed`, and one that exceeds `timeoutMs`
+ * (default {@link DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS}) with `timeout`. None of these ever records a pass or a fail.
+ *
+ * Throws only for caller errors: a malformed input, or a verifier without a
+ * usable identity (a record needs one).
+ */
+export declare function runSupportVerifier(verifier: SupportVerifier, input: SupportVerificationInput, options?: RunSupportVerifierOptions): Promise<CandidateVerification>;
+/**
+ * Validates a record read back from storage and returns a frozen copy. Throws
+ * on any unknown field, inconsistent verdict, or an id that is not the digest
+ * of the record's own fields (an edited or inconsistent record). The id is a
+ * content digest, not a signature: it does not prove who wrote the record, and
+ * a record rebuilt with a recomputed id validates.
+ */
+export declare function validateCandidateVerification(value: unknown): CandidateVerification;
+/** The candidate a fold reads records for: its id and its value as it is now. */
+export interface CandidateVerificationSubject {
+    candidateId: string;
+    value: unknown;
+    valueType?: string;
+    /** When supplied, records must also match the full input digest. */
+    evidence?: SupportEvidence[];
+}
+export type CandidateVerificationStatus = "not-evaluated" | "abstained" | "evaluated";
+export type CandidateVerificationInapplicableReason = "other-candidate" | "value-changed" | "input-changed";
+export interface FoldCandidateVerificationsResult {
+    /**
+     * `not-evaluated` when no record applies to the subject's current value,
+     * `abstained` when every applicable record is an abstention, `evaluated`
+     * when at least one applicable record carries a verdict (supported,
+     * contradicted or not-addressed). Not itself a verdict.
+     */
+    status: CandidateVerificationStatus;
+    /** Valid records bound to this candidate and value, ordered by id. Abstentions included. */
+    applicable: readonly CandidateVerification[];
+    /** Valid records bound to another candidate, value, or input. */
+    inapplicable: readonly {
+        record: CandidateVerification;
+        reason: CandidateVerificationInapplicableReason;
+    }[];
+    /** Records that failed validation, by input position. Never read further. */
+    rejected: readonly {
+        index: number;
+        reason: string;
+    }[];
+}
+/**
+ * Sorts records for one candidate into those that apply to its current value,
+ * those bound to something else, and those that failed validation. Never
+ * selects a winner among applicable records and never derives a trust state.
+ */
+export declare function foldCandidateVerifications(subject: CandidateVerificationSubject, records: readonly unknown[]): FoldCandidateVerificationsResult;

package/dist/src/candidate-verification.js

@@ -0,0 +1,334 @@
+import { sha256Hex } from "./sha256.js";
+/**
+ * Support verification: a port for an independent check of whether a
+ * candidate's value is supported by its evidence, and the immutable record of
+ * what such a check said.
+ *
+ * A {@link CandidateVerification} is a record of a verifier's output, bound to
+ * the exact value and evidence it checked. It is not a trust decision: nothing
+ * in Survey reads it to route, auto-accept, or calibrate a candidate. Survey
+ * ships no verifier implementations; producers or separate adapter packages
+ * implement {@link SupportVerifier}.
+ *
+ * Runtime-neutral (no Node built-ins) so the review workbench bundle can
+ * validate records in the browser.
+ */
+export const candidateVerificationKind = "survey.candidate-verification";
+const METHODS = ["deterministic", "model", "human"];
+const RESULTS = ["supported", "contradicted", "not-addressed", "abstain"];
+const ABSTAIN_REASONS = ["malformed", "empty", "timeout", "unsupported", "error"];
+/**
+ * Canonical JSON with object keys sorted by UTF-16 code unit, matching
+ * `canonicalJson` in `@kontourai/surface` (`src/canonical-digest.ts`) byte for
+ * byte. Survey's review-workbench `canonicalJson` sorts with `localeCompare`
+ * and would disagree on mixed-case keys, so it is not used here.
+ */
+function surfaceCanonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(surfaceCanonicalJson).join(",")}]`;
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${surfaceCanonicalJson(value[key])}`).join(",")}}`;
+}
+/**
+ * `"sha256:" + hex SHA-256` of the canonical JSON of a value: the same
+ * definition as Surface's `valueDigest`, so a record binds to a value the way a
+ * Surface claim does.
+ */
+export function valueDigest(value) {
+    return `sha256:${sha256Hex(surfaceCanonicalJson(value))}`;
+}
+function digest(domain, payload) {
+    return `sha256:${sha256Hex(surfaceCanonicalJson({ domain, payload }))}`;
+}
+/** Digest of everything a verifier was given: candidate id, value, value type and evidence (ordered by id). */
+export function supportVerificationInputDigest(input) {
+    const normalized = normalizeInput(input);
+    return digest("survey.support-verification-input/v1", {
+        candidateId: normalized.candidateId,
+        valueDigest: valueDigest(normalized.value),
+        ...(normalized.valueType !== undefined ? { valueType: normalized.valueType } : {}),
+        evidence: normalized.evidence,
+    });
+}
+/**
+ * Builds a frozen record from a verifier's verdict. Throws on a malformed
+ * verdict: use {@link runSupportVerifier} to turn a verifier's failure into an
+ * abstention instead.
+ */
+export function buildCandidateVerification(input) {
+    const normalized = normalizeInput(input.input);
+    const verifier = normalizeVerifier(input.verifier);
+    const verdict = normalizeVerdict(input.verdict);
+    const payload = {
+        kind: candidateVerificationKind,
+        schemaVersion: 1,
+        candidateId: normalized.candidateId,
+        evidenceIds: normalized.evidence.map(({ id }) => id),
+        valueDigest: valueDigest(normalized.value),
+        inputDigest: supportVerificationInputDigest(normalized),
+        verifier: { id: verifier.id, version: verifier.version },
+        method: verifier.method,
+        result: verdict.result,
+        ...(verdict.result === "abstain" ? { abstainReason: verdict.abstainReason } : {}),
+        ...(verdict.result !== "abstain" && verdict.score !== undefined ? { score: verdict.score } : {}),
+        createdAt: canonicalTimestamp(input.createdAt, "createdAt"),
+    };
+    return deepFreeze({ id: recordId(payload), ...payload });
+}
+/** How long {@link runSupportVerifier} waits when no `timeoutMs` is given. */
+export const DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS = 30_000;
+/**
+ * The largest `timeoutMs` {@link runSupportVerifier} accepts: the largest
+ * delay a timer honours (2^31 - 1 ms). A larger delay would be clamped to
+ * 1 ms, turning a long bound into an immediate timeout, so it is refused.
+ */
+export const MAX_SUPPORT_VERIFIER_TIMEOUT_MS = 2_147_483_647;
+/**
+ * Calls a verifier and records what it said. A verifier that throws abstains
+ * with `error`, one that returns nothing with `empty`, one that returns a
+ * malformed verdict with `malformed`, and one that exceeds `timeoutMs`
+ * (default {@link DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS}) with `timeout`. None of these ever records a pass or a fail.
+ *
+ * Throws only for caller errors: a malformed input, or a verifier without a
+ * usable identity (a record needs one).
+ */
+export async function runSupportVerifier(verifier, input, options = {}) {
+    const identity = normalizeVerifier(verifier);
+    const normalized = normalizeInput(input);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_SUPPORT_VERIFIER_TIMEOUT_MS) {
+        throw new Error(`timeoutMs must be a positive finite number no greater than ${MAX_SUPPORT_VERIFIER_TIMEOUT_MS}`);
+    }
+    const now = options.now ?? (() => new Date().toISOString());
+    const verdict = await callVerifier(verifier, normalized, timeoutMs);
+    return buildCandidateVerification({ input: normalized, verifier: identity, verdict, createdAt: now() });
+}
+async function callVerifier(verifier, input, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timedOut = Symbol("timeout");
+    // The verifier gets its own frozen copy: it cannot change what the record binds to.
+    const frozenInput = deepFreeze(structuredClone(input));
+    try {
+        const call = Promise.resolve().then(() => verifier.verify(frozenInput, { signal: controller.signal }));
+        const raced = await Promise.race([call, new Promise((resolve) => { timer = setTimeout(() => resolve(timedOut), timeoutMs); })]);
+        if (raced === timedOut) {
+            controller.abort();
+            call.catch(() => undefined);
+            return { result: "abstain", abstainReason: "timeout" };
+        }
+        if (raced === undefined || raced === null)
+            return { result: "abstain", abstainReason: "empty" };
+        try {
+            return normalizeVerdict(raced);
+        }
+        catch {
+            return { result: "abstain", abstainReason: "malformed" };
+        }
+    }
+    catch {
+        return { result: "abstain", abstainReason: "error" };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+const RECORD_KEYS = new Set(["id", "kind", "schemaVersion", "candidateId", "evidenceIds", "valueDigest", "inputDigest", "verifier", "method", "result", "abstainReason", "score", "createdAt"]);
+/**
+ * Validates a record read back from storage and returns a frozen copy. Throws
+ * on any unknown field, inconsistent verdict, or an id that is not the digest
+ * of the record's own fields (an edited or inconsistent record). The id is a
+ * content digest, not a signature: it does not prove who wrote the record, and
+ * a record rebuilt with a recomputed id validates.
+ */
+export function validateCandidateVerification(value) {
+    const record = requiredObject(value, "CandidateVerification");
+    for (const key of Object.keys(record)) {
+        if (!RECORD_KEYS.has(key))
+            throw new Error(`CandidateVerification has unknown field ${key}`);
+    }
+    if (record.kind !== candidateVerificationKind)
+        throw new Error(`CandidateVerification kind must be ${candidateVerificationKind}`);
+    if (record.schemaVersion !== 1)
+        throw new Error("CandidateVerification schemaVersion must be 1");
+    const evidenceIds = record.evidenceIds;
+    if (!Array.isArray(evidenceIds) || evidenceIds.length === 0)
+        throw new Error("CandidateVerification evidenceIds must be a non-empty array");
+    evidenceIds.forEach((id, index) => {
+        nonEmpty(id, `evidenceIds[${index}]`);
+        if (index > 0 && !(evidenceIds[index - 1] < id))
+            throw new Error("CandidateVerification evidenceIds must be sorted and unique");
+    });
+    const verifier = requiredObject(record.verifier, "verifier");
+    if (Object.keys(verifier).some((key) => key !== "id" && key !== "version"))
+        throw new Error("CandidateVerification verifier has an unknown field");
+    const verdict = normalizeVerdict({
+        result: record.result,
+        ...("abstainReason" in record ? { abstainReason: record.abstainReason } : {}),
+        ...("score" in record ? { score: record.score } : {}),
+    });
+    const payload = {
+        kind: candidateVerificationKind,
+        schemaVersion: 1,
+        candidateId: nonEmpty(record.candidateId, "candidateId"),
+        evidenceIds: evidenceIds,
+        valueDigest: sha256Digest(record.valueDigest, "valueDigest"),
+        inputDigest: sha256Digest(record.inputDigest, "inputDigest"),
+        verifier: { id: nonEmpty(verifier.id, "verifier.id"), version: nonEmpty(verifier.version, "verifier.version") },
+        method: oneOf(record.method, METHODS, "method"),
+        result: verdict.result,
+        ...(verdict.result === "abstain" ? { abstainReason: verdict.abstainReason } : {}),
+        ...(verdict.result !== "abstain" && verdict.score !== undefined ? { score: verdict.score } : {}),
+        createdAt: canonicalTimestamp(record.createdAt, "createdAt"),
+    };
+    const id = recordId(payload);
+    if (record.id !== id)
+        throw new Error("CandidateVerification id is not the digest of its fields");
+    return deepFreeze({ id, ...structuredClone(payload) });
+}
+/**
+ * Sorts records for one candidate into those that apply to its current value,
+ * those bound to something else, and those that failed validation. Never
+ * selects a winner among applicable records and never derives a trust state.
+ */
+export function foldCandidateVerifications(subject, records) {
+    const candidateId = nonEmpty(subject.candidateId, "candidateId");
+    const currentValueDigest = valueDigest(subject.value);
+    const currentInputDigest = subject.evidence === undefined
+        ? undefined
+        : supportVerificationInputDigest({ candidateId, value: subject.value, ...(subject.valueType !== undefined ? { valueType: subject.valueType } : {}), evidence: subject.evidence });
+    const applicable = new Map();
+    const inapplicable = new Map();
+    const rejected = [];
+    records.forEach((raw, index) => {
+        let record;
+        try {
+            record = validateCandidateVerification(raw);
+        }
+        catch (error) {
+            rejected.push(Object.freeze({ index, reason: error instanceof Error ? error.message : String(error) }));
+            return;
+        }
+        const reason = record.candidateId !== candidateId
+            ? "other-candidate"
+            : record.valueDigest !== currentValueDigest
+                ? "value-changed"
+                : currentInputDigest !== undefined && record.inputDigest !== currentInputDigest
+                    ? "input-changed"
+                    : undefined;
+        if (reason)
+            inapplicable.set(record.id, Object.freeze({ record, reason }));
+        else
+            applicable.set(record.id, record);
+    });
+    const byId = (entries) => [...entries.keys()].sort().map((id) => entries.get(id));
+    const applicableRecords = byId(applicable);
+    return Object.freeze({
+        status: applicableRecords.length === 0
+            ? "not-evaluated"
+            : applicableRecords.every((record) => record.result === "abstain") ? "abstained" : "evaluated",
+        applicable: Object.freeze(applicableRecords),
+        inapplicable: Object.freeze(byId(inapplicable)),
+        rejected: Object.freeze(rejected),
+    });
+}
+function recordId(payload) {
+    return digest("survey.candidate-verification/v1", payload);
+}
+function normalizeInput(input) {
+    const value = requiredObject(input, "SupportVerificationInput");
+    if (!("value" in value))
+        throw new Error("SupportVerificationInput value is required");
+    if (!Array.isArray(value.evidence) || value.evidence.length === 0)
+        throw new Error("SupportVerificationInput evidence must be a non-empty array");
+    const evidence = value.evidence.map((entry, index) => {
+        const item = requiredObject(entry, `evidence[${index}]`);
+        return {
+            id: nonEmpty(item.id, `evidence[${index}].id`),
+            excerpt: text(item.excerpt, `evidence[${index}].excerpt`),
+            locator: nonEmpty(item.locator, `evidence[${index}].locator`),
+            ...(item.context !== undefined ? { context: text(item.context, `evidence[${index}].context`) } : {}),
+        };
+    }).sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+    evidence.forEach((entry, index) => {
+        if (index > 0 && evidence[index - 1].id === entry.id)
+            throw new Error(`SupportVerificationInput evidence id ${entry.id} is repeated`);
+    });
+    return {
+        candidateId: nonEmpty(value.candidateId, "candidateId"),
+        value: value.value,
+        ...(value.valueType !== undefined ? { valueType: nonEmpty(value.valueType, "valueType") } : {}),
+        evidence,
+    };
+}
+function normalizeVerifier(value) {
+    const verifier = requiredObject(value, "verifier");
+    return {
+        id: nonEmpty(verifier.id, "verifier.id"),
+        version: nonEmpty(verifier.version, "verifier.version"),
+        method: oneOf(verifier.method, METHODS, "verifier.method"),
+    };
+}
+function normalizeVerdict(value) {
+    const verdict = requiredObject(value, "verdict");
+    for (const key of Object.keys(verdict)) {
+        if (key !== "result" && key !== "abstainReason" && key !== "score")
+            throw new Error(`verdict has unknown field ${key}`);
+    }
+    const result = oneOf(verdict.result, RESULTS, "verdict.result");
+    if (result === "abstain") {
+        if ("score" in verdict)
+            throw new Error("an abstaining verdict carries no score");
+        return { result, abstainReason: oneOf(verdict.abstainReason, ABSTAIN_REASONS, "verdict.abstainReason") };
+    }
+    if ("abstainReason" in verdict)
+        throw new Error("abstainReason is only allowed when result is abstain");
+    if (!("score" in verdict))
+        return { result };
+    const score = verdict.score;
+    if (typeof score !== "number" || !Number.isFinite(score) || score < 0 || score > 1)
+        throw new Error("verdict.score must be a number from 0 to 1");
+    return { result, score };
+}
+function oneOf(value, allowed, label) {
+    if (typeof value !== "string" || !allowed.includes(value))
+        throw new Error(`${label} must be one of ${allowed.join(", ")}`);
+    return value;
+}
+function requiredObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} must be a non-empty string`);
+    return value;
+}
+function text(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+function sha256Digest(value, label) {
+    if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value))
+        throw new Error(`${label} must be a sha256:<64 hex> digest`);
+    return value;
+}
+function canonicalTimestamp(value, label) {
+    const timestamp = nonEmpty(value, label);
+    const parsed = new Date(timestamp);
+    if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== timestamp)
+        throw new Error(`${label} must be a canonical ISO timestamp`);
+    return timestamp;
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/src/canonical-reviewed-trust-input.js

@@ -39,10 +39,17 @@ export function buildCanonicalReviewedTrustInput(options) {
         const rejectsAll = selectsNone && result.decision === "reject-proposed";
         const rejectedRole = workbenchDecisionDefinitions[result.decision].candidateRole;
         const rejectAllReason = result.rationale?.trim() || "Every proposed value for this claim was rejected.";
+        // A choice of one conflicting value passes over the others: each keeps a
+        // record that it was seen and not chosen (and so its own rejected-candidate
+        // learning), never silently dropped.
+        const unchosenIds = new Set(result.decision === "select-proposed" ? result.reviewDecision.spec.unselectedCandidateIds ?? [] : []);
+        const notChosenReason = `Not chosen: the reviewer chose candidate ${recordIdFor(item, result.selectedCandidateId ?? "")} for this claim.`;
         const candidates = item.spec.candidates.map((candidate) => {
             const records = projectCandidate(item, rejectsAll && candidate.role === rejectedRole
                 ? { ...candidate, rejectionReason: candidate.rejectionReason ?? rejectAllReason }
-                : candidate);
+                : unchosenIds.has(candidate.id)
+                    ? { ...candidate, rejectionReason: candidate.rejectionReason ?? notChosenReason }
+                    : candidate);
             addConsistent(rawSources, records.rawSource, "raw source");
             addConsistent(extractions, records.extraction, "extraction");
             return records.candidate;
@@ -96,6 +103,9 @@ export function buildCanonicalReviewedTrustInput(options) {
             metadata: {
                 workbenchDecision: result.decision,
                 ...(result.editedValue !== undefined ? { editedValue: result.editedValue } : {}),
+                ...(decision.unselectedCandidateIds?.length
+                    ? { unselectedCandidateIds: decision.unselectedCandidateIds.map((id) => recordIdFor(item, id)) }
+                    : {}),
             },
         };
         addConsistent(reviewOutcomes, reviewOutcome, "review outcome");
@@ -192,6 +202,20 @@ function assertCanonicalResult(item, result) {
         || canonicalJson(decision.editedValue) !== canonicalJson(result.editedValue)) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical ReviewDecision.`);
     }
+    // Accepting one value of a conflict would project it as if it had been the
+    // only value; a choice between conflicting values is select-proposed.
+    if (result.decision === "accept-proposed" && item.spec.candidates.filter((candidate) => candidate.role === "proposed").length > 1) {
+        throw new Error(`Review result ${result.reviewItemName} accepts one proposed value of a conflict; a choice between conflicting values must be a select-proposed decision that records the values it passed over.`);
+    }
+    // A choice names exactly the proposed values it passed over; no other
+    // decision names any.
+    const expectedUnselected = result.decision === "select-proposed" && selected
+        ? item.spec.candidates.filter((candidate) => candidate.role === "proposed" && candidate.id !== selected.id).map((candidate) => candidate.id)
+        : [];
+    if (canonicalJson(decision.unselectedCandidateIds ?? []) !== canonicalJson(expectedUnselected)
+        || (result.decision === "select-proposed" && expectedUnselected.length === 0)) {
+        throw new Error(`Review result ${result.reviewItemName} does not record the proposed values its ${result.decision} decision passed over.`);
+    }
     if ((result.decision === "could-not-confirm") !== (decision.resolution === "could_not_confirm")) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical review resolution.`);
     }
@@ -210,6 +234,11 @@ function assertCanonicalResult(item, result) {
         }
     }
 }
+/** The projected Candidate record id of a ReviewItem candidate. */
+function recordIdFor(item, candidateId) {
+    const candidate = item.spec.candidates.find((entry) => entry.id === candidateId);
+    return candidate?.projection?.candidateId ?? candidateId;
+}
 function claimTargetIdentity(target) {
     const { claimId: _claimId, ...identity } = target;
     return identity;

package/dist/src/console/review-console-server.js

@@ -18,6 +18,7 @@ import { readFile as readFileAsync } from "node:fs/promises";
 import { resolve, join, dirname, extname, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { attestReviewQueueExtraction } from "../review-workbench/queue-binding.js";
 import { appendReviewSessionEvents, readReviewSessionFile, reviewSessionRevision, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -404,9 +405,15 @@ let activeItemName = null;
 async function fetchAndMount() {
   try {
     const res = await fetch("/api/session");
-    if (!res.ok) throw new Error("Session fetch failed: " + res.status);
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      showSaveStatus(body.error || ("The session could not be loaded (HTTP " + res.status + ")."));
+      const root = document.getElementById("review-workbench");
+      if (root) root.innerHTML = "";
+      return;
+    }
     const data = await res.json();
-    const { snapshot, events, revision } = data;
+    const { snapshot, events, revision, extractionImport } = data;
     const state = events && events.length > 0
       ? replayReviewSessionEvents(snapshot, events)
       : snapshot;
@@ -419,7 +426,7 @@ async function fetchAndMount() {
     const root = document.getElementById("review-workbench");
     if (!root) return;
 
-    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision) });
+    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision), ...(extractionImport ? { extractionImport } : {}) });
   } catch (err) {
     console.error("[console] Mount error:", err);
   }
@@ -602,12 +609,22 @@ export async function startReviewConsoleServer(options) {
             // ---- Session read ----
             if (pathname === "/api/session" && req.method === "GET") {
                 const content = await readSession(sessionPath);
+                // A queue that does not match the extraction import stored with it is
+                // not served for review; one without a stored import is served, and the
+                // workbench marks it unverified.
+                const attestation = attestReviewQueueExtraction(content.snapshot.items, content.extractionImport);
+                if (attestation.state === "diverges") {
+                    sendJson(res, 409, { error: attestation.message, queueAttestation: attestation.state });
+                    return;
+                }
                 sendJson(res, 200, {
                     session: content.session,
                     snapshot: content.snapshot,
                     events: content.events,
                     revision: reviewSessionRevision(content.events),
                     state: currentSessionState(content.snapshot, content.events),
+                    queueAttestation: attestation.state,
+                    ...(content.extractionImport !== undefined ? { extractionImport: content.extractionImport } : {}),
                 });
                 return;
             }
@@ -660,6 +677,7 @@ export async function startReviewConsoleServer(options) {
                             record,
                             events: nextEvents,
                             requiredResolvedItems: "none",
+                            extractionImport: content.extractionImport,
                         });
                         issueMessages = applyResult.ok
                             ? []
@@ -672,7 +690,7 @@ export async function startReviewConsoleServer(options) {
                         return { result: { status: 422, body: { error: `Validation failed: ${issueMessages.join("; ")}` } } };
                     }
                     return {
-                        next: { session: content.session, snapshot, events: nextEvents },
+                        next: { ...content, session: content.session, snapshot, events: nextEvents },
                         result: {
                             status: 200,
                             body: { ok: true, eventCount: nextEvents.length, revision: reviewSessionRevision(nextEvents) },