@kontourai/survey 6.0.0 → 6.1.0

package/dist/example-data/public-directory-review-resource.d.ts

@@ -35,12 +35,12 @@ export declare const publicDirectoryReviewItemExample: {
                 excerpt: string;
             };
             extraction: {
+                model?: undefined;
                 extractionId: string;
                 target: string;
                 confidence: number;
                 extractor: string;
                 extractedAt: string;
-                model?: undefined;
             };
             claimTarget: {
                 claimId: string;
@@ -61,13 +61,13 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
             };
             producer: {
+                proposalId?: undefined;
+                oldValue?: undefined;
                 sourceAuthority: {
                     authorityClass: string;
                     declaredBy: string;
                     scope: string;
                 };
-                proposalId?: undefined;
-                oldValue?: undefined;
             };
         } | {
             id: string;

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/index.d.ts

@@ -35,8 +35,10 @@ export { repeatedObservation } from "./repeated-observation.js";
 export type { RepeatedObservationInput } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationBuilderArgs, SourceOfAuthorityObservationInput, } from "./source-of-authority-observation.js";
-export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
-export type { InterpretationReadingPresentation, InterpretationReadingSource, ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
+export { buildCandidateVerification, candidateVerificationKind, DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS, MAX_SUPPORT_VERIFIER_TIMEOUT_MS, foldCandidateVerifications, runSupportVerifier, supportVerificationInputDigest, validateCandidateVerification, valueDigest, } from "./candidate-verification.js";
+export type { BuildCandidateVerificationInput, CandidateVerification, CandidateVerificationInapplicableReason, CandidateVerificationStatus, CandidateVerificationSubject, FoldCandidateVerificationsResult, RunSupportVerifierOptions, SupportAbstainReason, SupportEvidence, SupportVerdict, SupportVerificationInput, SupportVerificationMethod, SupportVerificationResult, SupportVerifier, } from "./candidate-verification.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, candidateVerificationNotes, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export type { CandidateVerificationNote, CandidateVerificationRecordPresentation, InterpretationReadingPresentation, InterpretationReadingSource, ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, PolicyStandardMetadata, PolicyStandardSourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";

package/dist/src/index.js

@@ -17,7 +17,8 @@ export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalRevi
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
-export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
+export { buildCandidateVerification, candidateVerificationKind, DEFAULT_SUPPORT_VERIFIER_TIMEOUT_MS, MAX_SUPPORT_VERIFIER_TIMEOUT_MS, foldCandidateVerifications, runSupportVerifier, supportVerificationInputDigest, validateCandidateVerification, valueDigest, } from "./candidate-verification.js";
+export { buildInterpretationReadingPresentation, buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, candidateVerificationNotes, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";

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

@@ -5,7 +5,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { buildReviewSessionEvents, currentReviewItem, decisionSelectsNoCandidate, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
-import { buildReviewItemPresentation, excludedProposalsSentence } from "../review-workbench/review-presentation.js";
+import { buildReviewItemPresentation, candidateVerificationNotes, excludedProposalsSentence } from "../review-workbench/review-presentation.js";
 import { appendReviewSessionEvents, readReviewSessionFile, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 const SESSION_NAME = "mcp-review-session";
 const UI_RESOURCE_URI_META_KEY = "ui/resourceUri";
@@ -80,12 +80,17 @@ function itemDetailText(item, snapshot, events) {
             ...(candidate.locator?.excerpt ? [`  excerpt: ${candidate.locator.excerpt}`] : []),
         ])),
         ...extractionImportLines(item),
+        ...candidateVerificationNotes(item, editedValueFor(item, current)).flatMap((entry) => [``, `Verification: ${entry.sentence}`]),
     ];
     if (item.spec.rationale) {
         lines.push(``, `Rationale: ${item.spec.rationale}`);
     }
     return lines.join("\n");
 }
