@kontourai/survey 3.0.0 → 4.0.0

package/dist/src/to-surface.js

@@ -2,15 +2,34 @@ import { createHash } from "node:crypto";
 import { buildReviewProofAnchor } from "./review-proof.js";
 import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 import { deriveCalibration } from "./calibration.js";
+import { AUTO_ACCEPT_ACTOR } from "./producer-profile.js";
+import { canonicalJson } from "./review-workbench/canonical.js";
 /** Minimum labeled samples a calibration group needs before its empirical
  *  accuracy is emitted as a `conclusionConfidence.value`. */
 const DEFAULT_CALIBRATION_MIN_SAMPLES = 20;
+/**
+ * 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 class ReviewAgreementError extends Error {
+    name = "ReviewAgreementError";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
 export function buildSurveyTrustBundle(input, options = {}) {
     const projectionContextId = validateProjectionContextId(options.projectionContextId);
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
     const candidateSets = indexById(input.candidateSets, "candidate set");
     const reviewsByCandidateSet = groupBy(input.reviewOutcomes, (review) => review.candidateSetId);
+    // Only the explicit experimental opt-in produces a value (#279).
     const calibrationOptions = normalizeCalibrationOptions(options.calibration);
     const calibrationMetrics = calibrationOptions
         ? (calibrationOptions.metrics ?? deriveCalibration({
@@ -28,18 +47,19 @@ export function buildSurveyTrustBundle(input, options = {}) {
         const candidate = selectCandidate(candidateSet, projection.candidateId);
         const extraction = requireMapValue(extractions, candidate.extractionId, "extraction");
         const rawSource = requireMapValue(rawSources, extraction.sourceId, "raw source");
-        const review = selectReview(reviewsByCandidateSet.get(candidateSet.id) ?? [], candidate.id);
+        const review = selectReview(reviewsByCandidateSet.get(candidateSet.id) ?? [], candidate.id, projection.id);
         const projectionReview = review?.resolution === "could_not_confirm" ? undefined : review;
         const unreviewedStatus = statusFor({ candidateSet, candidate });
         const status = projection.status
             ?? (review?.resolution === "could_not_confirm"
                 ? (unreviewedStatus === "disputed" ? unreviewedStatus : review.status)
                 : statusFor({ candidateSet, candidate, review }));
-        assertProducerDiscipline({ status, review, candidateSet, extraction, rawSource, projection });
         const claimValue = projection.value ?? candidate.value;
+        assertProducerDiscipline({ status, review, candidateSet, candidate, extraction, rawSource, projection, claimValue });
         const createdAt = projection.createdAt ?? extraction.extractedAt;
         const updatedAt = projection.updatedAt ?? projectionReview?.reviewedAt ?? input.generatedAt;
         const evidenceId = projectionRecordId(projection.id, projectionContextId, "claim-evidence", "evidence.source");
+        const autoAccepted = projectionReview?.actor === AUTO_ACCEPT_ACTOR;
         const claim = {
             id: projection.id,
             subjectType: projection.subjectType,
@@ -57,8 +77,13 @@ export function buildSurveyTrustBundle(input, options = {}) {
             confidenceBasis: {
                 sourceQuality: "moderate",
                 extractionConfidence: candidate.confidence ?? extraction.confidence,
-                reviewerAuthority: status === "verified" || status === "assumed" ? "operator" : "none",
-                evidenceStrength: status === "verified" || status === "assumed" ? "moderate" : "weak",
+                // An auto-accept policy checked nothing but the proposer's own
+                // confidence, so its claims carry system authority and weak evidence;
+                // only a human review earns operator authority.
+                reviewerAuthority: status === "verified" || status === "assumed"
+                    ? (autoAccepted ? "system" : "operator")
+                    : "none",
+                evidenceStrength: (status === "verified" || status === "assumed") && !autoAccepted ? "moderate" : "weak",
                 impactLevel: projection.impactLevel,
                 ...projection.confidenceBasis,
             },
@@ -72,18 +97,21 @@ export function buildSurveyTrustBundle(input, options = {}) {
                     candidate,
                     review: projectionReview,
                     comfortZoneReview: review,
+                    valueEdit: (status === "verified" || status === "assumed") && review ? acceptedEdit(review) : undefined,
                 }),
             },
         };
-        // Promote the review's comfort-zone signal — and, when calibration is
-        // enabled, an empirically-calibrated conclusion probability — into the
+        // Promote the review's comfort-zone signal — and, under the experimental
+        // calibration opt-in, the group affirmation rate — into the
         // first-class conclusionConfidence field (Surface 2.9 / Hachure 0.14) so the
         // signal is portable and comparable, not buried in producer metadata.
         //
-        // comfortZone is CARRIED from the review. `value` is PRODUCED from empirical
-        // review calibration (#114/#137): the affirmation rate of this extractor's
-        // proposals at this confidence — a calibrated conclusion probability, distinct
-        // from the extraction-confidence ingredient in confidenceBasis.
+        // comfortZone is CARRIED from the review. `value` is PRODUCED, only under the
+        // experimental opt-in, from empirical review calibration (#114/#137/#279):
+        // the affirmation rate of this claim's extractor/field GROUP. It is a group
+        // base rate shared by every affirmed claim in the group, not a per-claim
+        // probability, and distinct from the extraction-confidence ingredient in
+        // confidenceBasis.
         //
         // A value is produced only for an AFFIRMED conclusion (status verified/assumed)
         // that clears the sample floor. conclusionConfidence.value is "probability the
@@ -235,7 +263,8 @@ function projectInterpretations(input) {
     }
 }
 function buildInterpretationProjection(input) {
-    const anchorSource = requirePolicyStandardAnchor(input.interpretation, input.rawSources);
+    assertInterpretationReadingShape(input.interpretation);
+    const anchorSource = requireInterpretationAnchor(input.interpretation, input.rawSources);
     const claim = resolveInterpretationClaim(input.interpretation, input.claims, input.input);
     if (!input.claimsById.has(claim.id)) {
         throw new Error(`Interpretation ${input.interpretation.id} resolved unknown claim ${claim.id}`);
@@ -260,6 +289,48 @@ function buildInterpretationProjection(input) {
         }),
     };
 }
+const INTERPRETATION_READING_KINDS = ["policy-standard", "gleaned", "answerImpact"];
+const INTERPRETATION_ANSWER_IMPACTS = ["supported", "narrowed", "accepted-risk"];
+/** Absent readingKind means the original policy-standard reading (pre-#259 records). */
+function interpretationReadingKind(interpretation) {
+    return interpretation.readingKind ?? "policy-standard";
+}
+/**
+ * Fail-closed shape validation for the reading dimension (#259). Records come
+ * from JSON as often as from typed callers, so unknown vocabulary throws
+ * instead of silently projecting under a label nothing derived.
+ */
+function assertInterpretationReadingShape(interpretation) {
+    if (interpretation.readingKind !== undefined && !INTERPRETATION_READING_KINDS.includes(interpretation.readingKind)) {
+        throw new Error(`Interpretation ${interpretation.id} has unknown readingKind ${String(interpretation.readingKind)}; expected one of ${INTERPRETATION_READING_KINDS.join(", ")}`);
+    }
+    const kind = interpretationReadingKind(interpretation);
+    if (kind === "answerImpact") {
+        if (interpretation.answerImpact === undefined) {
+            throw new Error(`Interpretation ${interpretation.id} readingKind answerImpact requires an answerImpact value`);
+        }
+        if (!INTERPRETATION_ANSWER_IMPACTS.includes(interpretation.answerImpact)) {
+            throw new Error(`Interpretation ${interpretation.id} has unknown answerImpact ${String(interpretation.answerImpact)}; expected one of ${INTERPRETATION_ANSWER_IMPACTS.join(", ")}`);
+        }
+        return;
+    }
+    if (interpretation.answerImpact !== undefined) {
+        throw new Error(`Interpretation ${interpretation.id} sets answerImpact but readingKind is ${kind}; answerImpact is only valid on answerImpact readings`);
+    }
+}
+/**
+ * Resolves an interpretation's anchor raw source. Every reading kind requires
+ * a KNOWN raw source (referential integrity per #16 R3); only the original
+ * policy-standard reading additionally requires the source kind to be
+ * `policy-standard`. The gleaned / answerImpact readings (#259) anchor to the
+ * result source the producer read, whatever its kind.
+ */
+function requireInterpretationAnchor(interpretation, rawSources) {
+    if (interpretationReadingKind(interpretation) === "policy-standard") {
+        return requirePolicyStandardAnchor(interpretation, rawSources);
+    }
+    return requireMapValue(rawSources, interpretation.anchorsToSourceId, "interpretation anchor raw source");
+}
 function requirePolicyStandardAnchor(interpretation, rawSources) {
     const anchorSource = requireMapValue(rawSources, interpretation.anchorsToSourceId, "interpretation anchor raw source");
     if (anchorSource.kind !== "policy-standard") {
@@ -268,14 +339,20 @@ function requirePolicyStandardAnchor(interpretation, rawSources) {
     return anchorSource;
 }
 function createInterpretationAnchorEvidence(input) {
+    const readingKind = interpretationReadingKind(input.interpretation);
     return {
         id: projectionRecordId(input.interpretation.id, input.projectionContextId, "interpretation-evidence", "evidence.anchor"),
         claimId: input.claim.id,
-        evidenceType: "policy_rule",
+        // The policy-standard reading keeps its exact prior projection; the new
+        // reading kinds (#259) derive the evidence type from the anchor source
+        // they actually read, via the same mapping extraction evidence uses.
+        evidenceType: readingKind === "policy-standard" ? "policy_rule" : evidenceTypeFor(input.anchorSource),
         method: "anchoring",
         sourceRef: input.anchorSource.sourceRef,
         sourceLocator: input.interpretation.ruleLocator,
-        excerptOrSummary: input.policyStandard?.inlineText ?? `Anchored policy-standard reading at ${input.interpretation.ruleLocator}.`,
+        excerptOrSummary: readingKind === "policy-standard"
+            ? input.policyStandard?.inlineText ?? `Anchored policy-standard reading at ${input.interpretation.ruleLocator}.`
+            : input.anchorSource.inlineText ?? `Anchored ${readingKind} reading at ${input.interpretation.ruleLocator}.`,
         observedAt: input.anchorSource.observedAt,
         collectedBy: input.interpretation.actor,
         integrityRef: input.anchorSource.checksum,
@@ -287,6 +364,10 @@ function createInterpretationAnchorEvidence(input) {
             locatorScheme: input.anchorSource.locatorScheme,
             anchorsToSourceId: input.anchorSource.id,
             ruleLocator: input.interpretation.ruleLocator,
+            // Only explicitly-set reading kinds project, so legacy batches stay
+            // byte-identical. Authored-judgment provenance markers, not machine facts.
+            ...(input.interpretation.readingKind ? { readingKind: input.interpretation.readingKind } : {}),
+            ...(input.interpretation.answerImpact ? { answerImpact: input.interpretation.answerImpact } : {}),
         },
     };
 }
@@ -319,6 +400,10 @@ function attachInterpretationClaimMetadata(input) {
                     reading: input.interpretation.reading,
                     actor: input.interpretation.actor,
                     recordedAt: input.interpretation.recordedAt,
+                    // Explicit reading dimension only (#259): legacy entries keep their
+                    // exact prior bytes; absent readingKind means policy-standard.
+                    ...(input.interpretation.readingKind ? { readingKind: input.interpretation.readingKind } : {}),
+                    ...(input.interpretation.answerImpact ? { answerImpact: input.interpretation.answerImpact } : {}),
                     ...(input.interpretation.metadata ? { metadata: input.interpretation.metadata } : {}),
                     edges: [
                         {
@@ -394,6 +479,11 @@ function buildSurveyMetadata(input) {
                 },
             }
             : {}),
+        // A trusted claim whose value is a reviewer's edit says so, and keeps the
+        // value the reviewer was shown.
+        ...(input.valueEdit
+            ? { valueEdit: { edited: true, originalValue: input.candidate.value, reviewOutcomeId: input.comfortZoneReview?.id } }
+            : {}),
         ...(input.comfortZoneReview?.withinComfortZone === false
             ? {
                 comfortZone: {
@@ -423,6 +513,17 @@ function assertProducerDiscipline(input) {
         review: input.review,
         candidateSetStatus: input.candidateSet.status,
     });
+    if ((input.status === "verified" || input.status === "assumed") && input.review) {
+        // A trusted claim may only restate its review: same status, and the value
+        // the reviewer saw (the candidate value, or the edit the review records).
+        if (input.review.status !== input.status) {
+            throw new ReviewAgreementError("status-mismatch", `Claim ${input.projection.id} status ${input.status} disagrees with review outcome ${input.review.id} status ${input.review.status}`);
+        }
+        const reviewedValue = reviewedValueFor(input.review, input.candidate);
+        if (canonicalJson(input.claimValue) !== canonicalJson(reviewedValue)) {
+            throw new ReviewAgreementError("value-mismatch", `Claim ${input.projection.id} is ${input.status} but its value differs from the value reviewed in ${input.review.id}`);
+        }
+    }
     if (input.rawSource.kind !== "manual-entry" && !input.extraction.locator) {
         throw new Error(`Claim ${input.projection.id} needs a source locator for ${input.rawSource.kind}`);
     }
@@ -435,15 +536,92 @@ function selectCandidate(candidateSet, candidateId) {
     }
     return candidate;
 }
-function selectReview(reviews, candidateId) {
-    return reviews.find((review) => review.candidateId === candidateId) ?? reviews.find((review) => !review.candidateId);
+/** An accepted edit the review records. `buildCanonicalReviewedTrustInput`
+ *  writes `metadata.editedValue` next to `metadata.workbenchDecision`; only an
+ *  edit on an `accept-proposed` decision replaces the reviewed value. Any other
+ *  `editedValue` (a bare one, or one on a reject or keep decision) is not an
+ *  accepted edit and is ignored. */
+function acceptedEdit(review) {
+    const metadata = review.metadata;
+    return metadata?.workbenchDecision === "accept-proposed" && Object.hasOwn(metadata, "editedValue")
+        ? { value: metadata.editedValue }
+        : undefined;
+}
+/** The value a review outcome attests: its accepted edit, else the candidate value that was reviewed. */
+function reviewedValueFor(review, candidate) {
+    const edit = acceptedEdit(review);
+    return edit ? edit.value : candidate.value;
+}
+/** The latest applicable review governs. Exact candidate bindings take
+ *  precedence over unbound (set-wide) reviews; within a tier, several reviews
+ *  are ordered by `reviewedAt`, and an order that cannot be established is
+ *  refused rather than guessed. */
+function selectReview(reviews, candidateId, claimId) {
+    const exact = reviews.filter((review) => review.candidateId === candidateId);
+    return latestReview(exact.length ? exact : reviews.filter((review) => !review.candidateId), claimId);
+}
+function latestReview(reviews, claimId) {
+    if (reviews.length <= 1)
+        return reviews[0];
+    const timed = reviews.map((review) => ({ review, at: review.reviewedAt ? Date.parse(review.reviewedAt) : Number.NaN }));
+    const untimed = timed.find((entry) => Number.isNaN(entry.at));
+    if (untimed) {
+        throw new ReviewAgreementError("ambiguous-review-order", `Claim ${claimId} has ${reviews.length} applicable review outcomes but ${untimed.review.id} has no parseable reviewedAt`);
+    }
+    const latestAt = Math.max(...timed.map((entry) => entry.at));
+    const latest = timed.filter((entry) => entry.at === latestAt).map((entry) => entry.review);
+    // Reviews at the same instant (however the timestamp is spelled) that record
+    // the same decision are one review recorded twice; conflicting ones are refused.
+    if (new Set(latest.map(reviewDecisionKey)).size > 1) {
+        throw new ReviewAgreementError("ambiguous-review-order", `Claim ${claimId} has conflicting review outcomes ${latest.map((review) => review.id).join(", ")} at the latest reviewedAt`);
+    }
+    return [...latest].sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))[0];
+}
+function reviewDecisionKey(review) {
+    const edit = acceptedEdit(review);
+    return canonicalJson({
+        candidateId: review.candidateId ?? null,
+        status: review.status,
+        resolution: review.resolution ?? null,
+        edit: edit ? { value: edit.value } : null,
+        // These reach the claim (comfort zone, testimony provenance), so reviews
+        // that differ in them are different decisions, not one recorded twice.
+        withinComfortZone: review.withinComfortZone ?? null,
+        comfortZoneNote: review.comfortZoneNote ?? null,
+        authorizing: review.authorizing ?? null,
+    });
 }
 function normalizeCalibrationOptions(calibration) {
     if (calibration === undefined || calibration === false)
         return undefined;
-    if (calibration === true)
-        return {};
-    return calibration;
+    if (calibration === true || calibration.experimentalConclusionValue === undefined) {
+        // Callers written before #279 asked for a value this way; tell them it is
+        // now ignored instead of silently dropping it. An explicit `false` is a
+        // deliberate opt-out and stays quiet.
+        warnCalibrationOptInMissingOnce();
+        return undefined;
+    }
+    return calibration.experimentalConclusionValue === true ? calibration : undefined;
+}
+let warnedCalibrationOptInMissing = false;
+/**
+ * Warn once per process, matching the `defineProductVocabulary` deprecation
+ * notice: `buildSurveyTrustBundle` has no diagnostics channel in its return
+ * value (it returns a TrustBundle), and a per-call warning would flood batch
+ * projections.
+ */
+function warnCalibrationOptInMissingOnce() {
+    if (warnedCalibrationOptInMissing)
+        return;
+    warnedCalibrationOptInMissing = true;
+    console.warn("[@kontourai/survey] buildSurveyTrustBundle: the `calibration` option no longer sets " +
+        "conclusionConfidence.value without `calibration: { experimentalConclusionValue: true }` (#279). " +
+        "The value is an experimental extractor/field group base rate, not a per-claim probability. " +
+        "Pass the flag to keep it, or `experimentalConclusionValue: false` / omit `calibration` to silence this warning.");
+}
+/** Test-only: re-arm the once-per-process calibration opt-in warning. Not exported from the package index. */
+export function resetCalibrationOptInWarningForTests() {
+    warnedCalibrationOptInMissing = false;
 }
 /**
  * Looks up the empirical affirmation rate for an extractor/field, preferring the

package/dist/src/types.d.ts

@@ -104,11 +104,50 @@ export interface EscalationRecord {
     resolvedBy?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * The reading dimension of an {@link Interpretation} (#259, generalizing #16):
+ *
+ * - `"policy-standard"` — the original reading of how a policy-standard
+ *   paragraph applies to the claim. This kind keeps the hard requirement that
+ *   the anchor raw source is `kind: "policy-standard"`.
+ * - `"gleaned"` — what this result taught: an authored reading of what the
+ *   anchored source material showed for the claim.
+ * - `"answerImpact"` — how the reading moved the inquiry answer the claim
+ *   feeds (see {@link InterpretationAnswerImpact}); requires `answerImpact`.
+ *
+ * Additive-optional: a record with no `readingKind` is a `"policy-standard"`
+ * reading, so existing batches keep their exact prior validation and
+ * projection behavior. Interpretations never enter canonical review-proof
+ * bytes regardless of kind.
+ */
+export type InterpretationReadingKind = "policy-standard" | "gleaned" | "answerImpact";
+/**
+ * How an `"answerImpact"` reading moved the inquiry answer its claim feeds:
+ * the result `supported` the answer, `narrowed` it, or was recorded as an
+ * `accepted-risk`. "Answer" means the inquiry answer (inquiry-mapping);
+ * downstream decisions stay with consumers.
+ */
+export type InterpretationAnswerImpact = "supported" | "narrowed" | "accepted-risk";
 export interface Interpretation {
     id: string;
     appliesToTarget?: string;
     appliesToClaimId?: string;
+    /**
+     * Which reading dimension this record carries. Absent means
+     * `"policy-standard"` (the pre-#259 behavior, unchanged).
+     */
+    readingKind?: InterpretationReadingKind;
+    /**
+     * Required when `readingKind` is `"answerImpact"`; illegal for any other
+     * kind. The structured impact beside the free-text `reading`.
+     */
+    answerImpact?: InterpretationAnswerImpact;
     anchorsToSourceId: string;
+    /**
+     * Locator inside the anchor source: the rule paragraph for a
+     * `"policy-standard"` reading, or the result location the producer read for
+     * `"gleaned"` / `"answerImpact"` readings.
+     */
     ruleLocator: string;
     reading: string;
     actor: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -72,9 +72,9 @@
     "workflow:validate-artifacts": "flow-agents-validate-artifacts"
   },
   "dependencies": {
-    "@kontourai/surface": "^2.13.0",
+    "@kontourai/surface": "^2.13.0 || ^3.0.0 || ^4.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.2.0"
+    "zod": "4.4.3"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"
@@ -85,7 +85,7 @@
     }
   },
   "devDependencies": {
-    "@kontourai/flow-agents": "5.5.0",
+    "@kontourai/flow-agents": "5.10.0",
     "@kontourai/traverse": "^0.25.0",
     "@kontourai/ui": "^1.1.0",
     "@playwright/test": "^1.62.0",
@@ -96,6 +96,7 @@
   "engines": {
     "node": ">=22"
   },
+  "packageManager": "pnpm@11.25.0",
   "bin": {
     "survey-review-mcp": "./bin/survey-review-mcp.mjs",
     "survey-review-console": "./bin/survey-review-console.mjs"