@kontourai/survey 1.7.0 → 1.9.0

package/dist/src/calibration.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Extraction-confidence calibration from human review outcomes.
+ *
+ * Survey owns the review chain, so it owns the one signal no eval vendor can
+ * publish: for every reviewed candidate, the stated extraction/candidate
+ * confidence (the PREDICTION) against the human review decision (the LABEL).
+ * Grouping those labeled samples by extractor (and field) and binning by
+ * confidence yields an empirical calibration curve — "confidence in [0.8,0.9)
+ * from extractor X was affirmed 17/20 times" — plus a calibration gap and an
+ * empirically-grounded auto-accept threshold suggestion.
+ *
+ * ADVISORY ONLY (ADR 0003 §4, proposals-only). Calibration INFORMS policy — the
+ * suggested threshold an operator MAY wire into `autoAcceptMinConfidence` — it
+ * never decides a claim or mutates a status. Projected claims carry status
+ * "proposed", exactly like every other producer proposal.
+ *
+ * Machine auto-accepts are EXCLUDED by default: an auto-accepted outcome is the
+ * threshold accepting its own guess, so counting it as a "correct" label would
+ * let the policy validate itself (circular). Only human review outcomes are
+ * labeled samples. Set `includeAutoAccepted` to override.
+ *
+ * All computations are deterministic; `now` + `windowDays` window by `reviewedAt`.
+ */
+import type { Claim, Evidence, TrustBundle, VerificationEvent } from "@kontourai/surface";
+import type { CandidateSet, Extraction, ReviewOutcome } from "./types.js";
+/**
+ * The three record arrays a calibration derivation reads — a subset of
+ * {@link SurveyInput}. Kept narrow so a caller can pass an existing batch's
+ * fields directly without constructing a whole SurveyInput.
+ */
+export interface CalibrationInput {
+    readonly reviewOutcomes: readonly ReviewOutcome[];
+    readonly candidateSets: readonly CandidateSet[];
+    readonly extractions: readonly Extraction[];
+}
+export interface DeriveCalibrationOptions {
+    /**
+     * Current time — required only when `windowDays` is set (windowing is by
+     * `reviewedAt`). Injected for determinism; never read from the wall clock.
+     */
+    readonly now?: Date;
+    /**
+     * Optional rolling window in days. Review outcomes whose `reviewedAt` is older
+     * than `now - windowDays` are excluded. Requires `now` — setting `windowDays`
+     * without `now` throws (rather than silently disabling windowing). When
+     * omitted, all supplied outcomes are considered.
+     */
+    readonly windowDays?: number;
+    /** Number of equal-width confidence bins over [0,1]. Default 10 (deciles). */
+    readonly binCount?: number;
+    /**
+     * The empirical accuracy the suggested threshold must clear. Default 0.95.
+     * A `suggestedThreshold` is the lowest bin lower-bound at/above which every
+     * populated bin's empirical accuracy meets this target.
+     */
+    readonly targetAccuracy?: number;
+    /**
+     * A bin needs at least this many samples to count toward `suggestedThreshold`
+     * (both to qualify and to disqualify). Default 1. Raise it to avoid grounding
+     * a threshold on a bin with too little evidence.
+     */
+    readonly minBinSamples?: number;
+    /**
+     * Include machine auto-accepted outcomes (actor === AUTO_ACCEPT_ACTOR) as
+     * labeled samples. Default false — see the module note on circularity.
+     */
+    readonly includeAutoAccepted?: boolean;
+}
+/** One labeled calibration sample: a prediction paired with the human label. */
+export interface CalibrationSample {
+    /** The extractor that produced the proposed value (or "unknown"). */
+    readonly extractor: string;
+    /** The extraction target / field the value belongs to. */
+    readonly field: string;
+    /** The proposed candidate's stated confidence, clamped to [0,1]. */
+    readonly predictedConfidence: number;
+    /** True iff the human review affirmed the proposed value. */
+    readonly correct: boolean;
+    /** The review outcome this sample came from. */
+    readonly reviewOutcomeId: string;
+    /** The candidate set the outcome reviewed. */
+    readonly candidateSetId: string;
+    /** The outcome's `reviewedAt`, when present. */
+    readonly reviewedAt: string | undefined;
+}
+/** An equal-width confidence bin with its empirical accuracy. */
+export interface CalibrationBin {
+    /** Inclusive lower bound of the bin. */
+    readonly lowerBound: number;
+    /** Exclusive upper bound (inclusive at 1.0 for the top bin). */
+    readonly upperBound: number;
+    readonly sampleCount: number;
+    readonly correctCount: number;
+    /** correctCount / sampleCount; undefined when the bin has no samples. */
+    readonly empiricalAccuracy: number | undefined;
+    /** Mean predicted confidence of samples in the bin; undefined when empty. */
+    readonly meanPredictedConfidence: number | undefined;
+}
+/** A calibration rollup for one extractor (and optionally one field). */
+export interface CalibrationGroup {
+    readonly extractor: string;
+    /** The field, or undefined for an extractor-level rollup across all fields. */
+    readonly field: string | undefined;
+    readonly sampleCount: number;
+    readonly correctCount: number;
+    /** correctCount / sampleCount; undefined when the group has no samples. */
+    readonly empiricalAccuracy: number | undefined;
+    /** Mean predicted confidence across the group; undefined when no samples. */
+    readonly meanPredictedConfidence: number | undefined;
+    /**
+     * meanPredictedConfidence − empiricalAccuracy. Positive → overconfident
+     * (states more confidence than the humans bear out); negative →
+     * underconfident. undefined when the group has no samples.
+     */
+    readonly calibrationGap: number | undefined;
+    /** Per-bin empirical accuracy, ascending by lowerBound. */
+    readonly bins: readonly CalibrationBin[];
+    /**
+     * Lowest bin lowerBound at/above which every populated bin (≥ minBinSamples)
+     * meets `targetAccuracy`, scanning the top-contiguous run of qualifying bins.
+     * undefined when no bin qualifies — the data does not yet support an empirical
+     * auto-accept threshold at that target. ADVISORY: an operator wires this into
+     * `autoAcceptMinConfidence`; calibration never sets it.
+     */
+    readonly suggestedThreshold: number | undefined;
+}
+export interface CalibrationMetrics {
+    /** One rollup per extractor (field === undefined), sorted by extractor. */
+    readonly byExtractor: readonly CalibrationGroup[];
+    /** One rollup per (extractor, field) pair, sorted by extractor then field. */
+    readonly byExtractorField: readonly CalibrationGroup[];
+    /** A single rollup across every labeled sample (extractor "*"). */
+    readonly overall: CalibrationGroup;
+    /** Number of labeled samples used. */
+    readonly sampleCount: number;
+    /** Outcomes that could not be turned into a labeled sample (see reasons). */
+    readonly skippedCount: number;
+    /** ISO 8601 timestamp of the earliest labeled sample's `reviewedAt`. */
+    readonly windowStart: string | undefined;
+    /** ISO 8601 timestamp of the latest labeled sample's `reviewedAt`. */
+    readonly windowEnd: string | undefined;
+    /** The `windowDays` option echoed back (undefined when not windowed). */
+    readonly windowDays: number | undefined;
+}
+/**
+ * Derives extractor/field confidence calibration from review outcomes.
+ *
+ * Each reviewed candidate set contributes one labeled sample: the confidence of
+ * the SYSTEM-proposed candidate (`CandidateSet.selectedCandidateId`) as the
+ * prediction, and whether the human review affirmed that proposed value as the
+ * label. A sample is skipped when it carries no human label or no prediction:
+ *
+ * - status "proposed" (not yet reviewed);
+ * - a machine auto-accept, unless `includeAutoAccepted` is set;
+ * - no `selectedCandidateId`, or the selected candidate / its confidence is
+ *   missing or non-finite (no prediction to calibrate).
+ *
+ * A sample is "correct" when the outcome status is verified/assumed AND the
+ * reviewer did not switch to a different candidate; "incorrect" when the status
+ * is rejected or the reviewer overrode the proposed candidate.
+ */
+export declare function deriveCalibration(input: CalibrationInput, options?: DeriveCalibrationOptions): CalibrationMetrics;
+/** A single projected calibration claim triple. */
+export interface CalibrationClaim {
+    readonly claim: Claim;
+    readonly evidence: Evidence;
+    readonly event: VerificationEvent;
+}
+export interface CalibrationClaimsSubject {
+    /** Surface subject type (e.g. "extractor"). */
+    readonly subjectType: string;
+    /** Surface subject id prefix (e.g. a producer or run id). */
+    readonly subjectId: string;
+    /** Surface facet (e.g. "review.calibration"). */
+    readonly facet: string;
+    /** Actor id to record on events. */
+    readonly actor: string;
+    /** ISO 8601 timestamp for claim created/updated times. */
+    readonly observedAt: string;
+    /** Producer identifier for the evidence `collectedBy` field. */
+    readonly collectedBy: string;
+}
+/**
+ * Projects per-extractor calibration as Surface-ready claims (claimType
+ * "calibration"). One claim per measurable metric per extractor: empirical
+ * accuracy, calibration gap, and — when the data supports it — the suggested
+ * auto-accept threshold. Every claim is status "proposed": calibration proposes,
+ * it never decides (ADR 0003 §4). Groups with no labeled samples are skipped.
+ */
+export declare function calibrationToClaims(metrics: CalibrationMetrics, subject: CalibrationClaimsSubject): CalibrationClaim[];
+/**
+ * Merges calibration claims into an existing TrustBundle. Convenience wrapper
+ * mirroring `mergeTrustBundleWithOversightMetrics`.
+ */
+export declare function mergeTrustBundleWithCalibration(bundle: TrustBundle, claims: readonly CalibrationClaim[]): TrustBundle;

