@kontourai/survey 1.5.0 → 1.6.0

package/dist/src/inquiry-mapping.js

@@ -18,7 +18,7 @@
  * and lives in the flow-agents repo.
  */
 import { resolveInquiry } from "@kontourai/surface";
-import { AUTO_ACCEPT_ACTOR, AUTO_ACCEPT_WITHIN_COMFORT_ZONE, getProducerProposal, hasCandidateConflict, meetsAutoAcceptThreshold, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { evaluateAutoAccept, getProducerProposal, hasCandidateConflict, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { reviewResourceApiVersion } from "./review-resource.js";
 // ---------------------------------------------------------------------------
 // Question normalization
@@ -152,20 +152,25 @@ export function applyAutoAcceptPolicy(proposals, policy) {
     // If proposals disagree, none can be auto-accepted
     if (hasCandidateConflict(proposals.map((p) => ({ equivalenceKey: mappingEquivalenceKey(p) }))))
         return [];
-    return proposals
-        .filter((p) => meetsAutoAcceptThreshold(p.confidence, policy.minConfidence))
-        .map((proposal) => ({
-        id: `inquiry-mapping.auto.${normalizeQuestion(proposal.question)}`,
-        normalizedQuestion: normalizeQuestion(proposal.question),
-        target: proposal.proposedTarget,
-        ruleId: proposal.proposedRuleId,
-        status: "assumed",
-        reviewedBy: AUTO_ACCEPT_ACTOR,
-        reviewedAt: proposal.proposedAt,
-        rationale: `Auto-accepted: confidence ${proposal.confidence} >= threshold ${policy.minConfidence}. ${proposal.rationale}`,
-        withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
-        proposalId: proposal.id,
-    }));
+    return proposals.flatMap((proposal) => {
+        const decision = evaluateAutoAccept({ confidence: proposal.confidence, rationale: proposal.rationale, proposedAt: proposal.proposedAt }, false, policy, proposal.proposedAt);
+        if (!decision.accepted)
+            return [];
+        return [
+            {
+                id: `inquiry-mapping.auto.${normalizeQuestion(proposal.question)}`,
+                normalizedQuestion: normalizeQuestion(proposal.question),
+                target: proposal.proposedTarget,
+                ruleId: proposal.proposedRuleId,
+                status: "assumed",
+                reviewedBy: decision.actor,
+                reviewedAt: decision.reviewedAt,
+                rationale: decision.rationale,
+                withinComfortZone: decision.withinComfortZone,
+                proposalId: proposal.id,
+            },
+        ];
+    });
 }
 // ---------------------------------------------------------------------------
 // Mapping lookup

package/dist/src/producer-profile.d.ts

@@ -117,18 +117,88 @@ export declare const AUTO_ACCEPT_WITHIN_COMFORT_ZONE: true;
 /**
  * The one auto-accept threshold rule every Producer Profile applies: a
  * confidence value clears an auto-accept policy iff it is at or above
- * (inclusive) the policy's minimum confidence. This is the only piece of
- * auto-accept *mechanics* that is identical across profiles today — each
- * profile decides its own iteration granularity (per-proposal filter vs.
- * per-group max-confidence gate) and output record shape around this call;
- * the core does not decide that.
+ * (inclusive) the policy's minimum confidence.
  *
- * These three exports are the ONLY auto-accept semantics the two profiles
- * genuinely share today (see the Slice 3 plan's Part (a) field-by-field
- * diff table). Everything else about auto-accept — iteration granularity
- * (per-proposal vs. per-group), output record type and cardinality, id
- * templates, timestamp source, and rationale string format — diverges
- * between profiles and stays entirely per-profile; this module does not
- * decide any of it.
+ * This is a low-level primitive used by {@link evaluateAutoAccept} below,
+ * which is now the single place that decides the gate/rationale/`reviewedAt`
+ * auto-accept policy for both profiles (see
+ * `docs/decisions/producer-profile.md`, "Auto-accept policy unification").
+ * What still stays entirely per-profile: output record shapes (e.g.
+ * `InquiryMapping` vs. schema-mapping's inline `ReviewOutcome`), id
+ * templates, and each profile's own selection/iteration algorithm for which
+ * candidate's evidence gets passed into that decision.
  */
 export declare function meetsAutoAcceptThreshold(confidence: number, minConfidence: number): boolean;
+/**
+ * The accepted-candidate-shaped evidence `evaluateAutoAccept` decides over.
+ * Deliberately narrow: only the fields the auto-accept policy itself reads,
+ * not a whole proposal/candidate shape, so any profile can adapt its own
+ * proposal type into this without a dependency the other direction.
+ */
+export interface AutoAcceptEvidence {
+    /**
+     * The accepted evidence's OWN confidence — this is what gates AND what the
+     * composed rationale cites (owner-accepted decisions 1 and 2 in
+     * `docs/decisions/producer-profile.md`; fixes schema-mapping's pre-Slice-3
+     * group-max-gate / selected-candidate-confidence-rationale mismatch).
+     */
+    confidence: number;
+    /**
+     * The evidence's own rationale, appended to the composed rationale when
+     * present (decision 2; mirrors inquiry-mapping's pre-existing behavior).
+     * Presence is decided with `!== undefined`, not truthiness, so an
+     * empty-string rationale is still appended.
+     */
+    rationale?: string;
+    /**
+     * ISO 8601 timestamp of when this specific evidence was proposed (decision
+     * 3). When absent, `evaluateAutoAccept` falls back to `fallbackTimestamp`
+     * and reports that in `reviewedAtSource`.
+     */
+    proposedAt?: string;
+}
+/** The auto-accept policy `evaluateAutoAccept` gates against. */
+export interface AutoAcceptPolicy {
+    /** Minimum confidence (inclusive) a proposal must clear to auto-accept. */
+    minConfidence: number;
+}
+/** The unified auto-accept decision `evaluateAutoAccept` returns. */
+export interface AutoAcceptDecision {
+    /** `true` iff there is no conflict and `evidence.confidence` clears `policy.minConfidence`. */
+    accepted: boolean;
+    /** The confidence value that was gated on (== `evidence.confidence`). */
+    confidence: number;
+    /** Composed rationale — always computed; callers only use it when `accepted`. */
+    rationale: string;
+    /** The resolved review timestamp — `evidence.proposedAt` when present, `fallbackTimestamp` otherwise. */
+    reviewedAt: string;
+    /** Which source `reviewedAt` came from. */
+    reviewedAtSource: "proposedAt" | "fallback";
+    /** Always `AUTO_ACCEPT_ACTOR`. */
+    actor: typeof AUTO_ACCEPT_ACTOR;
+    /** Always `AUTO_ACCEPT_WITHIN_COMFORT_ZONE`. */
+    withinComfortZone: typeof AUTO_ACCEPT_WITHIN_COMFORT_ZONE;
+}
+/**
+ * The one core auto-accept policy decision every Producer Profile delegates
+ * to, per the owner-accepted semantics recorded in
+ * `docs/decisions/producer-profile.md` ("Auto-accept policy unification"):
+ *
+ * 1. Gate on the accepted evidence's OWN confidence (not a group's), via
+ *    {@link meetsAutoAcceptThreshold} — and never accept when `hasConflict`.
+ * 2. Compose a rationale citing that same gate-clearing confidence, and
+ *    append `evidence.rationale` when present (`!== undefined`).
+ * 3. Stamp `reviewedAt` from `evidence.proposedAt` when present, falling
+ *    back to `fallbackTimestamp` (and reporting which source was used via
+ *    `reviewedAtSource`) when a profile's evidence carries no timestamp of
+ *    its own.
+ * 4. Always report `actor: AUTO_ACCEPT_ACTOR` and
+ *    `withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE` (ADR 0003 §4:
+ *    auto-accept only ever yields "assumed" with the comfort-zone posture).
+ *
+ * This function decides the policy only — it never renders a review outcome
+ * or claim-status record itself (ADR 0003 §4). Each profile still renders
+ * its own distinct record shape (`InquiryMapping` vs. schema-mapping's
+ * inline `ReviewOutcome`) from this decision's fields.
+ */
+export declare function evaluateAutoAccept(evidence: AutoAcceptEvidence, hasConflict: boolean, policy: AutoAcceptPolicy, fallbackTimestamp: string): AutoAcceptDecision;

package/dist/src/producer-profile.js

@@ -105,20 +105,54 @@ export const AUTO_ACCEPT_WITHIN_COMFORT_ZONE = true;
 /**
  * The one auto-accept threshold rule every Producer Profile applies: a
  * confidence value clears an auto-accept policy iff it is at or above
- * (inclusive) the policy's minimum confidence. This is the only piece of
- * auto-accept *mechanics* that is identical across profiles today — each
- * profile decides its own iteration granularity (per-proposal filter vs.
- * per-group max-confidence gate) and output record shape around this call;
- * the core does not decide that.
+ * (inclusive) the policy's minimum confidence.
  *
- * These three exports are the ONLY auto-accept semantics the two profiles
- * genuinely share today (see the Slice 3 plan's Part (a) field-by-field
- * diff table). Everything else about auto-accept — iteration granularity
- * (per-proposal vs. per-group), output record type and cardinality, id
- * templates, timestamp source, and rationale string format — diverges
- * between profiles and stays entirely per-profile; this module does not
- * decide any of it.
+ * This is a low-level primitive used by {@link evaluateAutoAccept} below,
+ * which is now the single place that decides the gate/rationale/`reviewedAt`
+ * auto-accept policy for both profiles (see
+ * `docs/decisions/producer-profile.md`, "Auto-accept policy unification").
+ * What still stays entirely per-profile: output record shapes (e.g.
+ * `InquiryMapping` vs. schema-mapping's inline `ReviewOutcome`), id
+ * templates, and each profile's own selection/iteration algorithm for which
+ * candidate's evidence gets passed into that decision.
  */
 export function meetsAutoAcceptThreshold(confidence, minConfidence) {
     return confidence >= minConfidence;
 }
+/**
+ * The one core auto-accept policy decision every Producer Profile delegates
+ * to, per the owner-accepted semantics recorded in
+ * `docs/decisions/producer-profile.md` ("Auto-accept policy unification"):
+ *
+ * 1. Gate on the accepted evidence's OWN confidence (not a group's), via
+ *    {@link meetsAutoAcceptThreshold} — and never accept when `hasConflict`.
+ * 2. Compose a rationale citing that same gate-clearing confidence, and
+ *    append `evidence.rationale` when present (`!== undefined`).
+ * 3. Stamp `reviewedAt` from `evidence.proposedAt` when present, falling
+ *    back to `fallbackTimestamp` (and reporting which source was used via
+ *    `reviewedAtSource`) when a profile's evidence carries no timestamp of
+ *    its own.
+ * 4. Always report `actor: AUTO_ACCEPT_ACTOR` and
+ *    `withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE` (ADR 0003 §4:
+ *    auto-accept only ever yields "assumed" with the comfort-zone posture).
+ *
+ * This function decides the policy only — it never renders a review outcome
+ * or claim-status record itself (ADR 0003 §4). Each profile still renders
+ * its own distinct record shape (`InquiryMapping` vs. schema-mapping's
+ * inline `ReviewOutcome`) from this decision's fields.
+ */
+export function evaluateAutoAccept(evidence, hasConflict, policy, fallbackTimestamp) {
+    const accepted = !hasConflict && meetsAutoAcceptThreshold(evidence.confidence, policy.minConfidence);
+    const rationale = `Auto-accepted: confidence ${evidence.confidence} >= threshold ${policy.minConfidence}.` +
+        (evidence.rationale !== undefined ? ` ${evidence.rationale}` : "");
+    const reviewedAt = evidence.proposedAt ?? fallbackTimestamp;
+    return {
+        accepted,
+        confidence: evidence.confidence,
+        rationale,
+        reviewedAt,
+        reviewedAtSource: evidence.proposedAt !== undefined ? "proposedAt" : "fallback",
+        actor: AUTO_ACCEPT_ACTOR,
+        withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
+    };
+}

package/dist/src/schema-mapping.js

@@ -20,7 +20,7 @@
  *      so that resolveInquiry can resolve across systems with weakest-link
  *      capping.
  */
-import { AUTO_ACCEPT_ACTOR, AUTO_ACCEPT_WITHIN_COMFORT_ZONE, getProducerProposal, meetsAutoAcceptThreshold, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { evaluateAutoAccept, getProducerProposal, projectProposalsToCandidateSet, } from "./producer-profile.js";
 import { buildSurveyTrustBundle } from "./to-surface.js";
 // ---------------------------------------------------------------------------
 // Canonical pair key
@@ -156,29 +156,42 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
         });
         candidateSet.selectedCandidateId = candidateSet.status !== "conflict" ? candidates[0]?.id : undefined;
         candidateSets.push(candidateSet);
-        // Auto-accept policy: non-conflicting proposals above threshold → assumed
-        let autoReviewStatus;
-        if (candidateSet.status !== "conflict" && options.autoAcceptMinConfidence !== undefined) {
-            const topConfidence = Math.max(...pairProposals.map((p) => p.confidence));
-            if (meetsAutoAcceptThreshold(topConfidence, options.autoAcceptMinConfidence)) {
-                autoReviewStatus = "assumed";
-            }
-        }
+        // Auto-accept policy: delegate the gate/rationale/reviewedAt decision to
+        // the core (docs/decisions/producer-profile.md — gates on the SELECTED
+        // candidate's own confidence, not the group's; keeps the existing
+        // candidates[0]-based selection algorithm unchanged, out of scope here).
         const selectedCandidate = candidateSet.selectedCandidateId
             ? candidates.find((c) => c.id === candidateSet.selectedCandidateId)
             : candidates[0];
-        if (autoReviewStatus && selectedCandidate) {
-            const reviewId = `schema-mapping.review.${pairKey}`;
-            reviewOutcomes.push({
-                id: reviewId,
-                candidateSetId,
-                candidateId: selectedCandidate.id,
-                status: autoReviewStatus,
-                actor: AUTO_ACCEPT_ACTOR,
-                reviewedAt: generatedAt,
-                rationale: `Auto-accepted: confidence ${selectedCandidate.confidence} >= threshold ${options.autoAcceptMinConfidence}`,
-                withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
-            });
+        const hasConflict = candidateSet.status === "conflict";
+        if (!hasConflict && options.autoAcceptMinConfidence !== undefined && selectedCandidate) {
+            const selectedProposal = getProducerProposal(selectedCandidate);
+            const decision = evaluateAutoAccept({
+                // Fail-closed fallback: Candidate.confidence is `number | undefined`
+                // (src/types.ts), but no conforming SchemaMappingExtractor can
+                // produce an undefined confidence today (MappingProposalRecord.confidence
+                // is required and is copied straight through to Candidate.confidence
+                // at construction), so this is unreachable through the typed contract.
+                // NEGATIVE_INFINITY (not 0) guarantees rejection regardless of
+                // autoAcceptMinConfidence's sign, matching old code's NaN-poisoning
+                // behavior of never auto-accepting on a missing confidence.
+                confidence: selectedCandidate.confidence ?? Number.NEGATIVE_INFINITY,
+                rationale: selectedProposal?.rationale,
+                proposedAt: selectedProposal?.proposedAt,
+            }, hasConflict, { minConfidence: options.autoAcceptMinConfidence }, generatedAt);
+            if (decision.accepted) {
+                const reviewId = `schema-mapping.review.${pairKey}`;
+                reviewOutcomes.push({
+                    id: reviewId,
+                    candidateSetId,
+                    candidateId: selectedCandidate.id,
+                    status: "assumed",
+                    actor: decision.actor,
+                    reviewedAt: decision.reviewedAt,
+                    rationale: decision.rationale,
+                    withinComfortZone: decision.withinComfortZone,
+                });
+            }
         }
         // Project to ClaimTarget (subjectType "system-field", fieldOrBehavior "maps-to")
         if (selectedCandidate) {

package/package.json

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