@kontourai/survey 3.0.0 → 5.0.0

package/dist/src/types.d.ts

@@ -28,7 +28,11 @@ export interface Extraction {
     extractedAt: string;
     metadata?: Record<string, unknown>;
 }
-export type CandidateSetStatus = "resolved" | "needs-review" | "conflict" | "escalated";
+/**
+ * `rejected`: a review rejected every candidate in the set and selected none
+ * (for example rejecting all conflicting values for one claim).
+ */
+export type CandidateSetStatus = "resolved" | "needs-review" | "conflict" | "escalated" | "rejected";
 export type EscalationDimension = "framing" | "completeness" | "conclusion" | "citation";
 export interface Candidate {
     id: string;
@@ -104,11 +108,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": "5.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"