package/dist/src/calibration.js

@@ -0,0 +1,361 @@
+/**
+ * Extraction-confidence calibration from human review outcomes.
+ *
+ * Survey owns the review chain, so it owns the one signal no eval vendor can
+ * publish: for every reviewed candidate, the stated extraction/candidate
+ * confidence (the PREDICTION) against the human review decision (the LABEL).
+ * Grouping those labeled samples by extractor (and field) and binning by
+ * confidence yields an empirical calibration curve — "confidence in [0.8,0.9)
+ * from extractor X was affirmed 17/20 times" — plus a calibration gap and an
+ * empirically-grounded auto-accept threshold suggestion.
+ *
+ * ADVISORY ONLY (ADR 0003 §4, proposals-only). Calibration INFORMS policy — the
+ * suggested threshold an operator MAY wire into `autoAcceptMinConfidence` — it
+ * never decides a claim or mutates a status. Projected claims carry status
+ * "proposed", exactly like every other producer proposal.
+ *
+ * Machine auto-accepts are EXCLUDED by default: an auto-accepted outcome is the
+ * threshold accepting its own guess, so counting it as a "correct" label would
+ * let the policy validate itself (circular). Only human review outcomes are
+ * labeled samples. Set `includeAutoAccepted` to override.
+ *
+ * All computations are deterministic; `now` + `windowDays` window by `reviewedAt`.
+ */
+import { AUTO_ACCEPT_ACTOR } from "./producer-profile.js";
+const DEFAULT_BIN_COUNT = 10;
+const DEFAULT_TARGET_ACCURACY = 0.95;
+const DEFAULT_MIN_BIN_SAMPLES = 1;
+// ---------------------------------------------------------------------------
+// deriveCalibration
+// ---------------------------------------------------------------------------
+/**
+ * Derives extractor/field confidence calibration from review outcomes.
+ *
+ * Each reviewed candidate set contributes one labeled sample: the confidence of
+ * the SYSTEM-proposed candidate (`CandidateSet.selectedCandidateId`) as the
+ * prediction, and whether the human review affirmed that proposed value as the
+ * label. A sample is skipped when it carries no human label or no prediction:
+ *
+ * - status "proposed" (not yet reviewed);
+ * - a machine auto-accept, unless `includeAutoAccepted` is set;
+ * - no `selectedCandidateId`, or the selected candidate / its confidence is
+ *   missing or non-finite (no prediction to calibrate).
+ *
+ * A sample is "correct" when the outcome status is verified/assumed AND the
+ * reviewer did not switch to a different candidate; "incorrect" when the status
+ * is rejected or the reviewer overrode the proposed candidate.
+ */
+export function deriveCalibration(input, options = {}) {
+    const binCount = normalizeBinCount(options.binCount);
+    const targetAccuracy = options.targetAccuracy ?? DEFAULT_TARGET_ACCURACY;
+    const minBinSamples = options.minBinSamples ?? DEFAULT_MIN_BIN_SAMPLES;
+    const includeAutoAccepted = options.includeAutoAccepted ?? false;
+    const candidateSetById = new Map(input.candidateSets.map((cs) => [cs.id, cs]));
+    const candidateById = new Map();
+    for (const cs of input.candidateSets) {
+        for (const c of cs.candidates)
+            candidateById.set(c.id, c);
+    }
+    const extractionById = new Map(input.extractions.map((e) => [e.id, e]));
+    if (options.windowDays !== undefined && options.now === undefined) {
+        throw new RangeError("deriveCalibration: `now` is required when `windowDays` is set (windowing is by reviewedAt).");
+    }
+    const cutoff = options.windowDays !== undefined && options.now !== undefined
+        ? options.now.getTime() - options.windowDays * 24 * 60 * 60 * 1000
+        : undefined;
+    const samples = [];
+    let skippedCount = 0;
+    for (const outcome of input.reviewOutcomes) {
+        if (cutoff !== undefined) {
+            const t = outcome.reviewedAt ? Date.parse(outcome.reviewedAt) : NaN;
+            if (isNaN(t) || t < cutoff) {
+                skippedCount++;
+                continue;
+            }
+        }
+        const sample = toSample(outcome, candidateSetById, candidateById, extractionById, includeAutoAccepted);
+        if (sample === undefined) {
+            skippedCount++;
+            continue;
+        }
+        samples.push(sample);
+    }
+    const timestamps = samples
+        .map((s) => (s.reviewedAt ? Date.parse(s.reviewedAt) : NaN))
+        .filter((t) => !isNaN(t))
+        .sort((a, b) => a - b);
+    const windowStart = timestamps.length > 0 ? new Date(timestamps[0]).toISOString() : undefined;
+    const windowEnd = timestamps.length > 0 ? new Date(timestamps[timestamps.length - 1]).toISOString() : undefined;
+    const buildGroup = (extractor, field, groupSamples) => computeGroup(extractor, field, groupSamples, binCount, targetAccuracy, minBinSamples);
+    // Extractor-level rollups.
+    const byExtractorMap = new Map();
+    // (extractor, field) rollups. The key is a JSON-encoded [extractor, field]
+    // pair so no in-band delimiter can collide with an extractor/field that
+    // contains that delimiter; the extractor and field are carried in the value,
+    // never parsed back out of the key.
+    const byFieldMap = new Map();
+    for (const s of samples) {
+        pushTo(byExtractorMap, s.extractor, s);
+        const fieldKey = JSON.stringify([s.extractor, s.field]);
+        const existing = byFieldMap.get(fieldKey);
+        if (existing)
+            existing.samples.push(s);
+        else
+            byFieldMap.set(fieldKey, { extractor: s.extractor, field: s.field, samples: [s] });
+    }
+    const byExtractor = [...byExtractorMap.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([extractor, groupSamples]) => buildGroup(extractor, undefined, groupSamples));
+    const byExtractorField = [...byFieldMap.values()]
+        .sort((a, b) => (a.extractor < b.extractor ? -1 : a.extractor > b.extractor ? 1 : a.field < b.field ? -1 : a.field > b.field ? 1 : 0))
+        .map(({ extractor, field, samples: groupSamples }) => buildGroup(extractor, field, groupSamples));
+    const overall = buildGroup("*", undefined, samples);
+    return {
+        byExtractor,
+        byExtractorField,
+        overall,
+        sampleCount: samples.length,
+        skippedCount,
+        windowStart,
+        windowEnd,
+        windowDays: options.windowDays,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: sample construction
+// ---------------------------------------------------------------------------
+function toSample(outcome, candidateSetById, candidateById, extractionById, includeAutoAccepted) {
+    // No human label yet.
+    if (outcome.status === "proposed")
+        return undefined;
+    // Machine auto-accepts are not human labels (circular) unless opted in.
+    if (!includeAutoAccepted && outcome.actor === AUTO_ACCEPT_ACTOR)
+        return undefined;
+    const candidateSet = candidateSetById.get(outcome.candidateSetId);
+    if (candidateSet === undefined)
+        return undefined;
+    // The prediction is the SYSTEM-proposed candidate's confidence.
+    const proposedId = candidateSet.selectedCandidateId;
+    if (proposedId === undefined)
+        return undefined;
+    const proposed = candidateById.get(proposedId);
+    if (proposed === undefined)
+        return undefined;
+    const extraction = proposed.extractionId ? extractionById.get(proposed.extractionId) : undefined;
+    const rawConfidence = proposed.confidence ?? extraction?.confidence;
+    if (rawConfidence === undefined || !Number.isFinite(rawConfidence))
+        return undefined;
+    const predictedConfidence = clamp01(rawConfidence);
+    const extractor = extraction?.extractor ?? "unknown";
+    const field = extraction?.target ?? candidateSet.target;
+    // The label: did the human affirm the proposed value?
+    let correct;
+    if (outcome.status === "rejected") {
+        correct = false;
+    }
+    else {
+        // verified | assumed — an override to a different candidate means the
+        // proposed value did NOT stand.
+        const overrode = outcome.candidateId !== undefined && outcome.candidateId !== proposedId;
+        correct = !overrode;
+    }
+    return {
+        extractor,
+        field,
+        predictedConfidence,
+        correct,
+        reviewOutcomeId: outcome.id,
+        candidateSetId: outcome.candidateSetId,
+        reviewedAt: outcome.reviewedAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: group + bin computation
+// ---------------------------------------------------------------------------
+function computeGroup(extractor, field, samples, binCount, targetAccuracy, minBinSamples) {
+    const sampleCount = samples.length;
+    const correctCount = samples.filter((s) => s.correct).length;
+    const empiricalAccuracy = sampleCount > 0 ? correctCount / sampleCount : undefined;
+    const meanPredictedConfidence = sampleCount > 0
+        ? samples.reduce((sum, s) => sum + s.predictedConfidence, 0) / sampleCount
+        : undefined;
+    const calibrationGap = meanPredictedConfidence !== undefined && empiricalAccuracy !== undefined
+        ? meanPredictedConfidence - empiricalAccuracy
+        : undefined;
+    const bins = computeBins(samples, binCount);
+    const suggestedThreshold = computeSuggestedThreshold(bins, targetAccuracy, minBinSamples);
+    return {
+        extractor,
+        field,
+        sampleCount,
+        correctCount,
+        empiricalAccuracy: round(empiricalAccuracy),
+        meanPredictedConfidence: round(meanPredictedConfidence),
+        calibrationGap: round(calibrationGap),
+        bins,
+        suggestedThreshold,
+    };
+}
+function computeBins(samples, binCount) {
+    const width = 1 / binCount;
+    const counts = Array.from({ length: binCount }, () => ({ n: 0, correct: 0, sum: 0 }));
+    for (const s of samples) {
+        const idx = Math.min(binCount - 1, Math.floor(s.predictedConfidence * binCount));
+        const bucket = counts[idx];
+        bucket.n++;
+        bucket.sum += s.predictedConfidence;
+        if (s.correct)
+            bucket.correct++;
+    }
+    return counts.map((b, i) => ({
+        lowerBound: round(i * width),
+        upperBound: round((i + 1) * width),
+        sampleCount: b.n,
+        correctCount: b.correct,
+        empiricalAccuracy: b.n > 0 ? round(b.correct / b.n) : undefined,
+        meanPredictedConfidence: b.n > 0 ? round(b.sum / b.n) : undefined,
+    }));
+}
+/**
+ * The suggested threshold is the lowerBound of the lowest bin in the
+ * top-contiguous run of bins that each (a) have ≥ minBinSamples and (b) meet
+ * targetAccuracy. Scanning from the highest bin down, a populated bin that
+ * fails the target — or an under-sampled bin we cannot vouch for — ends the run.
+ * undefined when even the top populated bin does not qualify.
+ */
+function computeSuggestedThreshold(bins, targetAccuracy, minBinSamples) {
+    let threshold;
+    for (let i = bins.length - 1; i >= 0; i--) {
+        const bin = bins[i];
+        if (bin.sampleCount < minBinSamples)
+            break;
+        if (bin.empiricalAccuracy === undefined || bin.empiricalAccuracy < targetAccuracy)
+            break;
+        threshold = bin.lowerBound;
+    }
+    return threshold;
+}
+/**
+ * Projects per-extractor calibration as Surface-ready claims (claimType
+ * "calibration"). One claim per measurable metric per extractor: empirical
+ * accuracy, calibration gap, and — when the data supports it — the suggested
+ * auto-accept threshold. Every claim is status "proposed": calibration proposes,
+ * it never decides (ADR 0003 §4). Groups with no labeled samples are skipped.
+ */
+export function calibrationToClaims(metrics, subject) {
+    const results = [];
+    for (const group of metrics.byExtractor) {
+        if (group.sampleCount === 0)
+            continue;
+        const base = `${sanitize(group.extractor)}`;
+        const push = (metric, value, detail) => {
+            const claimId = `calibration.${subject.subjectId}.${base}.${metric}`;
+            const evidenceId = `${claimId}.evidence`;
+            const claim = {
+                id: claimId,
+                subjectType: subject.subjectType,
+                subjectId: `${subject.subjectId}.${group.extractor}`,
+                facet: subject.facet,
+                claimType: "calibration",
+                fieldOrBehavior: metric,
+                value,
+                status: "proposed",
+                createdAt: subject.observedAt,
+                updatedAt: subject.observedAt,
+                impactLevel: "medium",
+                confidenceBasis: {
+                    sourceQuality: "moderate",
+                    reviewerAuthority: "none",
+                    evidenceStrength: "weak",
+                    impactLevel: "medium",
+                },
+                metadata: {
+                    calibration: {
+                        extractor: group.extractor,
+                        sampleCount: group.sampleCount,
+                        correctCount: group.correctCount,
+                        empiricalAccuracy: group.empiricalAccuracy,
+                        meanPredictedConfidence: group.meanPredictedConfidence,
+                        calibrationGap: group.calibrationGap,
+                        suggestedThreshold: group.suggestedThreshold,
+                        windowStart: metrics.windowStart,
+                        windowEnd: metrics.windowEnd,
+                        windowDays: metrics.windowDays,
+                    },
+                },
+            };
+            const evidence = {
+                id: evidenceId,
+                claimId,
+                evidenceType: "attestation",
+                method: "extraction",
+                sourceRef: "calibration://computed",
+                excerptOrSummary: `calibration.${metric} for extractor ${group.extractor}: ${detail}; ` +
+                    `over ${group.correctCount}/${group.sampleCount} affirmed human review outcomes`,
+                observedAt: subject.observedAt,
+                collectedBy: subject.collectedBy,
+            };
+            const event = {
+                id: `${claimId}.event`,
+                claimId,
+                status: "proposed",
+                actor: subject.actor,
+                method: "candidate-proposal",
+                evidenceIds: [evidenceId],
+                createdAt: subject.observedAt,
+            };
+            results.push({ claim, evidence, event });
+        };
+        if (group.empiricalAccuracy !== undefined) {
+            push("empiricalAccuracy", group.empiricalAccuracy, `empirical accuracy = ${group.empiricalAccuracy}`);
+        }
+        if (group.calibrationGap !== undefined) {
+            push("calibrationGap", group.calibrationGap, `mean confidence − empirical accuracy = ${group.calibrationGap}`);
+        }
+        if (group.suggestedThreshold !== undefined) {
+            push("suggestedThreshold", group.suggestedThreshold, `advisory auto-accept threshold = ${group.suggestedThreshold}`);
+        }
+    }
+    return results;
+}
+/**
+ * Merges calibration claims into an existing TrustBundle. Convenience wrapper
+ * mirroring `mergeTrustBundleWithOversightMetrics`.
+ */
+export function mergeTrustBundleWithCalibration(bundle, claims) {
+    return {
+        ...bundle,
+        claims: [...bundle.claims, ...claims.map((c) => c.claim)],
+        evidence: [...bundle.evidence, ...claims.map((c) => c.evidence)],
+        events: [...bundle.events, ...claims.map((c) => c.event)],
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function pushTo(map, key, sample) {
+    const existing = map.get(key);
+    if (existing)
+        existing.push(sample);
+    else
+        map.set(key, [sample]);
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function normalizeBinCount(binCount) {
+    if (binCount === undefined)
+        return DEFAULT_BIN_COUNT;
+    if (!Number.isInteger(binCount) || binCount < 1) {
+        throw new RangeError(`binCount must be a positive integer, received ${binCount}`);
+    }
+    return binCount;
+}
+function round(value) {
+    if (value === undefined)
+        return undefined;
+    return Math.round(value * 10000) / 10000;
+}
+function sanitize(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}

package/dist/src/index.d.ts

@@ -12,6 +12,8 @@ export { buildSurveyTrustBundle } from "./to-surface.js";
 export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export type { LearningProjection, LearningProjectionKind, LearningProjectionSeverity, LearningProjectionSignal, } from "./learning-projections.js";
+export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
+export type { LearningUpdateEvidenceReference, LearningUpdateProposal, OpaqueEvidenceReference, ProvenanceReference, ReviewedLearningUpdateProposalInput, ReviewProofReference, } from "./learning-update-proposal.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
 export type { CanonicalReviewProofPayload, CanonicalReviewProofPayloadV1, CanonicalReviewProofPayloadV2, ReviewProofInput, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
@@ -38,3 +40,5 @@ export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export type { CurrentProposedCandidateInput, CurrentProposedReviewItemInput, } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
 export type { AggregateOversightMetrics, DeriveOversightMetricsOptions, OversightMetrics, OversightMetricsClaimsSubject, OversightQualityClaim, ReviewerOversightMetrics, } from "./oversight-metrics.js";
+export { calibrationToClaims, deriveCalibration, mergeTrustBundleWithCalibration, } from "./calibration.js";
+export type { CalibrationBin, CalibrationClaim, CalibrationClaimsSubject, CalibrationGroup, CalibrationInput, CalibrationMetrics, CalibrationSample, DeriveCalibrationOptions, } from "./calibration.js";

package/dist/src/index.js

@@ -5,6 +5,7 @@ export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js"
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export { buildSurveyTrustBundle } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
+export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
@@ -18,3 +19,4 @@ export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, v
 export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";
 export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
+export { calibrationToClaims, deriveCalibration, mergeTrustBundleWithCalibration, } from "./calibration.js";

package/dist/src/learning-update-proposal.d.ts

@@ -0,0 +1,54 @@
+import type { ClaimTarget, ProvenanceResolution, RawSourceKind, SurveyInput } from "./types.js";
+export interface ReviewProofReference {
+    kind: "review-proof";
+    algorithm: "sha256";
+    value: string;
+    proofSchemaVersion: 2;
+}
+export interface ProvenanceReference {
+    kind: "provenance";
+    rawSourceId: string;
+    origin: RawSourceKind;
+    resolution: ProvenanceResolution;
+    reviewOutcomeId: string;
+}
+export interface OpaqueEvidenceReference {
+    kind: "evidence";
+    id: string;
+}
+export type LearningUpdateEvidenceReference = ReviewProofReference | ProvenanceReference | OpaqueEvidenceReference;
+export interface LearningUpdateProposal {
+    id: string;
+    kind: "learning.update-proposal";
+    source: string;
+    createdAt: string;
+    subject: Pick<ClaimTarget, "subjectType" | "subjectId" | "facet" | "claimType" | "fieldOrBehavior">;
+    applicability: {
+        target: string;
+    };
+    proposedDelta: {
+        previousValue: unknown;
+        proposedValue: unknown;
+    };
+    evidenceRefs: LearningUpdateEvidenceReference[];
+    authorizationRef: {
+        reviewOutcomeId: string;
+        reviewProofHash: string;
+    };
+    reviewLineage: {
+        candidateSetId: string;
+        selectedCandidateId: string;
+        unselectedCandidateIds: string[];
+        reviewOutcomeId: string;
+        selectedClaimId: string;
+    };
+}
+export interface ReviewedLearningUpdateProposalInput {
+    survey: SurveyInput;
+    candidateSetId: string;
+    reviewOutcomeId: string;
+    selectedClaimId: string;
+    proof: ReviewProofReference;
+}
+/** Builds data for a producer-owned application decision. It performs no I/O or domain validation. */
+export declare function buildReviewedLearningUpdateProposal(input: ReviewedLearningUpdateProposalInput): LearningUpdateProposal;

package/dist/src/learning-update-proposal.js

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./review-workbench/canonical.js";
+/** Builds data for a producer-owned application decision. It performs no I/O or domain validation. */
+export function buildReviewedLearningUpdateProposal(input) {
+    const { survey } = input;
+    const candidateSet = exactlyOne(survey.candidateSets, ({ id }) => id === input.candidateSetId, "candidate set");
+    if (!candidateSet || candidateSet.status !== "resolved")
+        throw new Error("learning update requires a resolved candidate set");
+    const roleCandidates = candidateSet.candidates.filter((candidate) => {
+        const role = candidate.metadata?.candidateRole;
+        return role === "current" || role === "proposed";
+    });
+    const current = roleCandidates.filter(({ metadata }) => metadata?.candidateRole === "current");
+    const proposed = roleCandidates.filter(({ metadata }) => metadata?.candidateRole === "proposed");
+    assertUniqueIds(candidateSet.candidates, "candidate");
+    if (current.length !== 1 || proposed.length !== 1) {
+        throw new Error("learning update requires exactly one current and one proposed candidate role");
+    }
+    const currentCandidate = current[0];
+    const proposedCandidate = proposed[0];
+    if (candidateSet.selectedCandidateId !== proposedCandidate.id)
+        throw new Error("learning update requires the proposed candidate to be selected");
+    const review = exactlyOne(survey.reviewOutcomes, ({ id }) => id === input.reviewOutcomeId, "review outcome");
+    if (!review || review.candidateSetId !== candidateSet.id || review.candidateId !== candidateSet.selectedCandidateId) {
+        throw new Error("review outcome must identify the selected candidate and candidate set");
+    }
+    if (review.status !== "verified" && review.status !== "assumed")
+        throw new Error("learning update requires an accepted review status");
+    if (!review.reviewedAt)
+        throw new Error("learning update requires reviewedAt");
+    if (!review.authorizing)
+        throw new Error("learning update requires authorizing review provenance");
+    assertCanonicalProofReference(input.proof);
+    const selectedClaim = exactlyOne(survey.claims, ({ id }) => id === input.selectedClaimId, "selected claim");
+    if (!selectedClaim || selectedClaim.candidateSetId !== candidateSet.id || selectedClaim.candidateId !== proposedCandidate.id) {
+        throw new Error("selected claim must identify the selected proposed candidate and candidate set");
+    }
+    if (selectedClaim.status !== "verified" && selectedClaim.status !== "assumed") {
+        throw new Error("learning update requires an accepted selected claim status");
+    }
+    if (selectedClaim.status !== review.status)
+        throw new Error("selected claim status must match the accepted review status");
+    const currentClaim = exactlyOne(survey.claims, ({ candidateSetId, candidateId }) => candidateSetId === candidateSet.id && candidateId === currentCandidate.id, "current claim");
+    if (!currentClaim || !sameSubject(currentClaim, selectedClaim))
+        throw new Error("current and selected claim lineage must share a subject");
+    const unselectedCandidates = candidateSet.candidates.filter(({ id }) => id !== proposedCandidate.id);
+    for (const candidate of unselectedCandidates) {
+        const claim = exactlyOne(survey.claims, ({ candidateSetId, candidateId }) => candidateSetId === candidateSet.id && candidateId === candidate.id, "unselected claim");
+        if (claim.status !== "superseded")
+            throw new Error("unselected claim status must be superseded");
+    }
+    assertCanonicalJsonValue(currentCandidate.value);
+    assertCanonicalJsonValue(proposedCandidate.value);
+    const currentSource = sourceForCandidate(survey, candidateSet.target, currentCandidate.id, currentCandidate.extractionId, currentCandidate.value);
+    const proposedSource = sourceForCandidate(survey, candidateSet.target, proposedCandidate.id, proposedCandidate.extractionId, proposedCandidate.value);
+    const provenanceRefs = [currentSource, proposedSource].map((source) => {
+        if (source.resolution !== "supersession")
+            throw new Error(`candidate ${source.id} requires explicit supersession provenance`);
+        return { kind: "provenance", rawSourceId: source.id, origin: source.kind, resolution: source.resolution, reviewOutcomeId: review.id };
+    });
+    const evidenceCandidates = [
+        ...(review.evidenceIds ?? []).map((id) => ({ kind: "evidence", id })),
+        ...provenanceRefs,
+        { ...input.proof },
+    ];
+    const evidenceRefs = [...new Map(evidenceCandidates.map((reference) => [canonicalJson(reference), reference])).values()]
+        .sort((left, right) => evidenceRank(left) - evidenceRank(right) || canonicalJson(left).localeCompare(canonicalJson(right)));
+    const subject = pickSubject(selectedClaim);
+    const reviewLineage = {
+        candidateSetId: candidateSet.id,
+        selectedCandidateId: proposedCandidate.id,
+        unselectedCandidateIds: unselectedCandidates.map(({ id }) => id).sort(),
+        reviewOutcomeId: review.id,
+        selectedClaimId: selectedClaim.id,
+    };
+    const authorizationRef = { reviewOutcomeId: review.id, reviewProofHash: input.proof.value };
+    const proposalWithoutId = {
+        kind: "learning.update-proposal",
+        source: survey.source,
+        createdAt: review.reviewedAt,
+        subject,
+        applicability: { target: candidateSet.target },
+        proposedDelta: { previousValue: currentCandidate.value, proposedValue: proposedCandidate.value },
+        evidenceRefs,
+        authorizationRef,
+        reviewLineage,
+    };
+    const identityPayload = { identitySchemaVersion: 1, ...proposalWithoutId };
+    return { id: createHash("sha256").update(canonicalJson(identityPayload)).digest("hex"), ...proposalWithoutId };
+}
+function assertCanonicalProofReference(proof) {
+    if (proof?.kind !== "review-proof" || proof.algorithm !== "sha256" || proof.proofSchemaVersion !== 2) {
+        throw new Error("learning update requires an identified canonical v2 review proof");
+    }
+    if (!/^[a-f0-9]{64}$/.test(proof.value))
+        throw new Error("canonical review proof must be a lowercase SHA-256 hash");
+}
+function sourceForCandidate(survey, target, candidateId, extractionId, value) {
+    const extraction = exactlyOne(survey.extractions, ({ id }) => id === extractionId, "extraction");
+    assertCanonicalJsonValue(extraction.value);
+    if (!extraction || extraction.target !== target || canonicalJson(extraction.value) !== canonicalJson(value)) {
+        throw new Error(`candidate ${candidateId} has inconsistent extraction lineage`);
+    }
+    const source = exactlyOne(survey.rawSources, ({ id }) => id === extraction.sourceId, "raw source");
+    if (!source)
+        throw new Error(`candidate ${candidateId} has missing source lineage`);
+    return source;
+}
+function pickSubject(claim) {
+    return { subjectType: claim.subjectType, subjectId: claim.subjectId, facet: claim.facet, claimType: claim.claimType, fieldOrBehavior: claim.fieldOrBehavior };
+}
+function sameSubject(left, right) {
+    return canonicalJson(pickSubject(left)) === canonicalJson(pickSubject(right));
+}
+function evidenceRank(reference) {
+    if (reference.kind === "evidence")
+        return 0;
+    if (reference.kind === "provenance")
+        return 1;
+    return 2;
+}
+function exactlyOne(records, predicate, label) {
+    const matches = records.filter(predicate);
+    if (matches.length !== 1)
+        throw new Error(`learning update requires exactly one ${label}; found ${matches.length}`);
+    return matches[0];
+}
+function assertUniqueIds(records, label) {
+    const ids = new Set();
+    for (const { id } of records) {
+        if (ids.has(id))
+            throw new Error(`learning update rejects duplicate ${label} id ${id}`);
+        ids.add(id);
+    }
+}
+/** Values are limited to JSON primitives, arrays, and plain string-keyed objects. */
+function assertCanonicalJsonValue(value, ancestors = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value) && !Object.is(value, -0))
+            return;
+        throw new Error("invalid canonical JSON value: number is not collision-free");
+    }
+    if (typeof value !== "object")
+        throw new Error("invalid canonical JSON value: unsupported primitive");
+    if (ancestors.has(value))
+        throw new Error("invalid canonical JSON value: cycle");
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        throw new Error("invalid canonical JSON value: unsupported prototype");
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        if (Object.getOwnPropertySymbols(value).length > 0)
+            throw new Error("invalid canonical JSON value: symbol-keyed array property");
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const expectedKeys = Array.from({ length: value.length }, (_, index) => String(index));
+        const actualKeys = Object.keys(descriptors).filter((key) => key !== "length");
+        if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, index) => key !== expectedKeys[index])) {
+            throw new Error("invalid canonical JSON value: sparse or extra array property");
+        }
+        for (const key of expectedKeys) {
+            const descriptor = descriptors[key];
+            if (!descriptor.enumerable || !("value" in descriptor))
+                throw new Error("invalid canonical JSON value: array accessor or hidden property");
+            assertCanonicalJsonValue(descriptor.value, ancestors);
+        }
+    }
+    else {
+        if (Object.getOwnPropertySymbols(value).length > 0)
+            throw new Error("invalid canonical JSON value: symbol-keyed property");
+        for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(value))) {
+            if (!descriptor.enumerable || !("value" in descriptor))
+                throw new Error("invalid canonical JSON value: property is not enumerable data");
+            assertCanonicalJsonValue(descriptor.value, ancestors);
+        }
+    }
+    ancestors.delete(value);
+}

package/dist/src/to-surface.js

@@ -47,6 +47,20 @@ 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
+        // 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) {
+            claim.conclusionConfidence = {
+                comfortZone: {
+                    within: review.withinComfortZone,
+                    ...(review.comfortZoneNote ? { reason: review.comfortZoneNote } : {}),
+                },
+            };
+        }
         if (options.reviewProofs && review) {
             claim.currentIntegrityAnchor = buildReviewProofAnchor({
                 rawSource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -71,7 +71,7 @@
     "check:generated-css": "node scripts/copy-review-workbench-package-assets.cjs --check"
   },
   "dependencies": {
-    "@kontourai/surface": "^2.0.0"
+    "@kontourai/surface": "^2.9.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.20.0",