+/** The reviewer's edit when the item's decision accepts one; verifier records are read against it. */
+function editedValueFor(item, state) {
+    return state.decisionsByItemName[item.metadata.name] === "accept-proposed" ? state.editedValuesByItemName?.[item.metadata.name] : undefined;
+}
 /** What an envelope import says about the item's evidence, including rival values it excluded. */
 function extractionImportLines(item) {
     const presentation = buildReviewItemPresentation(item);
@@ -143,6 +148,7 @@ function buildReviewCardHtml(item, snapshot, events) {
         : proposedCard(proposedCandidates[0], "Proposed");
     const itemNameJson = escapeJsonInHtml(item.metadata.name);
     const excludedNote = excludedProposalsSentence(buildReviewItemPresentation(item).excludedProposals);
+    const verificationNotes = candidateVerificationNotes(item, editedValueFor(item, current));
     const decisionBadge = decision
         ? `<span class="badge badge-${decision === "accept-proposed" ? "accept" : decision === "reject-proposed" ? "reject" : "hold"}">${escapeHtml(workbenchDecisionDefinitions[decision].label)}</span>`
         : `<span class="badge badge-pending">${escapeHtml(status)}</span>`;
@@ -245,6 +251,7 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
   ${proposedCards}
 </div>
 ${excludedNote ? `<p class="feedback" id="excluded-note">${escapeHtml(excludedNote)}</p>` : ""}
+${verificationNotes.map((entry) => `<p class="feedback verification-note" data-candidate-id="${escapeHtml(entry.candidateId)}">${escapeHtml(entry.sentence)}</p>`).join("\n")}
 ${conflict ? `<p class="feedback" id="conflict-note">${proposedCandidates.length} different values were proposed. This card cannot choose one of them yet: reject them all, or use Could not confirm with a reason.</p>` : ""}
 
 <div class="divider"></div>
@@ -359,14 +366,21 @@ async function toolItem(itemName, options) {
                 ...(presentation.excludedProposals.length ? { excludedProposals: presentation.excludedProposals.map(({ proposalIndex, value, locator, excerpt }) => ({ proposalIndex, value, locator, excerpt })) } : {}),
             };
         })(),
