@kontourai/survey 1.9.0 → 1.10.0

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.10.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",