@kontourai/survey 2.4.3 → 3.0.0

package/README.md

@@ -203,7 +203,8 @@ host app should read as itself.
 
 ## Review MCP
 
-Drive review-queue decisions from an MCP agent (Claude Desktop, Cursor, or any MCP host):
+Drive review-queue decisions from any MCP host. The official server runtime
+automatically supports MCP 2026-07-28 discovery and existing legacy clients:
 
 ```sh
 npx survey-review-mcp --session path/to/session.json

package/dist/example-data/public-directory-review-resource.d.ts

@@ -35,12 +35,12 @@ export declare const publicDirectoryReviewItemExample: {
                 excerpt: string;
             };
             extraction: {
+                model?: undefined;
                 extractionId: string;
                 target: string;
                 confidence: number;
                 extractor: string;
                 extractedAt: string;
-                model?: undefined;
             };
             claimTarget: {
                 claimId: string;
@@ -61,13 +61,13 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
             };
             producer: {
+                proposalId?: undefined;
+                oldValue?: undefined;
                 sourceAuthority: {
                     authorityClass: string;
                     declaredBy: string;
                     scope: string;
                 };
-                proposalId?: undefined;
-                oldValue?: undefined;
             };
         } | {
             id: string;

package/dist/src/agent-utterance.d.ts

@@ -16,7 +16,7 @@
  * has full provenance (excerpt, span, extractor name, confidence) and is
  * run through the Inquiry pipeline rather than treated as authoritative.
  */
-import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
+import type { DerivationRule, InquiryRecord, TrustBundle, TrustStatus } from "@kontourai/surface";
 import type { CanonicalClaimTarget } from "@kontourai/surface";
 import type { Candidate, CandidateSet, Extraction, RawSource, SurveyInput } from "./types.js";
 import type { InquiryMapping } from "./inquiry-mapping.js";
@@ -52,17 +52,63 @@ export interface UtteranceClaimExtractor {
     extract(utterance: string): ExtractedStatement[] | Promise<ExtractedStatement[]>;
 }
 /**
- * Badge values for each extracted statement, derived from the inquiry outcome
- * and the answer status.
- *
- * - "verified": inquiry matched/derived and answer status is "verified"
- * - "assumed": inquiry matched/derived and answer status is "assumed"
- * - "stale": inquiry matched/derived and answer status is "stale"
- * - "disputed": inquiry matched/derived and answer status is "disputed"
- * - "rejected": inquiry matched/derived and answer status is "rejected"
- * - "unsupported": inquiry outcome is "unsupported" (no mapping or no registered claim)
+ * Badge values for each extracted statement.
+ *
+ * A badge grades THE STATEMENT, not the target. It is a function of two
+ * things: the status of the bundle's answer for the statement's canonical
+ * target, and how the statement's own asserted value compares to that
+ * answer's value.
+ *
+ * The status half of the vocabulary is Surface's `TrustStatus` verbatim —
+ * Survey does not mint parallel status terms for concepts Surface (and the
+ * Hachure core record shapes it implements) already name. Only two badge
+ * values are Survey-side additions, because they describe the
+ * statement-vs-answer relation rather than a claim's standing:
+ *
+ * - "contradicted": the bundle has an answer that would otherwise read as
+ *   support ("verified", "assumed", "stale") and the statement asserts a
+ *   DIFFERENT value. Mirrors the Hachure `contradiction` transparency-gap
+ *   type (merge.md §7b): a value conflict is surfaced, never silently
+ *   resolved in favour of one side.
+ * - "unsupported": the inquiry did not resolve to an answer at all — no
+ *   mapping and no registered claim for the target. This value means "there
+ *   is nothing here to compare against", and nothing else: a claim that is
+ *   registered but merely awaiting review badges "proposed", and one with no
+ *   evidence badges "unknown".
+ *
+ * Every other badge is the answer's `TrustStatus` passed through unchanged,
+ * so there is no fall-through path that can report a real status under a
+ * label meaning "no such claim".
+ */
+export type StatementBadge = TrustStatus | "contradicted" | "unsupported";
+/**
+ * How a statement's asserted value compares to the bundle's answer value.
+ *
+ * - "agrees": both are comparable scalars and equivalent under
+ *   `assertionComparisonKey`.
+ * - "contradicts": both are comparable scalars and NOT equivalent.
+ * - "not-compared": no comparison was possible — the inquiry produced no
+ *   answer, or the extractor parsed no value out of the statement
+ *   (`ExtractedStatement.value` absent), or one side is not a scalar.
+ *   Never treated as agreement.
+ */
+export type StatementValueComparison = "agrees" | "contradicts" | "not-compared";
+/**
+ * How the Extraction's `text-span:` locator was resolved for a statement.
+ *
+ * - "span": the extractor supplied an explicit character span; the locator
+ *   points where the extractor said it does.
+ * - "excerpt-match": no span, but the excerpt was found verbatim in the
+ *   utterance; the locator points at that occurrence.
+ * - "unanchored-fallback": no span AND the excerpt does not occur in the
+ *   utterance. The locator is still well-formed (`text-span:0-<length>`) so
+ *   downstream producer discipline holds, but it is a length-shaped
+ *   placeholder anchored at offset 0 — it does NOT point at the excerpt, and
+ *   the text it spans is unrelated prose. Anything that resolves the locator
+ *   against the source MUST check this field first; a hallucinated excerpt
+ *   lands here.
  */
-export type StatementBadge = "verified" | "assumed" | "stale" | "disputed" | "rejected" | "unsupported";
+export type LocatorResolution = "span" | "excerpt-match" | "unanchored-fallback";
 export interface UtteranceStatement {
     excerpt: string;
     span?: {
@@ -70,6 +116,29 @@ export interface UtteranceStatement {
         end: number;
     };
     target: CanonicalClaimTarget;
+    /**
+     * The value the statement asserted, verbatim from the extractor
+     * (`ExtractedStatement.value`) — not normalized, not defaulted. Absent when
+     * the extractor parsed no value, which is exactly when `valueComparison`
+     * is "not-compared". This is the field a reader needs to see WHAT was
+     * compared against the bundle's answer.
+     */
+    assertedValue?: unknown;
+    /** How `assertedValue` compares to `inquiryRecord.answer?.value`. */
+    valueComparison: StatementValueComparison;
+    /** Human-readable account of the comparison, naming both sides. */
+    comparisonRationale: string;
+    /**
+     * The Survey provenance records this statement produced: its Extraction,
+     * its Candidate, and the per-target Candidate Set it belongs to. The
+     * Candidate Set carries the Candidate Conflict verdict and rationale when
+     * two statements in the SAME utterance disagree about one target
+     * (`candidateSet.status === "conflict"`), which is a different signal from
+     * `valueComparison` (statement vs bundle).
+     */
+    records: UtteranceStatementRecords;
+    /** How this statement's Extraction locator was resolved. */
+    locatorResolution: LocatorResolution;
     inquiryRecord: InquiryRecord;
     badge: StatementBadge;
 }
@@ -107,6 +176,13 @@ interface UtteranceRecordsResult {
     records: UtteranceStatementRecords[];
     extractions: Extraction[];
     candidateSets: CandidateSet[];
+    /**
+     * `locatorResolutions[idx]` is how `records[idx]`'s Extraction locator was
+     * resolved — a parallel array rather than a fourth key on
+     * `UtteranceStatementRecords`, whose shape is a pinned contract. The same
+     * value is also on `records[idx].extraction.metadata.agentUtterance`.
+     */
+    locatorResolutions: LocatorResolution[];
 }
 /**
  * Build the full set of Survey records for every extracted statement in one

package/dist/src/agent-utterance.js

@@ -59,8 +59,10 @@ function buildUtteranceExtraction(params) {
     const candidateId = `${statementId}.candidate`;
     // Compute locator — required for non-manual-entry sources
     // (assertProducerDiscipline throws without it). Source Locator rule:
-    // span-first, excerpt-fallback — UNCHANGED from Slice 1.
-    const locator = spanToLocator(statement.span) ?? excerptLocator(utterance, statement.excerpt);
+    // span-first, excerpt-fallback — locator VALUES unchanged from Slice 1;
+    // what is new is that the record now says which branch produced them, so
+    // an unanchored placeholder is never mistaken for a resolved pointer.
+    const { locator, resolution: locatorResolution } = resolveUtteranceLocator(utterance, statement);
     const extraction = {
         id: extractionId,
         sourceId,
@@ -77,6 +79,7 @@ function buildUtteranceExtraction(params) {
                 excerpt: statement.excerpt,
                 extractorName,
                 confidence: statement.confidence,
+                locatorResolution,
             },
         },
     };
@@ -93,7 +96,7 @@ function buildUtteranceExtraction(params) {
             confidence: statement.confidence,
         },
     };
-    return { extraction, proposal };
+    return { extraction, proposal, locatorResolution };
 }
 /**
  * Group extraction/proposal pairs by canonical target and project each
@@ -166,7 +169,7 @@ function groupUtteranceExtractionsByTarget(sourceId, items) {
 export function buildUtteranceRecords(params) {
     const { sourceId, utterance, extracted, extractorName, observedAt } = params;
     const items = extracted.map((statement, idx) => {
-        const { extraction, proposal } = buildUtteranceExtraction({
+        const { extraction, proposal, locatorResolution } = buildUtteranceExtraction({
             sourceId,
             idx,
             statement,
@@ -174,7 +177,7 @@ export function buildUtteranceRecords(params) {
             extractorName,
             observedAt,
         });
-        return { statement, extraction, proposal };
+        return { statement, extraction, proposal, locatorResolution };
     });
     const groups = groupUtteranceExtractionsByTarget(sourceId, items);
     const records = items.map((item) => {
@@ -186,6 +189,7 @@ export function buildUtteranceRecords(params) {
         records,
         extractions: items.map((i) => i.extraction),
         candidateSets: [...groups.values()].map((g) => g.candidateSet),
+        locatorResolutions: items.map((i) => i.locatorResolution),
     };
 }
 // ---------------------------------------------------------------------------
@@ -234,7 +238,7 @@ export function utteranceToSurveyInput(utterance, extracted, context) {
     // core) — replaces the old per-statement builder call. Claims below stay
     // one-per-statement; `record.candidateSet.id`/`record.candidate.id` may be
     // shared across several claims when statements share a target (legal).
-    const { records, extractions, candidateSets } = buildUtteranceRecords({
+    const { records, extractions, candidateSets, locatorResolutions } = buildUtteranceRecords({
         sourceId,
         utterance,
         extracted,
@@ -270,6 +274,9 @@ export function utteranceToSurveyInput(utterance, extracted, context) {
                         span: statement.span,
                         confidence: statement.confidence,
                         locator: record.extraction.locator,
+                        // Travels with the locator so a downstream reader of the Claim
+                        // never has to assume the locator resolved.
+                        locatorResolution: locatorResolutions[idx],
                     },
                 },
             },
@@ -318,13 +325,14 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
     };
     // Step 2: Extract statements
     const extracted = await Promise.resolve(extractor.extract(utterance));
-    // Batched, grouped provenance construction — kept for provenance/doc-comment
-    // fidelity across the whole utterance (grouping needs every statement of a
-    // target's group present at once; a per-statement call cannot compute it).
-    // Still not surfaced on UtteranceStatement/UtteranceTrustReport this slice
-    // (unchanged from Slice 1's own scoping note) — wiring is left for a future
-    // slice, same as before.
-    buildUtteranceRecords({
+    // Batched, grouped provenance construction. Grouping needs every statement
+    // of a target's group present at once, so this cannot be a per-statement
+    // call. The result is now carried onto every UtteranceStatement
+    // (`records`), so the extractor's confidence, locator, Candidate and
+    // Candidate Set — including the Candidate Conflict verdict when two
+    // statements in this utterance disagree about one target — are observable
+    // in the report instead of being computed and dropped on the floor.
+    const { records, locatorResolutions } = buildUtteranceRecords({
         sourceId,
         utterance,
         extracted,
@@ -333,7 +341,7 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
     });
     // Step 3 & 4: Resolve each statement and build the report
     const statements = [];
-    for (const statement of extracted) {
+    for (const [idx, statement] of extracted.entries()) {
         // Resolve the claim
         let inquiryRecord;
         if (mappings && mappings.length > 0) {
@@ -358,11 +366,17 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
             // Resolve directly by canonical target
             inquiryRecord = resolveByTarget(bundle, statement.target, agentId, observedAt, rules, now);
         }
-        const badge = badgeFromRecord(inquiryRecord);
+        const comparison = compareAssertedValue(statement, inquiryRecord);
+        const badge = badgeFor(inquiryRecord, comparison.valueComparison);
         statements.push({
             excerpt: statement.excerpt,
             span: statement.span,
             target: statement.target,
+            ...(hasAssertedValue(statement) ? { assertedValue: statement.value } : {}),
+            valueComparison: comparison.valueComparison,
+            comparisonRationale: comparison.rationale,
+            records: records[idx],
+            locatorResolution: locatorResolutions[idx],
             inquiryRecord,
             badge,
         });
@@ -389,45 +403,122 @@ function canonicalTargetKey(target) {
 function targetToQuestion(target) {
     return `${target.subjectId} ${target.fieldOrBehavior}`;
 }
-function badgeFromRecord(record) {
+/**
+ * Answer statuses a reader takes as support for what the statement said.
+ * These — and only these — are the statuses a contradiction must override:
+ * badging a statement "verified" when it asserts a value the verified claim
+ * denies is the exact failure this profile exists to prevent. For any other
+ * status the claim's own standing is already the more informative thing to
+ * show, and the contradiction stays legible in `valueComparison`.
+ */
+const SUPPORTING_STATUSES = new Set(["verified", "assumed", "stale"]);
+function hasAssertedValue(statement) {
+    return statement.value !== undefined;
+}
+/**
+ * Whether a value can take part in a statement-vs-answer comparison at all.
+ * Scalars can; objects and arrays cannot, because an utterance extractor
+ * pulls a token out of prose and there is no defensible way to decide
+ * whether that token "is" a structured value. Those report "not-compared"
+ * rather than being asserted to contradict.
+ */
+function isComparableScalar(value) {
+    return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+/**
+ * The statement-vs-answer comparison key.
+ *
+ * This is deliberately NOT `utteranceEquivalenceKey`. That key compares two
+ * values from the SAME extractor, which share one type discipline, so it
+ * refuses cross-type equality on purpose (5 and "5" from one extractor
+ * really are different findings). A statement-vs-answer comparison crosses a
+ * boundary: the left side is a token the extractor pulled out of prose, the
+ * right side is a value the producer typed. Comparing those two by
+ * `typeof` would badge every true statement about a numeric or boolean field
+ * as a contradiction — a false accusation, which damages the badge exactly
+ * as much as a false green does.
+ *
+ * So scalars are compared by their canonical TEXT rendering, trimmed and
+ * lowercased. This bridges "the agent wrote 95" to "the producer stored 95"
+ * without losing a genuine disagreement: "5" and "6" still differ, and the
+ * bridge is named in `comparisonRationale` rather than applied silently.
+ */
+function assertionComparisonKey(value) {
+    return String(value).trim().toLowerCase();
+}
+/**
+ * Compare the statement's own asserted value against the bundle's answer.
+ *
+ * An absent asserted value is never treated as agreement: an extractor that
+ * parsed no value has asserted nothing to check, so it reports
+ * "not-compared".
+ */
+function compareAssertedValue(statement, record) {
+    const targetKey = canonicalTargetKey(statement.target);
+    const answer = record.answer;
+    if (!answer) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `No answer for ${targetKey} (inquiry outcome: ${record.outcome}); nothing to compare the statement against.`,
+        };
+    }
+    if (!hasAssertedValue(statement)) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `The extractor parsed no value out of this statement, so nothing was compared against the ${answer.status} answer for ${targetKey}.`,
+        };
+    }
+    if (!isComparableScalar(statement.value) || !isComparableScalar(answer.value)) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `Statement value ${JSON.stringify(statement.value) ?? "undefined"} and the ${answer.status} answer ${JSON.stringify(answer.value) ?? "undefined"} for ${targetKey} are not both scalars; no comparison was attempted.`,
+        };
+    }
+    const asserted = assertionComparisonKey(statement.value);
+    const answered = assertionComparisonKey(answer.value);
+    const shown = `statement "${asserted}" vs ${answer.status} answer "${answered}" (compared as text)`;
+    return asserted === answered
+        ? { valueComparison: "agrees", rationale: `Agrees for ${targetKey}: ${shown}.` }
+        : { valueComparison: "contradicts", rationale: `Contradicts for ${targetKey}: ${shown}.` };
+}
+/**
+ * Grade the STATEMENT: the answer's status, overridden by "contradicted"
+ * when the statement asserts something the answer denies and that answer
+ * would otherwise have read as support.
+ */
+function badgeFor(record, valueComparison) {
     if (record.outcome === "unsupported")
         return "unsupported";
     const status = record.answer?.status;
     if (!status)
         return "unsupported";
-    if (status === "verified")
-        return "verified";
-    if (status === "assumed")
-        return "assumed";
-    if (status === "stale")
-        return "stale";
-    if (status === "disputed")
-        return "disputed";
-    if (status === "rejected" || status === "superseded")
-        return "rejected";
-    return "unsupported";
+    if (valueComparison === "contradicts" && SUPPORTING_STATUSES.has(status))
+        return "contradicted";
+    return status;
 }
 /**
- * Convert a text-span to a locator string.
- */
-function spanToLocator(span) {
-    if (!span)
-        return undefined;
-    return `text-span:${span.start}-${span.end}`;
-}
-/**
- * Best-effort locator from excerpt text — find the first occurrence of the
- * excerpt in the utterance and use that as a text-span locator.
- * Falls back to text-span:0-0 if the excerpt is not found.
+ * The single Source Locator rule this module guarantees: span-first,
+ * excerpt-match second, unanchored placeholder last — and it always reports
+ * WHICH of the three produced the locator.
+ *
+ * The locator strings are unchanged from Slice 1, including the last branch's
+ * `text-span:0-<excerpt.length>` placeholder. That placeholder is deliberate
+ * (producer discipline requires a locator on a non-manual-entry source), but
+ * it is well-formed and therefore resolvable — it will happily span real,
+ * unrelated prose at the head of the utterance. Returning the resolution
+ * alongside it is what keeps a hallucinated excerpt from acquiring a pointer
+ * that looks exactly like a found one: the record now says the lookup failed
+ * instead of leaving the reader to re-derive it.
  */
-function excerptLocator(utterance, excerpt) {
-    const idx = utterance.indexOf(excerpt);
+function resolveUtteranceLocator(utterance, statement) {
+    if (statement.span) {
+        return { locator: `text-span:${statement.span.start}-${statement.span.end}`, resolution: "span" };
+    }
+    const idx = utterance.indexOf(statement.excerpt);
     if (idx >= 0) {
-        return `text-span:${idx}-${idx + excerpt.length}`;
+        return { locator: `text-span:${idx}-${idx + statement.excerpt.length}`, resolution: "excerpt-match" };
     }
-    // Fallback: anchor to start (preserves discipline contract; locator is
-    // best-effort for span-less extractors)
-    return `text-span:0-${excerpt.length}`;
+    return { locator: `text-span:0-${statement.excerpt.length}`, resolution: "unanchored-fallback" };
 }
 // ---------------------------------------------------------------------------
 // Reference extractor (deterministic, for tests — not for production use)

package/dist/src/index.d.ts

@@ -10,6 +10,7 @@ export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry
 export type { ExtractionAlignmentState, ArtifactUnavailableCode, BuiltExtractionInspectorCandidate, BuiltExtractionInspectorModel, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
 export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionOccurrence, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
 export type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
+export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
@@ -41,7 +42,7 @@ export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, Polic
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export type { AutoAcceptPolicy, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
-export type { ExtractedStatement, StatementBadge, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
+export type { ExtractedStatement, LocatorResolution, StatementBadge, StatementValueComparison, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
 export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";
 export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";

package/dist/src/index.js

@@ -4,6 +4,7 @@ export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeR
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./review-workbench/queue-binding.js";
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
+export { toSurfaceReviewedExtractionDecision, toSurfaceReviewedExtractionImport, toSurfaceReviewedExtractionItem, } from "./surface-reviewed-extraction.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";

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

@@ -1,30 +1,16 @@
-import { createInterface } from "node:readline";
 import { readFile, writeFile, rename } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
 import { buildReviewSessionEvents, currentReviewItem, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
-/**
- * Minimal Model Context Protocol server over stdio for review-queue inspection
- * and decision-making against a session JSON file.
- *
- * Implemented without an SDK dependency — newline-delimited JSON-RPC 2.0 with
- * the MCP lifecycle (initialize / ping / tools) and an optional embedded UI
- * resource per tool call. The session file is the durable store; decisions
- * append events and write back atomically (write temp + rename).
- */
-const PROTOCOL_VERSION = "2025-06-18";
 const SESSION_NAME = "mcp-review-session";
-// MCP Apps extension (SEP-1865). The review card is offered under both UI
-// conventions so one server renders across hosts: the existing mcp-ui.dev
-// embedded resource in tool results, AND a declared `ui://` resource that the
-// official Apps hosts (ChatGPT/Claude) and Station's SEP-1865 resolver read via
-// resources/read. The canonical pointer is the FLAT `_meta["ui/resourceUri"]`
-// key (what registerAppTool emits); the nested `_meta.ui.resourceUri` is the
-// convenience shape some hosts read — we emit both.
 const UI_RESOURCE_URI_META_KEY = "ui/resourceUri";
 const UI_CAPABILITY_EXTENSION = "io.modelcontextprotocol/ui";
 const QUEUE_PANEL_URI = "ui://survey/review-card/queue";
 const UI_RESOURCE_MIME = "text/html;profile=mcp-app";
