@kontourai/survey 1.4.0 → 1.5.0

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

@@ -2,7 +2,7 @@ import { type DeriveReviewSessionApplyResultForSnapshotResult, type MapReviewWor
 import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
-import type { ReviewQueueSessionState } from "./review-queue-session.js";
+import { type ReviewQueueSessionState } from "./review-queue-session.js";
 export interface ServerReviewSessionRecord {
     readonly sessionName: string;
     readonly snapshot: ReviewQueueSessionState;
@@ -59,6 +59,19 @@ export interface DeriveServerReviewSessionApplyResultOptions {
 }
 export declare function createServerReviewSessionRecord(options: CreateServerReviewSessionRecordOptions): ServerReviewSessionRecord;
 export declare function hashReviewSessionSnapshot(snapshot: ReviewQueueSessionState): string;
+/**
+ * Project the current review session state from a snapshot plus its
+ * append-only event log: replay events over the snapshot when any exist,
+ * otherwise return the snapshot itself unchanged (same object reference —
+ * no eager replay, no copy). Collapses the
+ * `events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot`
+ * conditional that was duplicated across the MCP and console review
+ * adapters (src/mcp/review-mcp.ts, src/console/review-console-server.ts) —
+ * same shape of fix as canonicalJson in ./canonical.ts, which was
+ * extracted after two near-identical copies of a derivation desynced
+ * (audit 2026-06-28, ops#24).
+ */
+export declare function currentSessionState(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;
 export declare function compareServerReviewSessionFreshness(record: ServerReviewSessionRecord, snapshot: ReviewQueueSessionState, eventCount?: number): ServerReviewSessionFreshnessComparison;
 export declare function assertServerReviewSessionFreshness(record: ServerReviewSessionRecord, snapshot: ReviewQueueSessionState, eventCount?: number): void;
 export declare function validateServerReviewSessionEvents(record: ServerReviewSessionRecord, events: readonly ReviewSessionEvent[]): ServerReviewSessionEventValidationIssue[];

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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { deriveReviewSessionApplyResultForSnapshot, mapReviewWorkbenchResultsToApplyActions, ReviewApplyActionMappingError, } from "./review-workbench.js";
 import { validateReviewDecisionMode, } from "./producer-decision-mode.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+import { replayReviewSessionEvents } from "./review-queue-session.js";
 import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
     name = "StaleServerReviewSessionError";
@@ -34,6 +35,21 @@ export function createServerReviewSessionRecord(options) {
 export function hashReviewSessionSnapshot(snapshot) {
     return sha256(canonicalJson(snapshot));
 }
+/**
+ * Project the current review session state from a snapshot plus its
+ * append-only event log: replay events over the snapshot when any exist,
+ * otherwise return the snapshot itself unchanged (same object reference —
+ * no eager replay, no copy). Collapses the
+ * `events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot`
+ * conditional that was duplicated across the MCP and console review
+ * adapters (src/mcp/review-mcp.ts, src/console/review-console-server.ts) —
+ * same shape of fix as canonicalJson in ./canonical.ts, which was
+ * extracted after two near-identical copies of a derivation desynced
+ * (audit 2026-06-28, ops#24).
+ */
+export function currentSessionState(snapshot, events) {
+    return events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+}
 export function compareServerReviewSessionFreshness(record, snapshot, eventCount) {
     const actualSnapshotHash = hashReviewSessionSnapshot(snapshot);
     const eventCountMatches = record.eventCount === undefined || eventCount === undefined || record.eventCount === eventCount;

package/dist/src/schema-mapping.js

@@ -20,6 +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 { buildSurveyTrustBundle } from "./to-surface.js";
 // ---------------------------------------------------------------------------
 // Canonical pair key
@@ -84,10 +85,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
         const subjectId = mappingSubjectId(first.sourceField, first.targetField);
         const candidateSetId = `schema-mapping.candidate-set.${pairKey}`;
         const claimId = `schema-mapping.claim.${pairKey}`;
-        // Detect conflict: proposals disagree on relation
-        const relations = new Set(pairProposals.map((p) => p.relation));
-        const status = relations.size > 1 ? "conflict" : "needs-review";
-        const candidates = pairProposals.map((proposal) => {
+        const candidateSetProposals = pairProposals.map((proposal) => {
             // Use the source system's RawSource for this extraction
             const rawSource = sourceById.get(proposal.sourceField.system) ?? rawSources[0];
             const extractionId = `schema-mapping.extraction.${proposal.id}`;
@@ -120,7 +118,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
             };
             extractions.push(extraction);
             return {
-                id: `schema-mapping.candidate.${proposal.id}`,
+                candidateId: `schema-mapping.candidate.${proposal.id}`,
                 extractionId,
                 value: {
                     relation: proposal.relation,
@@ -128,45 +126,41 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                     conversion: proposal.conversion,
                 },
                 confidence: proposal.confidence,
+                equivalenceKey: proposal.relation,
                 metadata: {
-                    schemaMappingProposal: {
-                        proposalId: proposal.id,
-                        sourceField: proposal.sourceField,
-                        targetField: proposal.targetField,
-                        relation: proposal.relation,
-                        conversion: proposal.conversion,
-                        evidence: proposal.evidence,
-                        confidence: proposal.confidence,
-                        rationale: proposal.rationale,
-                        proposedBy: proposal.proposedBy,
-                        proposedAt: proposal.proposedAt,
-                    },
+                    proposalId: proposal.id,
+                    sourceField: proposal.sourceField,
+                    targetField: proposal.targetField,
+                    relation: proposal.relation,
+                    conversion: proposal.conversion,
+                    evidence: proposal.evidence,
+                    confidence: proposal.confidence,
+                    rationale: proposal.rationale,
+                    proposedBy: proposal.proposedBy,
+                    proposedAt: proposal.proposedAt,
                 },
             };
         });
-        const candidateSet = {
-            id: candidateSetId,
-            target: `schema-mapping:${pairKey}`,
-            candidates,
-            selectedCandidateId: status !== "conflict" ? candidates[0]?.id : undefined,
-            status,
-            rationale: status === "conflict"
-                ? `Proposals disagree on relation for pair ${pairKey}: ${[...relations].join(", ")}`
-                : `${candidates.length} proposal(s) agree on relation "${first.relation}" for pair ${pairKey}.`,
-            metadata: {
+        const { candidateSet, candidates } = projectProposalsToCandidateSet(`schema-mapping:${pairKey}`, candidateSetProposals, {
+            candidateSetId,
+            candidateSetMetadata: {
                 schemaMapping: {
                     pairKey,
                     sourceField: first.sourceField,
                     targetField: first.targetField,
                 },
             },
-        };
+            candidateSetRationale: (status, proposals) => status === "conflict"
+                ? `Proposals disagree on relation for pair ${pairKey}: ${[...new Set(proposals.map((p) => p.equivalenceKey))].join(", ")}`
+                : `${proposals.length} proposal(s) agree on relation "${first.relation}" for pair ${pairKey}.`,
+        });
+        candidateSet.selectedCandidateId = candidateSet.status !== "conflict" ? candidates[0]?.id : undefined;
         candidateSets.push(candidateSet);
         // Auto-accept policy: non-conflicting proposals above threshold → assumed
         let autoReviewStatus;
-        if (status !== "conflict" && options.autoAcceptMinConfidence !== undefined) {
+        if (candidateSet.status !== "conflict" && options.autoAcceptMinConfidence !== undefined) {
             const topConfidence = Math.max(...pairProposals.map((p) => p.confidence));
-            if (topConfidence >= options.autoAcceptMinConfidence) {
+            if (meetsAutoAcceptThreshold(topConfidence, options.autoAcceptMinConfidence)) {
                 autoReviewStatus = "assumed";
             }
         }
@@ -180,10 +174,10 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
                 candidateSetId,
                 candidateId: selectedCandidate.id,
                 status: autoReviewStatus,
-                actor: "auto-accept-policy",
+                actor: AUTO_ACCEPT_ACTOR,
                 reviewedAt: generatedAt,
                 rationale: `Auto-accepted: confidence ${selectedCandidate.confidence} >= threshold ${options.autoAcceptMinConfidence}`,
-                withinComfortZone: true,
+                withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
             });
         }
         // Project to ClaimTarget (subjectType "system-field", fieldOrBehavior "maps-to")
@@ -191,7 +185,7 @@ export async function surveySchemaMapping(context, extractor, options = {}) {
             const review = reviewOutcomes.find((r) => r.candidateSetId === candidateSetId);
             const claimStatus = review
                 ? review.status
-                : (status === "conflict" ? "disputed" : undefined);
+                : (candidateSet.status === "conflict" ? "disputed" : undefined);
             const claimTarget = {
                 id: claimId,
                 candidateSetId,
@@ -266,7 +260,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     const rawSources = [];
     const seenSources = new Set();
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const sourceId = `schema-mapping.source.${sourceField.system}`;
         if (!seenSources.has(sourceId)) {
@@ -290,7 +284,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     const reviewOutcomes = [];
     const claims = [];
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const targetField = meta?.targetField ?? rm.proposal.targetField;
         const relation = (meta?.relation ?? rm.proposal.relation);
@@ -379,7 +373,7 @@ export function mappingReviewToSurface(reviewedMappings, options = {}) {
     // subject and back-references the mapping claim via mappingClaimId.
     const identityLinks = [];
     for (const rm of accepted) {
-        const meta = rm.selectedCandidate.metadata?.schemaMappingProposal;
+        const meta = getProducerProposal(rm.selectedCandidate);
         const sourceField = meta?.sourceField ?? rm.proposal.sourceField;
         const targetField = meta?.targetField ?? rm.proposal.targetField;
         const relation = (meta?.relation ?? rm.proposal.relation);

package/dist/src/source-of-authority-observation.js

@@ -1,4 +1,5 @@
 import { buildObservation } from "./observation-helper.js";
+import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 export class SourceOfAuthorityObservationBuilder {
     state;
     constructor(args) {
@@ -115,15 +116,11 @@ function assertVerifiedPosture(input) {
     if (!input.extraction.locator) {
         throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a source locator`);
     }
-    if (!input.reviewOutcome) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a review outcome`);
-    }
-    if (!input.reviewOutcome.actor) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without review actor authority`);
-    }
-    if (!input.reviewOutcome.reviewedAt) {
-        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without reviewedAt`);
-    }
+    assertReviewOutcomeDiscipline({
+        subject: `Source-of-authority observation ${input.id}`,
+        status,
+        review: input.reviewOutcome,
+    });
 }
 function claimStatus(claimStatusValue, reviewStatus) {
     return claimStatusValue ?? reviewStatus;

package/dist/src/to-surface.js

@@ -1,4 +1,5 @@
 import { buildReviewProofAnchor } from "./review-proof.js";
+import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 export function buildSurveyTrustBundle(input, options = {}) {
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
@@ -334,15 +335,11 @@ function statusFor(input) {
     return "proposed";
 }
 function assertProducerDiscipline(input) {
-    if ((input.status === "verified" || input.status === "assumed") && !input.review) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without a review outcome`);
-    }
-    if ((input.status === "verified" || input.status === "assumed") && !input.review?.actor) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without review actor authority`);
-    }
-    if ((input.status === "verified" || input.status === "assumed") && !input.review?.reviewedAt) {
-        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without reviewedAt`);
-    }
+    assertReviewOutcomeDiscipline({
+        subject: `Claim ${input.projection.id}`,
+        status: input.status,
+        review: input.review,
+    });
     if (input.rawSource.kind !== "manual-entry" && !input.extraction.locator) {
         throw new Error(`Claim ${input.projection.id} needs a source locator for ${input.rawSource.kind}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -55,8 +55,11 @@
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
     "test:browser": "playwright test",
-    "verify": "node scripts/check-content-boundary.cjs && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser",
+    "verify": "node scripts/check-content-boundary.cjs && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
+    "check:decisions": "node scripts/check-decisions.cjs check",
+    "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
+    "freeze:adrs": "node scripts/freeze-adrs.mjs",
     "sync:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs",
     "check:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs --check",
     "check:review-workbench": "npm run check:review-workbench:static && npm run check:generated-css",