@kontourai/survey 1.10.0 → 1.12.0

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

@@ -40,6 +40,7 @@ export declare const publicDirectoryReviewItemExample: {
                 confidence: number;
                 extractor: string;
                 extractedAt: string;
+                model?: undefined;
             };
             claimTarget: {
                 claimId: string;
@@ -91,6 +92,7 @@ export declare const publicDirectoryReviewItemExample: {
                 target: string;
                 confidence: number;
                 extractor: string;
+                model: string;
                 extractedAt: string;
             };
             claimTarget: {

package/dist/example-data/public-directory-review-resource.js

@@ -92,6 +92,7 @@ export const publicDirectoryReviewItemExample = {
                     target: "availabilityStatus",
                     confidence: 0.82,
                     extractor: "example-crawl",
+                    model: "example-extraction-model-2026-05",
                     extractedAt: "2026-05-31T15:00:00.000Z",
                 },
                 claimTarget: {

package/dist/examples/calibrated-auto-accept.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Worked example: wiring confidence calibration into a downstream consumer.
+ *
+ * A consumer that owns human review outcomes can close the confidence loop in two
+ * places, both shipped in @kontourai/survey (1.10.0):
+ *
+ *   1. Ground the auto-accept threshold. `deriveCalibration` over a history of
+ *      review outcomes yields `suggestedThreshold` — the lowest confidence at
+ *      which the extractor's proposals were empirically affirmed often enough.
+ *      Feed that number into a producer profile's `autoAcceptMinConfidence`
+ *      (see `SchemaMappingOptions.autoAcceptMinConfidence` /
+ *      `InquiryMappingOptions.minConfidence`) instead of hand-picking it.
+ *
+ *   2. Produce calibrated conclusion confidence. Pass the same calibration
+ *      `metrics` into `buildSurveyTrustBundle({ calibration: { metrics } })` and
+ *      affirmed claims carry `conclusionConfidence.value` = the empirical
+ *      affirmation rate for their extractor/field.
+ *
+ * Calibration is advisory (ADR 0003 §4): the threshold is a suggestion the
+ * operator wires into policy, and the produced value never changes claim status.
+ *
+ * Run: `node dist/examples/calibrated-auto-accept.js`
+ */
+export interface CalibratedAutoAcceptResult {
+    readonly suggestedThreshold: number | undefined;
+    readonly groupAccuracy: number | undefined;
+    readonly producedValues: ReadonlyArray<number | undefined>;
+}
+export declare function runCalibratedAutoAccept(): CalibratedAutoAcceptResult;

package/dist/examples/calibrated-auto-accept.js

@@ -0,0 +1,135 @@
+/**
+ * Worked example: wiring confidence calibration into a downstream consumer.
+ *
+ * A consumer that owns human review outcomes can close the confidence loop in two
+ * places, both shipped in @kontourai/survey (1.10.0):
+ *
+ *   1. Ground the auto-accept threshold. `deriveCalibration` over a history of
+ *      review outcomes yields `suggestedThreshold` — the lowest confidence at
+ *      which the extractor's proposals were empirically affirmed often enough.
+ *      Feed that number into a producer profile's `autoAcceptMinConfidence`
+ *      (see `SchemaMappingOptions.autoAcceptMinConfidence` /
+ *      `InquiryMappingOptions.minConfidence`) instead of hand-picking it.
+ *
+ *   2. Produce calibrated conclusion confidence. Pass the same calibration
+ *      `metrics` into `buildSurveyTrustBundle({ calibration: { metrics } })` and
+ *      affirmed claims carry `conclusionConfidence.value` = the empirical
+ *      affirmation rate for their extractor/field.
+ *
+ * Calibration is advisory (ADR 0003 §4): the threshold is a suggestion the
+ * operator wires into policy, and the produced value never changes claim status.
+ *
+ * Run: `node dist/examples/calibrated-auto-accept.js`
+ */
+import { buildSurveyTrustBundle, deriveCalibration, SurveyInputBuilder, } from "../src/index.js";
+const EXTRACTOR = "example-extractor";
+const FIELD = "registrationStatus";
+const HISTORY_AT = "2026-06-01T00:00:00.000Z";
+const BATCH_AT = "2026-07-01T00:00:00.000Z";
+/**
+ * A synthetic history: for this extractor/field, high-confidence proposals were
+ * almost always affirmed by reviewers and low-confidence ones were mostly
+ * rejected — the pattern that makes an empirical threshold meaningful.
+ */
+function buildReviewHistory() {
+    const extractions = [];
+    const candidateSets = [];
+    const reviewOutcomes = [];
+    let n = 0;
+    const addSamples = (count, confidence, affirmed) => {
+        for (let i = 0; i < count; i += 1) {
+            const key = `h-${n}`;
+            n += 1;
+            extractions.push({
+                id: `${key}-ext`,
+                sourceId: `${key}-src`,
+                target: FIELD,
+                value: "ACTIVE",
+                confidence,
+                extractor: EXTRACTOR,
+                extractedAt: HISTORY_AT,
+            });
+            const candidate = { id: `${key}-cand`, extractionId: `${key}-ext`, value: "ACTIVE", confidence };
+            candidateSets.push({
+                id: `${key}-cs`,
+                target: FIELD,
+                status: "resolved",
+                selectedCandidateId: candidate.id,
+                candidates: [candidate],
+            });
+            reviewOutcomes.push({
+                id: `${key}-ro`,
+                candidateSetId: `${key}-cs`,
+                candidateId: candidate.id,
+                status: i < affirmed ? "verified" : "rejected",
+                actor: "example-reviewer",
+                reviewedAt: HISTORY_AT,
+            });
+        }
+    };
+    addSamples(10, 0.95, 10); // top decile: all affirmed
+    addSamples(10, 0.85, 10); // 0.8–0.9: all affirmed
+    addSamples(10, 0.75, 5); // 0.7–0.8: half affirmed → below target, ends the run
+    addSamples(10, 0.55, 1); // 0.5–0.6: mostly rejected
+    return { reviewOutcomes, candidateSets, extractions };
+}
+export function runCalibratedAutoAccept() {
+    // (1) Derive the empirical calibration curve over the review history.
+    const metrics = deriveCalibration(buildReviewHistory(), {
+        targetAccuracy: 0.9, // the accuracy the auto-accept threshold must clear
+        minBinSamples: 5, // a decile needs this many samples to ground the threshold
+    });
+    const suggestedThreshold = metrics.overall.suggestedThreshold;
+    const group = metrics.byExtractorField.find((g) => g.extractor === EXTRACTOR && g.field === FIELD);
+    // This is the number you feed into your producer profile's auto-accept policy:
+    //   surveySchemaMapping(context, extractor, { autoAcceptMinConfidence: suggestedThreshold })
+    // Proposals at/above it were empirically affirmed often enough to auto-accept.
+    // (2) Produce calibrated conclusion confidence on a new batch of affirmed claims.
+    const input = new SurveyInputBuilder({ source: "example-consumer:calibrated", generatedAt: BATCH_AT })
+        .addObservation(affirmedObservation("entity-1", 0.85))
+        .addObservation(affirmedObservation("entity-2", 0.92))
+        .build();
+    // Prefer metrics computed over history (not just this batch), so a claim's own
+    // outcome does not feed its own value.
+    const bundle = buildSurveyTrustBundle(input, { calibration: { metrics, minSamples: 20 } });
+    const producedValues = bundle.claims.map((c) => c.conclusionConfidence?.value);
+    return { suggestedThreshold, groupAccuracy: group?.empiricalAccuracy, producedValues };
+}
+function affirmedObservation(subjectId, confidence) {
+    return {
+        id: `example.${subjectId}.${FIELD}.current`,
+        rawSource: {
+            kind: "api-record",
+            sourceRef: `records://${subjectId}/registry`,
+            observedAt: BATCH_AT,
+            locatorScheme: "structured-field",
+        },
+        extraction: {
+            target: FIELD,
+            value: "ACTIVE",
+            confidence,
+            locator: "json:$.registrationStatus",
+            extractor: EXTRACTOR,
+            extractedAt: BATCH_AT,
+        },
+        reviewOutcome: { status: "verified", actor: "example-reviewer", reviewedAt: BATCH_AT },
+        claim: {
+            subjectType: "public-record.entity",
+            subjectId,
+            facet: "public-record.profile",
+            claimType: "public-data.field",
+            fieldOrBehavior: FIELD,
+            impactLevel: "medium",
+            collectedBy: EXTRACTOR,
+        },
+    };
+}
+// Run standalone (not when imported by a test).
+if (process.argv[1]?.endsWith("calibrated-auto-accept.js")) {
+    const result = runCalibratedAutoAccept();
+    console.log(JSON.stringify({
+        suggestedAutoAcceptThreshold: result.suggestedThreshold,
+        empiricalAffirmationRate: result.groupAccuracy,
+        producedConclusionConfidenceValues: result.producedValues,
+    }, null, 2));
+}

package/dist/examples/review-workbench/downstream-public-directory-adapter.js

@@ -110,7 +110,8 @@ function proposedReviewCandidate(proposal, field, diff, selectedRole) {
         sourceRef: diff.sourceUrl ?? proposal.sourceUrl,
         observedAt: proposal.createdAt,
         excerpt: diff.excerpt ?? `Proposed ${field} value from downstream extraction.`,
-        extractor: proposal.extractionModel,
+        extractor: "downstream-directory-extractor",
+        model: proposal.extractionModel,
         extractedAt: proposal.createdAt,
         confidence: diff.confidence,
         sourceRank: selectedRole === "proposed" ? 1 : 2,
@@ -193,6 +194,7 @@ function candidateExtraction(args, extractionId) {
         target: args.field,
         confidence: args.confidence,
         extractor: args.extractor,
+        ...(args.model ? { model: args.model } : {}),
         extractedAt: args.extractedAt,
     };
 }

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

@@ -35,7 +35,16 @@ export interface ExtractionReference {
     extractionId?: string;
     target: string;
     confidence?: number;
+    /** The extraction tool/pipeline that produced this candidate (e.g. a crawler or parser). */
     extractor?: string;
+    /**
+     * The model or model-version that generated this candidate, when the producer
+     * knows it (e.g. an LLM id or a dated extraction-model tag). Distinct from
+     * `extractor` (the tool): a reviewer wants to know *which model* proposed a
+     * value for trust/calibration. Producer-provided provenance; Survey only
+     * carries and displays it.
+     */
+    model?: string;
     extractedAt?: string;
 }
 export interface ClaimTargetHint {
@@ -130,6 +139,15 @@ export interface ReviewDecisionSpec {
      *  their own admissible block. */
     authorizing?: ReviewAuthorizing;
     projection?: SurveyRecordProjectionHint;
+    /**
+     * Reviewer-edited override for the proposed candidate's value, captured when the
+     * reviewer edits the inline proposed-value editor before choosing "Use proposed".
+     * Only meaningful when the decision selects the proposed candidate. Downstream
+     * consumers should read the effective value as `editedValue ?? <selected candidate value>`
+     * rather than assuming the candidate's original value was applied verbatim.
+     * Additive/optional: absent means the candidate's original value was used unchanged.
+     */
+    editedValue?: unknown;
 }
 export interface ReviewDecisionStatus {
     appliedToClaimIds?: string[];

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

@@ -9,6 +9,12 @@ export interface ReviewWorkbenchState {
     readonly decision?: ReviewWorkbenchDecision;
     readonly reviewedAt: string;
     readonly actorId: string;
+    /**
+     * Reviewer-edited override for the item's proposed value (inline edit in the
+     * field-diff card). Additive/optional: undefined means no edit was made and the
+     * proposed candidate's original value applies.
+     */
+    readonly editedValue?: unknown;
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -17,6 +23,13 @@ export interface ReviewQueueSessionState {
     readonly decisionsByItemName: Readonly<Record<string, ReviewWorkbenchDecision>>;
     readonly reviewedAt: string;
     readonly actorId: string;
+    /**
+     * Reviewer-edited overrides for proposed values, keyed by ReviewItem name.
+     * Additive/optional: a session built before this field existed behaves exactly
+     * as before (every lookup resolves to undefined, meaning "use the candidate's
+     * original value").
+     */
+    readonly editedValuesByItemName?: Readonly<Record<string, unknown>>;
 }
 export interface ReviewSessionSummary {
     readonly accepted: number;
@@ -53,8 +66,25 @@ export declare function deriveQueueRowStatus(item: ReviewItem, session: ReviewQu
 export declare function nextUnresolvedItemName(session: ReviewQueueSessionState): string | undefined;
 export declare function reviewSessionSummary(session: ReviewQueueSessionState): ReviewSessionSummary;
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
+/**
+ * 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
+ * candidate's original value. Consumers reading `ReviewWorkbenchResult` should
+ * prefer `effectiveValue`/`effectiveDisplayValue`, which are already computed with
+ * 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 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[];
 export declare function replayReviewSessionEvents(startState: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;
+/**
+ * Detects the explicit "clear this ReviewItem's decision" replay signal (emitted
+ * by the workbench's "Change" / undo control): a decision event whose
+ * `data.workbenchDecision` is the literal `null` sentinel, as opposed to `undefined`
+ * (no decision info present — event is ignored by replay, same as before this
+ * feature existed).
+ */
+export declare function isClearedWorkbenchDecisionEvent(event: ReviewSessionEvent): boolean;
 export declare function buildReviewSessionEvent(session: ReviewQueueSessionState, spec: Omit<ReviewSessionEventSpec, "actor">): ReviewSessionEvent;

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

@@ -37,6 +37,7 @@ export function initialReviewQueueSessionState(items = reviewWorkbenchQueueExamp
         activeItemName: items[0]?.metadata.name ?? "",
         notesByItemName: {},
         decisionsByItemName: {},
+        editedValuesByItemName: {},
         reviewedAt: "2026-06-04T00:00:00.000Z",
         actorId: "review-workbench-operator",
     };
@@ -47,6 +48,7 @@ export function currentReviewWorkbenchState(session) {
         item,
         note: session.notesByItemName[item.metadata.name] ?? "",
         decision: session.decisionsByItemName[item.metadata.name],
+        editedValue: session.editedValuesByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
     };
@@ -117,6 +119,18 @@ export function candidateForDecision(item, decision) {
     }
     return candidate;
 }
+/**
+ * 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
+ * candidate's original value. Consumers reading `ReviewWorkbenchResult` should
+ * prefer `effectiveValue`/`effectiveDisplayValue`, which are already computed with
+ * 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);
+    return decision === "accept-proposed" && editedValue !== undefined ? editedValue : candidate.value;
+}
 export function selectedCandidateRole(state) {
     if (!state.decision) {
         return undefined;
@@ -238,6 +252,10 @@ export function replayReviewSessionEvents(startState, events) {
         }
         if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
             && event.spec.reviewItemName) {
+            if (isClearedWorkbenchDecisionEvent(event)) {
+                const { [event.spec.reviewItemName]: _removed, ...remainingDecisions } = session.decisionsByItemName;
+                return { ...session, decisionsByItemName: remainingDecisions };
+            }
             const decision = workbenchDecisionFromEvent(event);
             return decision
                 ? {
@@ -252,6 +270,18 @@ export function replayReviewSessionEvents(startState, events) {
         return session;
     }, startState);
 }
+/**
+ * Detects the explicit "clear this ReviewItem's decision" replay signal (emitted
+ * by the workbench's "Change" / undo control): a decision event whose
+ * `data.workbenchDecision` is the literal `null` sentinel, as opposed to `undefined`
+ * (no decision info present — event is ignored by replay, same as before this
+ * feature existed).
+ */
+export function isClearedWorkbenchDecisionEvent(event) {
+    return event.spec.data !== undefined
+        && "workbenchDecision" in event.spec.data
+        && event.spec.data.workbenchDecision === null;
+}
 export function buildReviewSessionEvent(session, spec) {
     return {
         apiVersion: reviewResourceApiVersion,

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

@@ -1,4 +1,4 @@
-import { candidateForDecision, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
     const sequenceIssues = validateEventSequence(events);
@@ -35,7 +35,12 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                 message: `ReviewSessionEvent ${event.metadata.name} is a decision event but does not reference a ReviewItem.`,
             });
         }
-        if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
+        if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+            && isClearedWorkbenchDecisionEvent(event)) {
+            // Explicit "clear this ReviewItem's decision" signal (undo). No candidate/status
+            // expectations apply — the event carries no selected candidate.
+        }
+        else if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
             const decision = replayableWorkbenchDecision(event.spec.data?.workbenchDecision);
             if (!decision) {
                 issues.push({