@kontourai/survey 1.9.0 → 1.11.0

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/src/to-surface.d.ts

@@ -1,6 +1,34 @@
 import type { TrustBundle } from "@kontourai/surface";
+import { type CalibrationMetrics } from "./calibration.js";
 import type { SurveyInput } from "./types.js";
+export interface SurveyCalibrationOptions {
+    /**
+     * Precomputed calibration to source the value from — typically derived over a
+     * LONGER history than the current batch (a better-grounded curve, and it avoids
+     * the mild self-reference of a claim's own review outcome feeding its value).
+     * When omitted, calibration is derived from THIS batch's review outcomes.
+     */
+    metrics?: CalibrationMetrics;
+    /**
+     * Minimum labeled samples a group needs before its accuracy is emitted as a
+     * value. Groups below the floor leave `value` unset rather than emitting a
+     * poorly-grounded number. Default {@link DEFAULT_CALIBRATION_MIN_SAMPLES}.
+     */
+    minSamples?: number;
+}
 export interface BuildSurveyTrustBundleOptions {
     reviewProofs?: boolean;
+    /**
+     * Populate `conclusionConfidence.value` from empirical review calibration —
+     * "how often this extractor's proposals at this confidence were affirmed by a
+     * human reviewer" (the produce side of the confidence loop; see #114/#137).
+     * `true` derives calibration from this batch; an object supplies precomputed
+     * metrics and/or a `minSamples` floor. Absent → `value` stays unset and only
+     * the comfort-zone signal is carried (unchanged behavior).
+     *
+     * ADVISORY (ADR 0003 §4): this only enriches the emitted conclusion confidence;
+     * it never changes a claim's `status`.
+     */
+    calibration?: boolean | SurveyCalibrationOptions;
 }
 export declare function buildSurveyTrustBundle(input: SurveyInput, options?: BuildSurveyTrustBundleOptions): TrustBundle;

package/dist/src/to-surface.js

@@ -1,10 +1,23 @@
 import { buildReviewProofAnchor } from "./review-proof.js";
 import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
+import { deriveCalibration } from "./calibration.js";
+/** Minimum labeled samples a calibration group needs before its empirical
+ *  accuracy is emitted as a `conclusionConfidence.value`. */
+const DEFAULT_CALIBRATION_MIN_SAMPLES = 20;
 export function buildSurveyTrustBundle(input, options = {}) {
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
     const candidateSets = indexById(input.candidateSets, "candidate set");
     const reviewsByCandidateSet = groupBy(input.reviewOutcomes, (review) => review.candidateSetId);
+    const calibrationOptions = normalizeCalibrationOptions(options.calibration);
+    const calibrationMetrics = calibrationOptions
+        ? (calibrationOptions.metrics ?? deriveCalibration({
+            reviewOutcomes: input.reviewOutcomes,
+            candidateSets: input.candidateSets,
+            extractions: input.extractions,
+        }))
+        : undefined;
+    const calibrationMinSamples = calibrationOptions?.minSamples ?? DEFAULT_CALIBRATION_MIN_SAMPLES;
     const claims = [];
     const evidence = [];
     const events = [];
@@ -47,18 +60,35 @@ export function buildSurveyTrustBundle(input, options = {}) {
                 survey: buildSurveyMetadata({ projection, rawSource, extraction, candidateSet, candidate, review }),
             },
         };
-        // Promote the review's comfort-zone signal into the first-class
-        // conclusionConfidence field (Surface 2.9 / Hachure 0.14) so the calibration
+        // Promote the review's comfort-zone signal — and, when calibration is
+        // enabled, an empirically-calibrated conclusion probability — into the
+        // first-class conclusionConfidence field (Surface 2.9 / Hachure 0.14) so the
         // signal is portable and comparable, not buried in producer metadata.
-        // We carry only comfortZone: `value` is a *calibrated conclusion probability*
-        // that Survey does not yet produce (extraction confidence is an ingredient in
-        // confidenceBasis, not a calibrated conclusion value) — carry, not produce.
-        if (review?.withinComfortZone !== undefined) {
+        //
+        // comfortZone is CARRIED from the review. `value` is PRODUCED from empirical
+        // review calibration (#114/#137): the affirmation rate of this extractor's
+        // proposals at this confidence — a calibrated conclusion probability, distinct
+        // from the extraction-confidence ingredient in confidenceBasis.
+        //
+        // A value is produced only for an AFFIRMED conclusion (status verified/assumed)
+        // that clears the sample floor. conclusionConfidence.value is "probability the
+        // conclusion is correct"; attaching an affirmation rate to a REJECTED (or
+        // not-yet-reviewed) conclusion would assert the opposite of what the human
+        // decided, so those claims get no value.
+        const comfortZone = review?.withinComfortZone !== undefined
+            ? {
+                within: review.withinComfortZone,
+                ...(review.comfortZoneNote ? { reason: review.comfortZoneNote } : {}),
+            }
+            : undefined;
+        const affirmedConclusion = status === "verified" || status === "assumed";
+        const calibrated = calibrationMetrics && review && affirmedConclusion
+            ? lookupCalibratedValue(calibrationMetrics, extraction.extractor, extraction.target, calibrationMinSamples)
+            : undefined;
+        if (comfortZone || calibrated) {
             claim.conclusionConfidence = {
-                comfortZone: {
-                    within: review.withinComfortZone,
-                    ...(review.comfortZoneNote ? { reason: review.comfortZoneNote } : {}),
-                },
+                ...(calibrated ? { value: calibrated.value, method: calibrated.method } : {}),
+                ...(comfortZone ? { comfortZone } : {}),
             };
         }
         if (options.reviewProofs && review) {
@@ -370,6 +400,31 @@ function selectCandidate(candidateSet, candidateId) {
 function selectReview(reviews, candidateId) {
     return reviews.find((review) => review.candidateId === candidateId) ?? reviews.find((review) => !review.candidateId);
 }
+function normalizeCalibrationOptions(calibration) {
+    if (calibration === undefined || calibration === false)
+        return undefined;
+    if (calibration === true)
+        return {};
+    return calibration;
+}
+/**
+ * Looks up the empirical affirmation rate for an extractor/field, preferring the
+ * finer (extractor, field) group and falling back to the extractor-level group
+ * when the field group is below the sample floor. Returns undefined when neither
+ * group clears the floor, so an ungrounded claim leaves `value` unset. The
+ * `method` records which granularity produced the value.
+ */
+function lookupCalibratedValue(metrics, extractor, field, minSamples) {
+    const fieldGroup = metrics.byExtractorField.find((g) => g.extractor === extractor && g.field === field);
+    if (fieldGroup && fieldGroup.sampleCount >= minSamples && fieldGroup.empiricalAccuracy !== undefined) {
+        return { value: fieldGroup.empiricalAccuracy, method: "empirical-review-calibration:extractor-field" };
+    }
+    const extractorGroup = metrics.byExtractor.find((g) => g.extractor === extractor);
+    if (extractorGroup && extractorGroup.sampleCount >= minSamples && extractorGroup.empiricalAccuracy !== undefined) {
+        return { value: extractorGroup.empiricalAccuracy, method: "empirical-review-calibration:extractor" };
+    }
+    return undefined;
+}
 function evidenceTypeFor(rawSource) {
     if (rawSource.kind === "policy-standard")
         return "policy_rule";

package/package.json

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