@kontourai/survey 3.0.0 → 4.0.0

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

@@ -1,6 +1,6 @@
 import type { ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
-export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason";
+export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch";
 export interface ReviewSessionReplayIssue {
     readonly code: ReviewSessionReplayIssueCode;
     readonly eventName: string;
@@ -10,3 +10,37 @@ export interface ReviewSessionReplayIssue {
     readonly message: string;
 }
 export declare function validateReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayIssue[];
+/**
+ * A ReviewSessionEvent whose `data.workbenchEditedValue` was rewritten from
+ * legacy editor text to its descriptor-typed value during replay (see
+ * checkEditedValueForItem). Not an error: the apply result still succeeds, and
+ * the warning lets a consumer see that a saved session was normalized.
+ */
+export type ReviewSessionReplayWarning = {
+    readonly code: "edited-value-converted-from-text";
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly reviewItemName: string;
+    readonly originalValue: string;
+    readonly convertedValue: unknown;
+    readonly message: string;
+} | {
+    /**
+     * An edit that would be refused (see checkEditedValueForItem) on a
+     * decision event that a later decision for the same item superseded. It
+     * never reaches effectiveValue, so it does not fail the session.
+     */
+    readonly code: "superseded-edited-value-refused";
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly reviewItemName: string;
+    readonly refusedCode: "edited-value-not-editable" | "edited-value-type-mismatch";
+    readonly editedValue: unknown;
+    readonly message: string;
+};
+/**
+ * Lists the legacy text edits replay converts to typed values, and refused
+ * edits that a later decision superseded. Call it only on an event stream that
+ * validateReviewSessionEventsForSnapshot accepted.
+ */
+export declare function reviewSessionReplayWarningsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayWarning[];

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

@@ -1,7 +1,9 @@
 import { candidateForDecision, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { checkEditedValueForItem } from "./edited-value.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
     const sequenceIssues = validateEventSequence(events);
+    const finalDecisionEvents = finalDecisionEventPerItem(events);
     const replayIssues = events.flatMap((event) => {
         const issues = [];
         const activeItemName = event.spec.activeItemName;
@@ -86,6 +88,22 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                         message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects resolution ${expectedResolution ?? "none"}, but references ${event.spec.resolution ?? "no resolution"}.`,
                     });
                 }
+                const editedValue = editedValueFromDecisionEvent(event);
+                // Only the item's final decision decides its effectiveValue, so only an
+                // edit on that event is refused. An edit a later decision superseded is
+                // reported as a warning instead of failing the whole session.
+                if (item && decision === "accept-proposed" && editedValue !== undefined && finalDecisionEvents.has(event)) {
+                    const check = checkEditedValueForItem(item, editedValue);
+                    if (!check.ok) {
+                        issues.push({
+                            ...eventRef,
+                            code: check.code,
+                            reviewItemName: itemName,
+                            candidateId: event.spec.candidateId,
+                            message: `ReviewSessionEvent ${event.metadata.name}: ${check.message}`,
+                        });
+                    }
+                }
                 if (decision === "could-not-confirm" && !event.spec.resolutionReason?.trim()) {
                     issues.push({
                         ...eventRef,
@@ -114,6 +132,65 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     });
     return [...sequenceIssues, ...replayIssues];
 }
+/**
+ * Lists the legacy text edits replay converts to typed values, and refused
+ * edits that a later decision superseded. Call it only on an event stream that
+ * validateReviewSessionEventsForSnapshot accepted.
+ */
+export function reviewSessionReplayWarningsForSnapshot(snapshot, events) {
+    const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
+    const finalDecisionEvents = finalDecisionEventPerItem(events);
+    return events.flatMap((event) => {
+        const itemName = event.spec.reviewItemName;
+        const item = itemName ? itemsByName.get(itemName) : undefined;
+        const editedValue = editedValueFromDecisionEvent(event);
+        if (!item || !itemName || editedValue === undefined
+            || replayableWorkbenchDecision(event.spec.data?.workbenchDecision) !== "accept-proposed") {
+            return [];
+        }
+        const check = checkEditedValueForItem(item, editedValue);
+        if (!check.ok) {
+            return finalDecisionEvents.has(event) ? [] : [{
+                    code: "superseded-edited-value-refused",
+                    eventName: event.metadata.name,
+                    sequence: event.spec.sequence,
+                    reviewItemName: itemName,
+                    refusedCode: check.code,
+                    editedValue,
+                    message: `ReviewSessionEvent ${event.metadata.name} carries an edit a later decision superseded, which would be refused: ${check.message}`,
+                }];
+        }
+        if (!check.convertedFromText || typeof editedValue !== "string") {
+            return [];
+        }
+        return [{
+                code: "edited-value-converted-from-text",
+                eventName: event.metadata.name,
+                sequence: event.spec.sequence,
+                reviewItemName: itemName,
+                originalValue: editedValue,
+                convertedValue: check.value,
+                message: `ReviewSessionEvent ${event.metadata.name} stores edited value ${JSON.stringify(editedValue)} as text; replay converted it to ${JSON.stringify(check.value)} per ReviewItem ${itemName}'s value descriptor.`,
+            }];
+    });
+}
+/** The last decision event (by sequence, as replay applies them) for each ReviewItem. */
+function finalDecisionEventPerItem(events) {
+    const lastByItem = new Map();
+    for (const event of [...events].sort((left, right) => left.spec.sequence - right.spec.sequence)) {
+        if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+            && event.spec.reviewItemName) {
+            lastByItem.set(event.spec.reviewItemName, event);
+        }
+    }
+    return new Set(lastByItem.values());
+}
+function editedValueFromDecisionEvent(event) {
+    return (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+        && event.spec.data && "workbenchEditedValue" in event.spec.data
+        ? event.spec.data.workbenchEditedValue
+        : undefined;
+}
 function replayableWorkbenchDecision(value) {
     return typeof value === "string" && value in workbenchDecisionDefinitions
         ? value

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

@@ -1,5 +1,5 @@
 import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.js";
-import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
+import { type ReviewSessionReplayIssue, type ReviewSessionReplayWarning } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewValueDescriptor } from "../review-resource.js";
 export { reviewAuditRowKeys, type ReviewAuditRowKey } from "./audit-rows.js";
@@ -8,7 +8,8 @@ export { buildExtractionInspectorModel, exportExtractionInspector, filterExtract
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
-export { validateReviewSessionEventsForSnapshot, type ReviewSessionReplayIssue, type ReviewSessionReplayIssueCode, } from "./review-session-replay.js";
+export { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, type ReviewSessionReplayIssue, type ReviewSessionReplayIssueCode, type ReviewSessionReplayWarning, } from "./review-session-replay.js";
+export { checkEditedValueForItem, editedValueFromEditorText, type EditedValueCheck, } from "./edited-value.js";
 export { assertReviewDecisionModeAllows, DecisionModeViolationError, validateReviewDecisionMode, type ReviewDecisionModeIssue, type ReviewDecisionModeIssueCode, type ReviewDecisionModeResult, } from "./producer-decision-mode.js";
 export declare function buildReviewDecision(state: ReviewWorkbenchState): ReviewDecision | undefined;
 export interface ReviewWorkbenchSessionExport {
@@ -34,6 +35,8 @@ export interface DeriveReviewSessionApplyResultForSnapshotOptions {
 export type DeriveReviewSessionApplyResultForSnapshotResult = {
     readonly ok: true;
     readonly issues: readonly [];
+    /** Non-fatal replay notes, e.g. a legacy text edit converted to its typed value. */
+    readonly warnings?: readonly ReviewSessionReplayWarning[];
     readonly unresolvedItemNames: readonly string[];
     readonly replayedSession: ReviewQueueSessionState;
     readonly sessionExport: ReviewWorkbenchSessionExport;
@@ -42,6 +45,7 @@ export type DeriveReviewSessionApplyResultForSnapshotResult = {
 } | {
     readonly ok: false;
     readonly issues: readonly ReviewSessionApplyIssue[];
+    readonly warnings?: readonly ReviewSessionReplayWarning[];
     readonly unresolvedItemNames: readonly string[];
     readonly replayedSession?: ReviewQueueSessionState;
     readonly sessionExport?: ReviewWorkbenchSessionExport;
@@ -207,8 +211,8 @@ export declare function buildReviewQueueWindow(session: ReviewQueueSessionState,
  * error message when the value violates the declared type/enum constraint, or
  * `undefined` when it is acceptable — including when there is no descriptor or
  * the type carries no single-line constraint (string/array/object). This is a
- * FORMAT check only: it never coerces or rewrites the value (the workbench
- * stores the reviewer's string edit unchanged, as it did before typed editors).
+ * FORMAT check on the editor text; on accept the workbench stores the text
+ * converted to the descriptor's JSON type (`editedValueFromEditorText`).
  */
 export declare function validateProposedValue(descriptor: ReviewValueDescriptor | undefined, rawValue: string): string | undefined;
 export declare function mountReviewWorkbench(root: HTMLElement, startState?: ReviewQueueSessionState | ReviewWorkbenchState, options?: MountReviewWorkbenchOptions): void;

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

@@ -1,12 +1,13 @@
 import { canonicalJson } from "./canonical.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
 import { candidateForDecision, keepActionDecision, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewWorkbenchState, defaultReviewSessionName, effectiveValueForDecision, initialReviewQueueSessionState, replayReviewSessionEvents, reviewWorkbenchSessionStorageKey, workbenchDecisionDefinitions, } from "./review-queue-session.js";
-import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+import { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
 import { findSoleCandidateById, reviewResourceApiVersion, } from "../review-resource.js";
 import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review-authorizing.js";
 import { 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";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./queue-binding.js";
@@ -14,7 +15,8 @@ export { buildExtractionInspectorModel, exportExtractionInspector, filterExtract
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
-export { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+export { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+export { checkEditedValueForItem, editedValueFromEditorText, } from "./edited-value.js";
 export { assertReviewDecisionModeAllows, DecisionModeViolationError, validateReviewDecisionMode, } from "./producer-decision-mode.js";
 export function buildReviewDecision(state) {
     if (!state.decision) {
@@ -332,6 +334,7 @@ export function deriveReviewSessionApplyResultForSnapshot(options) {
             results: [],
         };
     }
+    const warnings = reviewSessionReplayWarningsForSnapshot(options.snapshot, options.events);
     const replayedSession = replayReviewSessionEvents(options.snapshot, options.events);
     const sessionExport = buildReviewWorkbenchSessionExport(replayedSession, options.events);
     const resolvedItemNames = new Set(sessionExport.results.map((result) => result.reviewItemName));
@@ -356,6 +359,7 @@ export function deriveReviewSessionApplyResultForSnapshot(options) {
         return {
             ok: false,
             issues,
+            warnings,
             unresolvedItemNames,
             replayedSession,
             sessionExport,
@@ -366,6 +370,7 @@ export function deriveReviewSessionApplyResultForSnapshot(options) {
     return {
         ok: true,
         issues: [],
+        warnings,
         unresolvedItemNames,
         replayedSession,
         sessionExport,
@@ -804,8 +809,8 @@ function toDateInputValue(text) {
  * error message when the value violates the declared type/enum constraint, or
  * `undefined` when it is acceptable — including when there is no descriptor or
  * the type carries no single-line constraint (string/array/object). This is a
- * FORMAT check only: it never coerces or rewrites the value (the workbench
- * stores the reviewer's string edit unchanged, as it did before typed editors).
+ * FORMAT check on the editor text; on accept the workbench stores the text
+ * converted to the descriptor's JSON type (`editedValueFromEditorText`).
  */
 export function validateProposedValue(descriptor, rawValue) {
     if (!descriptor)
@@ -815,7 +820,9 @@ export function validateProposedValue(descriptor, rawValue) {
         case "number":
             if (value === "")
                 return "Enter a number.";
-            return Number.isFinite(Number(value)) ? undefined : `"${rawValue}" is not a number.`;
+            return parsePlainDecimal(value) !== undefined
+                ? undefined
+                : `"${rawValue}" is not a number (use plain decimal digits: any safe integer, or a fraction of at most 15 significant digits).`;
         case "boolean":
             if (value === "")
                 return "Choose true or false.";
@@ -823,7 +830,7 @@ export function validateProposedValue(descriptor, rawValue) {
         case "date":
             if (value === "")
                 return "Enter a date.";
-            return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value))
+            return isIsoCalendarDate(value)
                 ? undefined
                 : `"${rawValue}" is not a valid date (YYYY-MM-DD).`;
         case "enum": {
@@ -1210,7 +1217,12 @@ function createReviewWorkbenchController(root, startState, options) {
         const originalText = proposed ? formatValue(proposed.value) : undefined;
         const nextEditedValuesByItemName = { ...session.editedValuesByItemName };
         if (decision === "accept-proposed" && rawEditedValue !== undefined && rawEditedValue !== originalText) {
-            nextEditedValuesByItemName[itemName] = rawEditedValue;
+            // Store the edit as the descriptor's JSON type (a number field's "42" is
+            // 42), so the decision event and effectiveValue carry a typed value the
+            // server apply boundary accepts (kontourai/survey#278). Text that does not
+            // parse is kept as typed; the apply boundary refuses it.
+            const typedValue = editedValueFromEditorText(item?.spec.valueDescriptor, rawEditedValue);
+            nextEditedValuesByItemName[itemName] = typedValue === undefined ? rawEditedValue : typedValue;
         }
         else {
             delete nextEditedValuesByItemName[itemName];

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

@@ -1,6 +1,6 @@
 import { type DeriveReviewSessionApplyResultForSnapshotResult, type MapReviewWorkbenchResultsToApplyActionsOptions, type ReviewApplyActionIssue, type ReviewApplyActionMapping, type ReviewSessionApplyIssue, type ReviewSessionApplyResolutionRequirement, type ReviewWorkbenchResult } from "./review-workbench.js";
 import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
-import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
+import { type ReviewSessionReplayIssue, type ReviewSessionReplayWarning } from "./review-session-replay.js";
 import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueBinding } from "./queue-binding.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
@@ -128,6 +128,8 @@ export type ApplyReviewSessionIssue = ReviewSessionApplyIssue | {
 export type ApplyReviewSessionResult<TAction = never> = {
     readonly ok: true;
     readonly issues: readonly [];
+    /** Non-fatal replay notes, e.g. a legacy text edit converted to its typed value. */
+    readonly warnings?: readonly ReviewSessionReplayWarning[];
     readonly decisions: readonly ReviewDecision[];
     readonly results: readonly ReviewWorkbenchResult[];
     readonly actions: readonly ReviewApplyActionMapping<TAction>[];

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

@@ -225,6 +225,7 @@ export function applyReviewSession(options) {
     return {
         ok: true,
         issues: [],
+        warnings: derived.warnings ?? [],
         decisions: derived.decisions,
         results: derived.results,
         actions,

package/dist/src/reviewed-candidate-resolution.js

@@ -1,4 +1,5 @@
 import { candidateReviewRecord } from "./builder.js";
+import { ReviewAgreementError } from "./to-surface.js";
 export function reviewedCandidateResolution(input) {
     return candidateReviewRecord({
         id: input.id,
@@ -11,13 +12,12 @@ export function reviewedCandidateResolution(input) {
             ...input.reviewOutcome,
             candidateId: input.reviewOutcome.candidateId ?? input.selectedCandidateId,
         },
-        observations: input.observations.map((observation) => ({
-            ...observation,
-            claim: {
-                ...observation.claim,
-                status: observation.claim.status ?? claimStatusForObservation(input, observation),
-            },
-        })),
+        observations: input.observations.map((observation) => {
+            const status = observation.claim.status ?? claimStatusForObservation(input, observation);
+            if (observationCandidateId(observation) === input.selectedCandidateId)
+                assertSelectedStatusAgrees(input, status);
+            return { ...observation, claim: { ...observation.claim, status } };
+        }),
     });
 }
 function claimStatusForObservation(input, observation) {
@@ -26,6 +26,12 @@ function claimStatusForObservation(input, observation) {
     }
     return input.unselectedClaimStatus ?? "superseded";
 }
+/** A trusted selected claim must carry the status its review decided. */
+function assertSelectedStatusAgrees(input, status) {
+    if ((status === "verified" || status === "assumed") && status !== input.reviewOutcome.status) {
+        throw new ReviewAgreementError("status-mismatch", `Candidate set ${input.id} selected claim status ${status} disagrees with review outcome status ${input.reviewOutcome.status}`);
+    }
+}
 function observationCandidateId(observation) {
     return observation.candidate?.id ?? `${observation.id}.candidate`;
 }

package/dist/src/schema-mapping.d.ts

@@ -21,6 +21,7 @@
  *      capping.
  */
 import type { TrustBundle } from "@kontourai/surface";
+import type { AutoAcceptWarning } from "./producer-profile.js";
 import type { Candidate, CandidateSet, ReviewOutcome, SurveyInput } from "./types.js";
 /**
  * A stable reference to one field within one system's schema.
@@ -109,6 +110,10 @@ export interface SchemaMappingOptions {
      * If set, proposals at or above this confidence threshold are auto-accepted
      * as "assumed" (mirrors applyAutoAcceptPolicy in inquiry-mapping).
      * Conflicting proposals are never auto-accepted.
+     *
+     * Experimental: the gate trusts the proposer's self-reported confidence.
+     * Must be a finite number in (0, 1] (otherwise `RangeError`); a proposal
+     * whose confidence is not a finite number in [0, 1] is never auto-accepted.
      */
     autoAcceptMinConfidence?: number;
     /** ISO 8601 timestamp; defaults to new Date().toISOString(). */
@@ -116,6 +121,18 @@ export interface SchemaMappingOptions {
     /** Identifies the Survey producer run. */
     source?: string;
 }
+/**
+ * The schema-mapping profile's own payload, carried verbatim under the core's
+ * canonical `Candidate.metadata` key (see `./producer-profile.js`). Covers
+ * every field read across `mappingReviewToSurface`'s read-back sites and
+ * written at Candidate-projection time below.
+ */
+/**
+ * The value a schema-mapping candidate and its claim carry: the whole mapping,
+ * source field included, so a reviewed claim's value is exactly the reviewed
+ * candidate value.
+ */
+export type SchemaMappingValue = Pick<MappingProposalRecord, "relation" | "sourceField" | "targetField" | "conversion">;
 /**
  * Run the extractor against the provided system schemas and project the
  * resulting proposals into the standard Survey chain:
@@ -142,6 +159,12 @@ export declare function surveySchemaMapping(context: {
     surveyInput: SurveyInput;
     proposals: MappingProposalRecord[];
     candidateSets: CandidateSet[];
+    /**
+     * Proposals the auto-accept policy refused because their confidence is not
+     * a finite number in [0, 1]. Present only when non-empty; those proposals
+     * stay in human review.
+     */
+    autoAcceptWarnings?: AutoAcceptWarning[];
 }>;
 /**
  * A reviewed (accepted or rejected) mapping record: the CandidateSet, the

package/dist/src/schema-mapping.js

@@ -20,7 +20,7 @@
  *      so that resolveInquiry can resolve across systems with weakest-link
  *      capping.
  */
-import { evaluateAutoAccept, getProducerProposal, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { assertValidAutoAcceptThreshold, evaluateAutoAccept, getProducerProposal, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { buildSurveyTrustBundle } from "./to-surface.js";
 // ---------------------------------------------------------------------------
 // Canonical pair key
@@ -35,6 +35,14 @@ function fieldPairKey(a, b) {
 function mappingSubjectId(a, b) {
     return fieldPairKey(a, b);
 }
+function mappingValue(proposal) {
+    return {
+        relation: proposal.relation,
+        sourceField: proposal.sourceField,
+        targetField: proposal.targetField,
+        conversion: proposal.conversion,
+    };
+}
 // ---------------------------------------------------------------------------
 // surveySchemaMapping
 // ---------------------------------------------------------------------------
@@ -56,9 +64,12 @@ function mappingSubjectId(a, b) {
  * storage) or for mappingReviewToSurface after human review.
  */
 export async function surveySchemaMapping(context, extractor, options = {}) {
+    if (options.autoAcceptMinConfidence !== undefined)
+        assertValidAutoAcceptThreshold(options.autoAcceptMinConfidence);
     const generatedAt = options.generatedAt ?? new Date().toISOString();
     const source = options.source ?? `schema-mapping:${extractor.name}`;
     const proposals = await Promise.resolve(extractor.extract(context));
+    const autoAcceptWarnings = [];
     // One RawSource per system schema
     const rawSources = context.systems.map((s) => ({
         id: `schema-mapping.source.${s.system}`,
@@ -93,11 +104,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 id: extractionId,
                 sourceId: rawSource.id,
                 target: `${proposal.sourceField.entity}.${proposal.sourceField.field}:maps-to:${proposal.targetField.entity}.${proposal.targetField.field}`,
-                value: {
-                    relation: proposal.relation,
-                    targetField: proposal.targetField,
-                    conversion: proposal.conversion,
-                },
+                value: mappingValue(proposal),
                 confidence: proposal.confidence,
                 locator: proposal.sourceField.locator ?? `structured-field:${proposal.sourceField.entity}.${proposal.sourceField.field}`,
                 excerpt: proposal.evidence.map((e) => `[${e.system}] ${e.excerpt}`).join(" | "),
@@ -120,11 +127,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
             return {
                 candidateId: `schema-mapping.candidate.${proposal.id}`,
                 extractionId,
-                value: {
-                    relation: proposal.relation,
-                    targetField: proposal.targetField,
-                    conversion: proposal.conversion,
-                },
+                value: mappingValue(proposal),
                 confidence: proposal.confidence,
                 equivalenceKey: proposal.relation,
                 metadata: {
@@ -179,6 +182,13 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 rationale: selectedProposal?.rationale,
                 proposedAt: selectedProposal?.proposedAt,
             }, hasConflict, { minConfidence: options.autoAcceptMinConfidence }, generatedAt);
+            if (decision.warning) {
+                autoAcceptWarnings.push({
+                    code: decision.warning,
+                    proposalId: selectedProposal?.proposalId ?? selectedCandidate.id,
+                    confidence: decision.confidence,
+                });
+            }
             if (decision.accepted) {
                 const reviewId = `schema-mapping.review.${pairKey}`;
                 reviewOutcomes.push({
@@ -208,12 +218,8 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 facet: "schema-mapping.profile",
                 claimType: "schema-mapping.field-link",
                 fieldOrBehavior: "maps-to",
-                value: {
-                    relation: first.relation,
-                    sourceField: first.sourceField,
-                    targetField: first.targetField,
-                    conversion: first.conversion,
-                },
+                // No value override: the claim carries the selected candidate's value,
+                // which is the whole mapping a reviewer (or auto-accept) decided on.
                 ...(claimStatus ? { status: claimStatus } : {}),
                 impactLevel: "medium",
                 collectedBy: extractor.name,
@@ -241,7 +247,12 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
         reviewOutcomes,
         claims,
     };
-    return { surveyInput, proposals, candidateSets };
+    return {
+        surveyInput,
+        proposals,
+        candidateSets,
+        ...(autoAcceptWarnings.length > 0 ? { autoAcceptWarnings } : {}),
+    };
 }
 // ---------------------------------------------------------------------------
 // mappingReviewToSurface
@@ -315,7 +326,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
             id: extractionId,
             sourceId: rawSourceId,
             target: `${sourceField.entity}.${sourceField.field}:maps-to:${targetField.entity}.${targetField.field}`,
-            value: { relation, targetField, conversion },
+            value: { relation, sourceField, targetField, conversion },
             confidence,
             locator: sourceField.locator ?? `structured-field:${sourceField.entity}.${sourceField.field}`,
             excerpt: evidence.map((e) => `[${e.system}] ${e.excerpt}`).join(" | "),
@@ -352,7 +363,6 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
             facet: "schema-mapping.profile",
             claimType: "schema-mapping.field-link",
             fieldOrBehavior: "maps-to",
-            value: { relation, sourceField, targetField, conversion },
             status: rm.reviewOutcome.status,
             impactLevel: "medium",
             collectedBy: proposedBy,

package/dist/src/to-surface.d.ts

@@ -2,6 +2,14 @@ import type { TrustBundle } from "@kontourai/surface";
 import { type CalibrationMetrics } from "./calibration.js";
 import type { SurveyInput } from "./types.js";
 export interface SurveyCalibrationOptions {
+    /**
+     * EXPERIMENTAL opt-in, required for any `conclusionConfidence.value` to be
+     * set (#279). The value is the affirmation rate of the claim's whole
+     * extractor/field GROUP — a base rate every affirmed claim in the group
+     * shares — not a per-claim probability. Without this flag the `calibration`
+     * option sets no value.
+     */
+    experimentalConclusionValue?: boolean;
     /**
      * Precomputed calibration to source the value from — typically derived over a
      * LONGER history than the current batch (a better-grounded curve, and it avoids
@@ -30,16 +38,32 @@ export interface BuildSurveyTrustBundleOptions {
      */
     projectionContextId?: string;
     /**
-     * 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).
+     * EXPERIMENTAL. Populate `conclusionConfidence.value` from empirical review
+     * calibration — the affirmation rate of the claim's extractor/field group
+     * (a group base rate, not a per-claim probability; see #114/#137/#279).
+     * A value is set ONLY with `{ experimentalConclusionValue: true }`; `true` or
+     * an object without that flag sets no value. The object may also supply
+     * precomputed `metrics` and/or a `minSamples` floor. Absent → `value` stays
+     * unset and only the comfort-zone signal is carried.
      *
      * ADVISORY (ADR 0003 §4): this only enriches the emitted conclusion confidence;
      * it never changes a claim's `status`.
      */
     calibration?: boolean | SurveyCalibrationOptions;
 }
+/**
+ * Thrown when a claim's trusted status or value does not agree with the review
+ * outcome it cites, or when the governing review cannot be chosen.
+ * - `status-mismatch`: a `verified`/`assumed` claim cites a review whose status differs.
+ * - `value-mismatch`: a `verified`/`assumed` claim carries a value other than the reviewed value.
+ * - `ambiguous-review-order`: several reviews apply to one candidate and the latest
+ *   cannot be determined from `reviewedAt` (missing, unparseable, or tied).
+ */
+export declare class ReviewAgreementError extends Error {
+    readonly name = "ReviewAgreementError";
+    readonly code: "status-mismatch" | "value-mismatch" | "ambiguous-review-order";
+    constructor(code: ReviewAgreementError["code"], message: string);
+}
 export declare function buildSurveyTrustBundle(input: SurveyInput, options?: BuildSurveyTrustBundleOptions): TrustBundle;
+/** Test-only: re-arm the once-per-process calibration opt-in warning. Not exported from the package index. */
+export declare function resetCalibrationOptInWarningForTests(): void;