+const SERVER_INSTRUCTIONS = "Use survey_review_queue to inspect the queue, survey_review_item to drill into one item, and survey_review_decide to record a decision. Decisions are validated and persisted to the session file and are irreversible within this session.";
 // MCP tool decision strings → ReviewWorkbenchDecision
 const MCP_DECISION_MAP = {
     accept: "accept-proposed",
@@ -449,213 +435,160 @@ function buildUiResource(item, snapshot, events, instance) {
             mimeType: "text/html;profile=mcp-app",
             text: buildReviewCardHtml(item, snapshot, events),
             _meta: {
+                ui: {
+                    csp: {
+                        connectDomains: [],
+                        resourceDomains: [],
+                    },
+                },
                 "mcpui.dev/ui-preferred-frame-size": ["420px", "560px"],
             },
         },
     };
 }
-// Render the SEP-1865 declared review card: load the configured session, replay
-// to current state, and render the active item's card HTML (the same HTML the
-// embedded `queue` resource carries — here served via resources/read).
-async function readQueuePanelHtml(options) {
+// Render the declared review card from the same function used by embedded tool
+// results, so Apps and text-first hosts cannot drift.
+async function readQueuePanelResource(options) {
     const { snapshot, events } = await readSessionFile(options.sessionPath);
     const current = currentSessionState(snapshot, events);
     const activeItem = currentReviewItem(current);
-    return buildReviewCardHtml(activeItem, snapshot, events);
+    return buildUiResource(activeItem, snapshot, events, "queue").resource;
 }
 // ---- Domain error (maps to isError:true, not a JSON-RPC error) -----------
 class DomainError extends Error {
     isDomainError = true;
 }
-// ---- JSON-RPC dispatch ---------------------------------------------------
-async function handleLine(line, options, serverVersion) {
-    const trimmed = line.trim();
-    if (trimmed === "")
-        return;
-    let message;
-    try {
-        message = JSON.parse(trimmed);
-    }
-    catch {
-        send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
-        return;
+// ---- Official dual-era MCP server ---------------------------------------
+function uiResourceMeta(resourceUri) {
+    return {
+        ui: { resourceUri, visibility: ["model", "app"] },
+        [UI_RESOURCE_URI_META_KEY]: resourceUri,
+    };
+}
+function createReviewMcpServer(options, serverVersion) {
+    const server = new McpServer({
+        name: "survey-review-mcp",
+        title: "Survey Review MCP",
+        version: serverVersion,
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+        capabilities: options.noUi
+            ? {}
+            : {
+                extensions: {
+                    [UI_CAPABILITY_EXTENSION]: {},
+                },
+            },
+        cacheHints: {
+            "server/discover": { ttlMs: 0, cacheScope: "private" },
+            "tools/list": { ttlMs: 0, cacheScope: "private" },
+            "resources/list": { ttlMs: 0, cacheScope: "private" },
+            "resources/read": { ttlMs: 0, cacheScope: "private" },
+        },
+    });
+    server.registerTool("survey_review_queue", {
+        title: "Review queue",
+        description: "Return a text summary and JSON of the current review queue: all items with their status, the active item, resolved/total counts, and session summary totals.",
+        inputSchema: z.object({}),
+        ...(options.noUi ? {} : { _meta: uiResourceMeta(QUEUE_PANEL_URI) }),
+    }, async () => runReviewTool(() => toolQueue(options)));
+    server.registerTool("survey_review_item", {
+        title: "Review item detail",
+        description: "Return full detail for one review item: current and proposed values, confidence, source references, excerpts, and any current decision.",
+        inputSchema: z.object({
+            itemName: z.string().min(1).describe("The ReviewItem name to inspect."),
+        }),
+    }, async ({ itemName }) => runReviewTool(() => toolItem(itemName, options)));
+    server.registerTool("survey_review_decide", {
+        title: "Record a review decision",
+        description: "Apply a decision to a review item and persist it through Survey's server-owned validation boundary. Decision must be accept, hold, reject, or could-not-confirm. Could-not-confirm requires a reason. Domain failures return isError:true.",
+        inputSchema: z.discriminatedUnion("decision", [
+            z.object({
+                itemName: z.string().min(1).describe("The ReviewItem name to decide."),
+                decision: z
+                    .enum(["accept", "hold", "reject"])
+                    .describe("accept = accept-proposed, hold = keep-current, reject = reject-proposed."),
+                note: z.string().optional().describe("Optional reviewer note or rationale."),
+            }),
+            z.object({
+                itemName: z.string().min(1).describe("The ReviewItem name to decide."),
+                decision: z
+                    .literal("could-not-confirm")
+                    .describe("Record a terminal non-answer after evidence attempts are exhausted."),
+                reason: z
+                    .string()
+                    .trim()
+                    .min(1)
+                    .describe("Required non-empty reason for the could-not-confirm decision."),
+                attemptEvidenceIds: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Evidence ids attempted before a could-not-confirm decision."),
+            }),
+        ]),
+    }, async (input) => runReviewTool(() => input.decision === "could-not-confirm"
+        ? toolDecide(input.itemName, input.decision, input.reason, input.attemptEvidenceIds, options)
+        : toolDecide(input.itemName, input.decision, input.note, undefined, options)));
+    if (!options.noUi) {
+        server.registerResource("survey-review-workbench", QUEUE_PANEL_URI, {
+            title: "Survey review workbench",
+            description: "Interactive review card for the active item in the configured review session.",
+            mimeType: UI_RESOURCE_MIME,
+            cacheHint: { ttlMs: 0, cacheScope: "private" },
+        }, async () => {
+            const resource = await readQueuePanelResource(options);
+            return {
+                contents: [
+                    {
+                        uri: QUEUE_PANEL_URI,
+                        mimeType: resource.mimeType,
+                        text: sanitizeProtocolText(resource.text),
+                        _meta: resource._meta,
+                    },
+                ],
+            };
+        });
     }
-    const { id, method, params } = message;
-    const isNotification = id === undefined;
+    return server;
+}
+async function runReviewTool(operation) {
     try {
-        if (method === "initialize") {
-            send({
-                jsonrpc: "2.0",
-                id,
-                result: {
-                    protocolVersion: PROTOCOL_VERSION,
-                    capabilities: {
-                        tools: { listChanged: false },
-                        // Resources back the SEP-1865 ui:// review card (unless --no-ui).
-                        ...(options.noUi ? {} : { resources: { listChanged: false } }),
-                        ...(options.noUi
-                            ? {}
-                            : { extensions: { [UI_CAPABILITY_EXTENSION]: {} } }),
-                    },
-                    serverInfo: { name: "survey-review-mcp", title: "Survey Review MCP", version: serverVersion },
-                    instructions: "Use survey_review_queue to inspect the queue, survey_review_item to drill into a single item, and survey_review_decide to record a decision. Decisions are persisted to the session file and are irreversible within this session.",
-                },
-            });
-        }
-        else if (method === "ping") {
-            send({ jsonrpc: "2.0", id, result: {} });
-        }
-        else if (method === "tools/list") {
-            send({
-                jsonrpc: "2.0",
-                id,
-                result: {
-                    tools: [
-                        {
-                            name: "survey_review_queue",
-                            title: "Review queue",
-                            description: "Return a text summary and JSON of the current review queue: all items with their status (pending, in-review, resolved, rejected, escalated), the active item, resolved/total counts, and session summary totals.",
-                            inputSchema: { type: "object", properties: {} },
-                            // SEP-1865 UI pointer (both flat canonical + nested), unless --no-ui.
-                            ...(options.noUi
-                                ? {}
-                                : {
-                                    _meta: {
-                                        [UI_RESOURCE_URI_META_KEY]: QUEUE_PANEL_URI,
-                                        ui: { resourceUri: QUEUE_PANEL_URI, visibility: ["model", "app"] },
-                                    },
-                                }),
-                        },
-                        {
-                            name: "survey_review_item",
-                            title: "Review item detail",
-                            description: "Return full detail for a single review item: current vs proposed values, confidence, source references, excerpts, and the current decision (if any).",
-                            inputSchema: {
-                                type: "object",
-                                properties: {
-                                    itemName: { type: "string", description: "The ReviewItem name to inspect." },
-                                },
-                                required: ["itemName"],
-                            },
-                        },
-                        {
-                            name: "survey_review_decide",
-                            title: "Record a review decision",
-                            description: "Apply a decision to a review item and persist it to the session file. Decision must be accept, hold, reject, or could-not-confirm. Could-not-confirm requires a reason. Domain failures return isError:true.",
-                            inputSchema: {
-                                type: "object",
-                                properties: {
-                                    itemName: { type: "string", description: "The ReviewItem name to decide." },
-                                    decision: {
-                                        type: "string",
-                                        enum: ["accept", "hold", "reject", "could-not-confirm"],
-                                        description: "accept = accept-proposed, hold = keep-current, reject = reject-proposed, could-not-confirm = terminal non-answer.",
-                                    },
-                                    note: { type: "string", description: "Optional reviewer note / rationale." },
-                                    reason: { type: "string", minLength: 1, description: "Required non-empty reason when decision is could-not-confirm." },
-                                    attemptEvidenceIds: {
-                                        type: "array",
-                                        items: { type: "string" },
-                                        description: "Optional evidence ids recording what was attempted before could-not-confirm.",
-                                    },
-                                },
-                                required: ["itemName", "decision"],
-                                allOf: [{
-                                        if: { properties: { decision: { const: "could-not-confirm" } }, required: ["decision"] },
-                                        then: { required: ["reason"] },
-                                    }],
-                            },
-                        },
-                    ],
-                },
-            });
-        }
-        else if (method === "resources/list") {
-            send({
-                jsonrpc: "2.0",
-                id,
-                result: {
-                    resources: options.noUi
-                        ? []
-                        : [
-                            {
-                                uri: QUEUE_PANEL_URI,
-                                name: "Survey review workbench",
-                                description: "Interactive review card for the active item in the configured review session (MCP Apps UI resource).",
-                                mimeType: UI_RESOURCE_MIME,
-                            },
-                        ],
-                },
-            });
-        }
-        else if (method === "resources/read") {
-            const uri = typeof params?.uri === "string" ? params.uri : "";
-            if (options.noUi || uri !== QUEUE_PANEL_URI) {
-                send({ jsonrpc: "2.0", id, error: { code: -32602, message: `Unknown resource: ${uri || "(missing uri)"}` } });
-                return;
-            }
-            const html = await readQueuePanelHtml(options);
-            send({
-                jsonrpc: "2.0",
-                id,
-                result: { contents: [{ uri: QUEUE_PANEL_URI, mimeType: UI_RESOURCE_MIME, text: html }] },
-            });
-        }
-        else if (method === "tools/call") {
-            const name = typeof params?.name === "string" ? params.name : "";
-            const toolArgs = (params?.arguments ?? {});
-            try {
-                let content;
-                if (name === "survey_review_queue") {
-                    content = await toolQueue(options);
-                }
-                else if (name === "survey_review_item") {
-                    const itemName = typeof toolArgs.itemName === "string" ? toolArgs.itemName : "";
-                    if (!itemName) {
-                        throw new DomainError("survey_review_item requires itemName");
-                    }
-                    content = await toolItem(itemName, options);
-                }
-                else if (name === "survey_review_decide") {
-                    const itemName = typeof toolArgs.itemName === "string" ? toolArgs.itemName : "";
-                    const decision = typeof toolArgs.decision === "string" ? toolArgs.decision : "";
-                    const note = typeof toolArgs.note === "string" ? toolArgs.note : undefined;
-                    const reason = typeof toolArgs.reason === "string" ? toolArgs.reason : undefined;
-                    const attemptEvidenceIds = Array.isArray(toolArgs.attemptEvidenceIds)
-                        && toolArgs.attemptEvidenceIds.every((value) => typeof value === "string")
-                        ? toolArgs.attemptEvidenceIds
-                        : undefined;
-                    if (!itemName)
-                        throw new DomainError("survey_review_decide requires itemName");
-                    if (!decision)
-                        throw new DomainError("survey_review_decide requires decision");
-                    content = await toolDecide(itemName, decision, decision === "could-not-confirm" ? reason : note, attemptEvidenceIds, options);
-                }
-                else {
-                    send({ jsonrpc: "2.0", id, error: { code: -32602, message: `Unknown tool: ${name || "(missing name)"}` } });
-                    return;
-                }
-                send({ jsonrpc: "2.0", id, result: { content, isError: false } });
-            }
-            catch (error) {
-                const text = error instanceof Error ? error.message : String(error);
-                send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text }], isError: true } });
-            }
-        }
-        else if (isNotification) {
-            // Lifecycle notifications such as notifications/initialized need no reply.
-        }
-        else {
-            send({ jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method ?? "(none)"}` } });
-        }
+        return {
+            content: (await operation()).map(sanitizeContentItem),
+            isError: false,
+        };
     }
     catch (error) {
-        if (!isNotification) {
-            const messageText = error instanceof Error ? error.message : String(error);
-            send({ jsonrpc: "2.0", id, error: { code: -32603, message: messageText } });
-        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: sanitizeProtocolText(error instanceof Error ? error.message : String(error)),
+                },
+            ],
+            isError: true,
+        };
     }
 }
+const UNSAFE_TEXT_CHARS_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u0080-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u206f]/g;
+function sanitizeProtocolText(text) {
+    return text.replace(UNSAFE_TEXT_CHARS_RE, "");
+}
+function sanitizeContentItem(item) {
+    if (item.type === "text") {
+        return { ...item, text: sanitizeProtocolText(item.text) };
+    }
+    return {
+        ...item,
+        resource: {
+            ...item.resource,
+            text: sanitizeProtocolText(item.resource.text),
+        },
+    };
+}
+function sanitizeDiagnostic(text) {
+    return sanitizeProtocolText(text).replaceAll(/\s*\r?\n\s*/g, " ").trim();
+}
 // ---- Entry point ---------------------------------------------------------
 function parseMcpArgs(args) {
     const defaultSession = resolve(dirname(new URL(import.meta.url).pathname), "../../../example-data/mcp-review-session.json");
@@ -688,17 +621,19 @@ async function readPackageVersion() {
         return "0.0.0";
     }
 }
-function send(message) {
-    process.stdout.write(`${JSON.stringify(message)}\n`);
-}
 export async function runReviewMcp(args) {
     const options = parseMcpArgs(args);
     const serverVersion = await readPackageVersion();
-    const rl = createInterface({ input: process.stdin, terminal: false });
-    rl.on("line", (line) => {
-        void handleLine(line, options, serverVersion);
+    const inputClosed = new Promise((resolveClosed) => {
+        process.stdin.once("end", resolveClosed);
+        process.stdin.once("close", resolveClosed);
     });
-    await new Promise((resolveClosed) => {
-        rl.on("close", resolveClosed);
+    const handle = serveStdio(() => createReviewMcpServer(options, serverVersion), {
+        legacy: "serve",
+        onerror: (error) => {
+            process.stderr.write(`survey-review-mcp: ${sanitizeDiagnostic(error.message)}\n`);
+        },
     });
+    await inputClosed;
+    await handle.close();
 }

package/dist/src/surface-reviewed-extraction.d.ts

@@ -0,0 +1,6 @@
+import type { SurveyExtractionEnvelopeImport, SurveyExtractionReviewDecision, SurveyExtractionReviewItem } from "@kontourai/surface";
+import type { ExtractionEnvelopeImport } from "./extraction-envelope.js";
+import type { ReviewDecision, ReviewItem } from "./review-resource.js";
+export declare function toSurfaceReviewedExtractionImport(record: ExtractionEnvelopeImport): SurveyExtractionEnvelopeImport;
+export declare function toSurfaceReviewedExtractionItem(item: ReviewItem): SurveyExtractionReviewItem;
+export declare function toSurfaceReviewedExtractionDecision(decision: ReviewDecision): SurveyExtractionReviewDecision;

package/dist/src/surface-reviewed-extraction.js

@@ -0,0 +1,9 @@
+export function toSurfaceReviewedExtractionImport(record) {
+    return record;
+}
+export function toSurfaceReviewedExtractionItem(item) {
+    return item;
+}
+export function toSurfaceReviewedExtractionDecision(decision) {
+    return decision;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "2.4.3",
+  "version": "3.0.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,9 +50,10 @@
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
+    "test:package-smoke": "npm run build && node --test dist/tests/package-smoke/*.test.js",
     "test:browser": "playwright test",
     "test:browser:concurrent": "npm run build && node scripts/test-playwright-concurrency.mjs",
-    "verify": "npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser && npm run test:browser:concurrent",
+    "verify": "npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run test:package-smoke && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser && npm run test:browser:concurrent",
     "check:content-boundary": "node --test tests/content-boundary-script.test.cjs && node scripts/check-content-boundary.cjs",
     "check:decisions": "node scripts/check-decisions.cjs check",
     "check:guards": "node scripts/check-guards.mjs",
@@ -71,7 +72,9 @@
     "workflow:validate-artifacts": "flow-agents-validate-artifacts"
   },
   "dependencies": {
-    "@kontourai/surface": "^2.9.0"
+    "@kontourai/surface": "^2.13.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.2.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"