-        candidates: item.spec.candidates.map((c) => ({
-            id: c.id,
-            role: c.role,
-            value: c.value,
-            confidence: c.extraction?.confidence ?? c.confidence,
-            sourceRef: c.source?.sourceRef,
-            excerpt: c.locator?.excerpt,
-        })),
+        candidates: (() => {
+            const notes = candidateVerificationNotes(item, editedValueFor(item, current));
+            return item.spec.candidates.map((c, index) => {
+                const note = notes.find((entry) => entry.candidateIndex === index);
+                return {
+                    id: c.id,
+                    role: c.role,
+                    value: c.value,
+                    confidence: c.extraction?.confidence ?? c.confidence,
+                    sourceRef: c.source?.sourceRef,
+                    excerpt: c.locator?.excerpt,
+                    ...(note ? { verification: { subject: note.subjectLabel, status: note.status, records: note.records, inapplicableCount: note.inapplicableCount, rejectedCount: note.rejectedCount } } : {}),
+                };
+            });
+        })(),
     };
     const content = [
         { type: "text", text: `${text}\n\n${JSON.stringify(itemData, null, 2)}` },

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

@@ -1,3 +1,4 @@
+import type { CandidateVerification } from "./candidate-verification.js";
 import type { CandidateSetStatus, ClaimTarget, Extraction, RawSource, ReviewAuthorizing, ReviewOutcome } from "./types.js";
 export declare const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";
 export type ReviewResourceApiVersion = typeof reviewResourceApiVersion;
@@ -104,6 +105,14 @@ export interface ReviewCandidate {
     claimTarget: ClaimTargetHint;
     projection?: SurveyRecordProjectionHint;
     producer?: Record<string, unknown>;
+    /**
+     * Records of what independent support verifiers said about this candidate's
+     * value (see `CandidateVerification`). A record of a verifier's output, not a
+     * trust decision: nothing routes, accepts, or calibrates on it. Every decision
+     * surface validates each record on read, ignores any that fail, and shows only
+     * those bound to the value under review.
+     */
+    verifications?: CandidateVerification[];
 }
 /**
  * Well-known neutral value-type vocabulary for {@link ReviewValueDescriptor}.

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";
@@ -130,6 +131,42 @@ 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;
+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 = {
@@ -93,6 +94,61 @@ 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.`;
 }
+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);

package/dist/src/review-workbench/review-workbench-css.generated.js

@@ -835,7 +835,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   font-size: 12px;
 }
 
-.survey-workbench-embed .excerpt-verification{
+.survey-workbench-embed .excerpt-verification,
+.survey-workbench-embed .support-verification{
   margin: 0;
   font-size: 12px;
   color: var(--k-muted);

package/dist/src/review-workbench/review-workbench.css

@@ -832,7 +832,8 @@
   font-size: 12px;
 }
 
-.survey-workbench-embed .excerpt-verification{
+.survey-workbench-embed .excerpt-verification,
+.survey-workbench-embed .support-verification{
   margin: 0;
   font-size: 12px;
   color: var(--k-muted);

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

@@ -6,7 +6,7 @@ import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-pr
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
 import { findSoleCandidateById, reviewResourceApiVersion, } from "../review-resource.js";
 import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review-authorizing.js";
-import { excludedProposalsSentence, humanizeIdentifier } from "./review-presentation.js";
+import { candidateVerificationNotes, excludedProposalsSentence, humanizeIdentifier } from "./review-presentation.js";
 import { editedValueFromEditorText, isIsoCalendarDate, parsePlainDecimal } from "./edited-value.js";
 import { createAuditFactTrace, } from "./audit-rows.js";
 export { reviewAuditRowKeys } from "./audit-rows.js";
@@ -132,8 +132,9 @@ function decisionCardRenderedPrompt(state, targetLabel) {
     // The card shows proposals excluded at import; the recorded prompt must say
     // the reviewer was told about them.
     const excluded = excludedProposalsSentence(buildReviewItemPresentation(state.item).excludedProposals);
-    const base = decisionCardBasePrompt(state, targetLabel);
-    return excluded ? `${base} ${excluded}` : base;
+    // Likewise the verifier records the card showed, read against the same value.
+    const verification = candidateVerificationNotes(state.item, state.decision === "accept-proposed" ? state.editedValue : undefined).map((note) => note.sentence);
+    return [decisionCardBasePrompt(state, targetLabel), ...(excluded ? [excluded] : []), ...verification].join(" ");
 }
 function decisionCardBasePrompt(state, targetLabel) {
     const currentCandidate = state.item.spec.candidates.find((c) => c.role === "current");
@@ -701,6 +702,7 @@ function renderFieldCard(item, session, presentationAdapter) {
             : "<p class=\"field-value\">No proposed value is available for this field.</p>"}
         ${proposed ? renderProvenanceRow(item, proposed, presentationAdapter) : ""}
         ${renderExtractionImportNotes(presentation)}
+        ${renderVerificationNotes(candidateVerificationNotes(item, decision === "accept-proposed" ? editedValue : undefined))}
         <div class="decide">
           ${keepDecision === undefined ? "" : `<button class="btn keep" type="button" data-testid="keep-current" data-item-name="${escapeHtml(item.metadata.name)}">${keepLabel}</button>`}
           ${proposed ? `<button class="btn use" type="button" data-testid="use-proposed" data-item-name="${escapeHtml(item.metadata.name)}">Use proposed</button>
@@ -961,6 +963,20 @@ function renderExtractionImportNotes(presentation) {
     </div>
   `;
 }
+/**
+ * What verifier records say about the value on this card. A record is what a
+ * verifier said, not a review decision; records bound to another value and
+ * records that failed validation are counted, never shown as verdicts.
+ */
+function renderVerificationNotes(notes) {
+    if (notes.length === 0)
+        return "";
+    return `
+    <div class="prov import-notes">${notes.map((note) => `
+      <p class="support-verification" data-testid="support-verification" data-candidate-id="${escapeHtml(note.candidateId)}" data-status="${note.status}">${escapeHtml(note.sentence)}</p>`).join("")}
+    </div>
+  `;
+}
 function renderConfidenceMeter(confidence) {
     const clamped = Math.max(0, Math.min(1, confidence));
     const pct = Math.round(clamped * 100);

package/dist/src/review-workbench/review-workbench.standalone.css

@@ -627,7 +627,8 @@ h1, h2, h3, p {
   font-size: 12px;
 }
 
-.excerpt-verification {
+.excerpt-verification,
+.support-verification {
   margin: 0;
   font-size: 12px;
   color: var(--k-muted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",