@kontourai/survey 0.4.17 → 0.4.20

package/README.md

@@ -101,12 +101,24 @@ For the full consumer path from `ReviewItem` construction through persisted
 review events, exported results, and optional Surface projection, see
 [`docs/consumer-integration-guide.md`](docs/consumer-integration-guide.md).
 That guide also covers the server-side apply boundary: producers should derive
-write results from reviewed snapshots plus persisted events, not from
+write results from pre-decision review snapshots plus persisted events, not from
 browser-computed decisions or exported result payloads.
-Use `persistReviewSessionEvents` when server code needs to save review events
-and then replay exactly the persisted event set before applying product policy.
-For a generic, test-covered example of the consumer adapter contract, see
-[`examples/review-workbench/facility-credential-consumer.ts`](examples/review-workbench/facility-credential-consumer.ts).
+Use `persistReviewSessionEvents` when server code needs to save review events,
+then pass the persisted event set to `deriveReviewSessionApplyResultForSnapshot`
+before applying product policy. Survey derives selected review results and
+structured replay/completion issues; the producer still owns current-record
+validation and writes.
+For browser-backed queues, server code can import
+`@kontourai/survey/review-workbench/server-review-session` and use
+`createServerReviewSessionRecord`, `hashReviewSessionSnapshot`,
+`assertServerReviewSessionFreshness`, and `assertServerReviewSessionEvents` to
+keep the review snapshot server-owned while accepting browser-submitted
+`ReviewSessionEvent` resources.
+For generic, test-covered consumer examples, see
+[`examples/review-workbench/facility-credential-consumer.ts`](examples/review-workbench/facility-credential-consumer.ts)
+for presentation and event persistence, and
+[`examples/review-workbench/server-apply-consumer.ts`](examples/review-workbench/server-apply-consumer.ts)
+for a compact server-side apply boundary.
 For the current decision on why Survey is not adding a generic review adapter
 builder yet, see
 [`docs/consumer-adapter-abstraction-assessment.md`](docs/consumer-adapter-abstraction-assessment.md).

package/dist/examples/review-workbench/facility-credential-consumer.d.ts

@@ -1,16 +1,19 @@
 import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
-import { buildReviewItemPresentation, buildReviewResultPresentation, buildReviewWorkbenchSessionExportForSnapshot, buildSurfaceProjectionPreview, initialReviewQueueSessionState, type ReviewPresentationAdapter } from "../../src/review-workbench/review-workbench.js";
+import { buildReviewItemPresentation, buildReviewResultPresentation, buildSurfaceProjectionPreview, deriveReviewSessionApplyResultForSnapshot, initialReviewQueueSessionState, type ReviewPresentationAdapter } from "../../src/review-workbench/review-workbench.js";
 import type { ReviewSessionEvent } from "../../src/review-resource.js";
 export declare const facilityCredentialPresentationAdapter: ReviewPresentationAdapter;
 export declare function buildFacilityCredentialConsumerExample(): Promise<FacilityCredentialConsumerExample>;
 export declare const facilityCredentialConsumerExample: FacilityCredentialConsumerExample;
 export interface FacilityCredentialConsumerExample {
     readonly reviewItem: typeof facilityCredentialReviewItemFixture;
+    readonly reviewSessionSnapshot: ReturnType<typeof initialReviewQueueSessionState>;
     readonly reviewedSnapshot: ReturnType<typeof initialReviewQueueSessionState>;
     readonly eventsToPersist: readonly ReviewSessionEvent[];
     readonly persistedEvents: readonly ReviewSessionEvent[];
     readonly persistedEventCount: number;
-    readonly sessionExport: ReturnType<typeof buildReviewWorkbenchSessionExportForSnapshot>;
+    readonly applyResult: Extract<ReturnType<typeof deriveReviewSessionApplyResultForSnapshot>, {
+        readonly ok: true;
+    }>;
     readonly itemPresentation: ReturnType<typeof buildReviewItemPresentation>;
     readonly resultPresentation: ReturnType<typeof buildReviewResultPresentation>;
     readonly surfaceProjectionPreview: NonNullable<ReturnType<typeof buildSurfaceProjectionPreview>>;

package/dist/examples/review-workbench/facility-credential-consumer.js

@@ -1,5 +1,5 @@
 import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
-import { buildReviewItemPresentation, buildReviewResultPresentation, buildReviewSessionEvents, buildReviewWorkbenchSessionExportForSnapshot, buildSurfaceProjectionPreview, initialReviewQueueSessionState, persistReviewSessionEvents, } from "../../src/review-workbench/review-workbench.js";
+import { buildReviewItemPresentation, buildReviewResultPresentation, buildReviewSessionEvents, buildSurfaceProjectionPreview, deriveReviewSessionApplyResultForSnapshot, initialReviewQueueSessionState, persistReviewSessionEvents, } from "../../src/review-workbench/review-workbench.js";
 export const facilityCredentialPresentationAdapter = {
     labelForTarget: (target) => target === "operatingLicenseCredential"
         ? "Operating license credential"
@@ -45,10 +45,13 @@ export const facilityCredentialPresentationAdapter = {
     },
 };
 export async function buildFacilityCredentialConsumerExample() {
-    const reviewedSnapshot = {
+    const reviewSessionSnapshot = {
         ...initialReviewQueueSessionState([facilityCredentialReviewItemFixture]),
         actorId: "review-operator@example.test",
         reviewedAt: "2026-01-17T16:15:00.000Z",
+    };
+    const reviewedSnapshot = {
+        ...reviewSessionSnapshot,
         decisionsByItemName: {
             [facilityCredentialReviewItemFixture.metadata.name]: "accept-proposed",
         },
@@ -70,8 +73,15 @@ export async function buildFacilityCredentialConsumerExample() {
             return { eventCount: persistedEvents.length };
         },
     });
-    const sessionExport = buildReviewWorkbenchSessionExportForSnapshot(reviewedSnapshot, persisted.events);
-    const [result] = sessionExport.results;
+    const applyResult = deriveReviewSessionApplyResultForSnapshot({
+        snapshot: reviewSessionSnapshot,
+        events: persisted.events,
+        requiredResolvedItems: "all",
+    });
+    if (!applyResult.ok) {
+        throw new Error(`Expected persisted credential events to replay before apply: ${applyResult.issues.map((issue) => issue.message).join(" ")}`);
+    }
+    const [result] = applyResult.results;
     if (!result) {
         throw new Error("Expected the reviewed credential snapshot to produce one review result.");
     }
@@ -83,11 +93,12 @@ export async function buildFacilityCredentialConsumerExample() {
     }
     return {
         reviewItem: facilityCredentialReviewItemFixture,
+        reviewSessionSnapshot,
         reviewedSnapshot,
         eventsToPersist,
         persistedEvents: persisted.events,
         persistedEventCount: persisted.eventCount,
-        sessionExport,
+        applyResult,
         itemPresentation,
         resultPresentation,
         surfaceProjectionPreview,

package/dist/examples/review-workbench/server-apply-consumer.d.ts

@@ -0,0 +1,30 @@
+import { type ReviewQueueSessionState, type ReviewWorkbenchResult } from "../../src/review-workbench/review-workbench.js";
+import type { ReviewSessionEvent } from "../../src/review-resource.js";
+export interface FacilityCredentialRecord {
+    readonly id: string;
+    readonly credential: unknown;
+    readonly appliedReviewItemNames: readonly string[];
+}
+export type FacilityCredentialApplyPreparation = {
+    readonly ok: true;
+    readonly mutation: {
+        readonly recordId: string;
+        readonly credential: unknown;
+        readonly reviewItemName: string;
+        readonly selectedCandidateId: string;
+        readonly actorId: string;
+        readonly appliedAt: string;
+    };
+    readonly result: ReviewWorkbenchResult;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function prepareFacilityCredentialServerApply(input: {
+    readonly currentRecord: FacilityCredentialRecord;
+    readonly reviewSessionSnapshot: ReviewQueueSessionState;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly actorId: string;
+    readonly appliedAt: string;
+}): FacilityCredentialApplyPreparation;
+export declare const facilityCredentialCurrentRecordFixture: FacilityCredentialRecord;

package/dist/examples/review-workbench/server-apply-consumer.js

@@ -0,0 +1,47 @@
+import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
+import { deriveReviewSessionApplyResultForSnapshot, } from "../../src/review-workbench/review-workbench.js";
+export function prepareFacilityCredentialServerApply(input) {
+    const applyResult = deriveReviewSessionApplyResultForSnapshot({
+        snapshot: input.reviewSessionSnapshot,
+        events: input.events,
+        requiredResolvedItems: "all",
+    });
+    if (!applyResult.ok) {
+        return {
+            ok: false,
+            message: applyResult.issues.map((issue) => issue.message).join(" "),
+        };
+    }
+    const [result] = applyResult.results;
+    if (!result || applyResult.results.length !== 1) {
+        return { ok: false, message: "Expected exactly one reviewed credential result." };
+    }
+    const item = input.reviewSessionSnapshot.items.find((candidate) => candidate.metadata.name === result.reviewItemName);
+    if (!item || item.spec.target !== "operatingLicenseCredential") {
+        return { ok: false, message: "Review result does not target the credential field." };
+    }
+    const currentCandidate = item.spec.candidates.find((candidate) => candidate.role === "current");
+    if (!currentCandidate || JSON.stringify(currentCandidate.value) !== JSON.stringify(input.currentRecord.credential)) {
+        return { ok: false, message: "Current credential no longer matches the review session snapshot." };
+    }
+    if (input.currentRecord.appliedReviewItemNames.includes(result.reviewItemName)) {
+        return { ok: false, message: "Review result was already applied." };
+    }
+    return {
+        ok: true,
+        result,
+        mutation: {
+            recordId: input.currentRecord.id,
+            credential: result.selectedValue,
+            reviewItemName: result.reviewItemName,
+            selectedCandidateId: result.selectedCandidateId,
+            actorId: input.actorId,
+            appliedAt: input.appliedAt,
+        },
+    };
+}
+export const facilityCredentialCurrentRecordFixture = {
+    id: "facility-credential-record-1",
+    credential: facilityCredentialReviewItemFixture.spec.candidates.find((candidate) => candidate.role === "current")?.value,
+    appliedReviewItemNames: [],
+};

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

@@ -0,0 +1,12 @@
+import type { ReviewSessionEvent } from "../review-resource.js";
+import { type ReviewQueueSessionState } from "./review-queue-session.js";
+export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch";
+export interface ReviewSessionReplayIssue {
+    readonly code: ReviewSessionReplayIssueCode;
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly reviewItemName?: string;
+    readonly candidateId?: string;
+    readonly message: string;
+}
+export declare function validateReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayIssue[];

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

@@ -0,0 +1,136 @@
+import { candidateForDecision, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+export function validateReviewSessionEventsForSnapshot(snapshot, events) {
+    const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
+    const sequenceIssues = validateEventSequence(events);
+    const replayIssues = events.flatMap((event) => {
+        const issues = [];
+        const activeItemName = event.spec.activeItemName;
+        const reviewItemName = event.spec.reviewItemName;
+        const itemName = reviewItemName ?? activeItemName;
+        const eventRef = {
+            eventName: event.metadata.name,
+            sequence: event.spec.sequence,
+        };
+        if (activeItemName && !itemsByName.has(activeItemName)) {
+            issues.push({
+                ...eventRef,
+                code: "unknown-active-item",
+                reviewItemName: activeItemName,
+                message: `ReviewSessionEvent ${event.metadata.name} references active item ${activeItemName}, but the supplied session snapshot does not contain that ReviewItem.`,
+            });
+        }
+        if (reviewItemName && !itemsByName.has(reviewItemName)) {
+            issues.push({
+                ...eventRef,
+                code: "unknown-review-item",
+                reviewItemName,
+                message: `ReviewSessionEvent ${event.metadata.name} references review item ${reviewItemName}, but the supplied session snapshot does not contain that ReviewItem.`,
+            });
+        }
+        if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+            && !reviewItemName) {
+            issues.push({
+                ...eventRef,
+                code: "missing-review-item",
+                message: `ReviewSessionEvent ${event.metadata.name} is a decision event but does not reference a ReviewItem.`,
+            });
+        }
+        if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
+            const decision = replayableWorkbenchDecision(event.spec.data?.workbenchDecision);
+            if (!decision) {
+                issues.push({
+                    ...eventRef,
+                    code: "invalid-workbench-decision",
+                    reviewItemName,
+                    candidateId: event.spec.candidateId,
+                    message: `ReviewSessionEvent ${event.metadata.name} is a decision event but does not include a replayable workbench decision.`,
+                });
+            }
+            else if (itemName && itemsByName.has(itemName)) {
+                const item = itemsByName.get(itemName);
+                const expectedCandidate = item ? candidateForDecision(item, decision) : undefined;
+                const expectedStatus = workbenchDecisionDefinitions[decision].status;
+                const referencedCandidateExists = event.spec.candidateId
+                    ? item?.spec.candidates.some((candidate) => candidate.id === event.spec.candidateId)
+                    : false;
+                if (expectedCandidate && (!event.spec.candidateId || referencedCandidateExists) && event.spec.candidateId !== expectedCandidate.id) {
+                    issues.push({
+                        ...eventRef,
+                        code: "decision-candidate-mismatch",
+                        reviewItemName: itemName,
+                        candidateId: event.spec.candidateId,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects candidate ${expectedCandidate.id}, but references ${event.spec.candidateId ?? "no candidate"}.`,
+                    });
+                }
+                if (event.spec.status !== expectedStatus) {
+                    issues.push({
+                        ...eventRef,
+                        code: "decision-status-mismatch",
+                        reviewItemName: itemName,
+                        candidateId: event.spec.candidateId,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects status ${expectedStatus}, but references ${event.spec.status ?? "no status"}.`,
+                    });
+                }
+            }
+        }
+        if (event.spec.candidateId && itemName && itemsByName.has(itemName)) {
+            const item = itemsByName.get(itemName);
+            const hasCandidate = item?.spec.candidates.some((candidate) => candidate.id === event.spec.candidateId);
+            if (!hasCandidate) {
+                issues.push({
+                    ...eventRef,
+                    code: "unknown-candidate",
+                    reviewItemName: itemName,
+                    candidateId: event.spec.candidateId,
+                    message: `ReviewSessionEvent ${event.metadata.name} references candidate ${event.spec.candidateId}, but ReviewItem ${itemName} in the supplied session snapshot does not contain that candidate.`,
+                });
+            }
+        }
+        return issues;
+    });
+    return [...sequenceIssues, ...replayIssues];
+}
+function replayableWorkbenchDecision(value) {
+    return typeof value === "string" && value in workbenchDecisionDefinitions
+        ? value
+        : undefined;
+}
+function validateEventSequence(events) {
+    const issues = [];
+    const seen = new Map();
+    events.forEach((event, index) => {
+        const sequence = event.spec.sequence;
+        const eventRef = {
+            eventName: event.metadata.name,
+            sequence,
+        };
+        if (!Number.isSafeInteger(sequence) || sequence < 1) {
+            issues.push({
+                ...eventRef,
+                code: "invalid-sequence",
+                message: `ReviewSessionEvent ${event.metadata.name} has invalid sequence ${String(sequence)}. Sequences must be positive safe integers.`,
+            });
+            return;
+        }
+        const duplicateOf = seen.get(sequence);
+        if (duplicateOf) {
+            issues.push({
+                ...eventRef,
+                code: "duplicate-sequence",
+                message: `ReviewSessionEvent ${event.metadata.name} reuses sequence ${sequence} from ${duplicateOf}.`,
+            });
+        }
+        else {
+            seen.set(sequence, event.metadata.name);
+        }
+        const expected = index + 1;
+        if (sequence !== expected) {
+            issues.push({
+                ...eventRef,
+                code: "non-contiguous-sequence",
+                message: `ReviewSessionEvent ${event.metadata.name} has sequence ${sequence}, but canonical event streams must be ordered and contiguous from 1; expected ${expected}.`,
+            });
+        }
+    });
+    return issues;
+}

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

@@ -1,9 +1,11 @@
 import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.js";
+import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewSession, type ReviewSessionEvent } from "../review-resource.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
+export { validateReviewSessionEventsForSnapshot, type ReviewSessionReplayIssue, type ReviewSessionReplayIssueCode, } from "./review-session-replay.js";
 export declare function buildReviewDecision(state: ReviewWorkbenchState): ReviewDecision | undefined;
 export interface ReviewWorkbenchSessionExport {
     readonly session: ReviewSession;
@@ -11,15 +13,37 @@ export interface ReviewWorkbenchSessionExport {
     readonly decisions: readonly ReviewDecision[];
     readonly results: readonly ReviewWorkbenchResult[];
 }
-export type ReviewSessionReplayIssueCode = "unknown-active-item" | "unknown-review-item" | "unknown-candidate";
-export interface ReviewSessionReplayIssue {
-    readonly code: ReviewSessionReplayIssueCode;
-    readonly eventName: string;
-    readonly sequence: number;
-    readonly reviewItemName?: string;
-    readonly candidateId?: string;
+export type ReviewSessionApplyResolutionRequirement = "all" | "any" | "none";
+export type ReviewSessionApplyIssue = ReviewSessionReplayIssue | {
+    readonly code: "unresolved-review-item";
+    readonly reviewItemName: string;
+    readonly message: string;
+} | {
+    readonly code: "no-resolved-review-items";
     readonly message: string;
+};
+export interface DeriveReviewSessionApplyResultForSnapshotOptions {
+    readonly snapshot: ReviewQueueSessionState;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly requiredResolvedItems?: ReviewSessionApplyResolutionRequirement;
 }
+export type DeriveReviewSessionApplyResultForSnapshotResult = {
+    readonly ok: true;
+    readonly issues: readonly [];
+    readonly unresolvedItemNames: readonly string[];
+    readonly replayedSession: ReviewQueueSessionState;
+    readonly sessionExport: ReviewWorkbenchSessionExport;
+    readonly decisions: readonly ReviewDecision[];
+    readonly results: readonly ReviewWorkbenchResult[];
+} | {
+    readonly ok: false;
+    readonly issues: readonly ReviewSessionApplyIssue[];
+    readonly unresolvedItemNames: readonly string[];
+    readonly replayedSession?: ReviewQueueSessionState;
+    readonly sessionExport?: ReviewWorkbenchSessionExport;
+    readonly decisions: readonly ReviewDecision[];
+    readonly results: readonly ReviewWorkbenchResult[];
+};
 export interface ReviewSessionEventStore {
     load(session: ReviewQueueSessionState): readonly ReviewSessionEvent[] | undefined;
     save(session: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): void;
@@ -77,9 +101,9 @@ export interface ReviewWorkbenchResult {
 export declare function buildReviewDecisionsFromSession(session: ReviewQueueSessionState): ReviewDecision[];
 export declare function buildReviewWorkbenchResultsFromSession(session: ReviewQueueSessionState): ReviewWorkbenchResult[];
 export declare function buildReviewWorkbenchSessionExport(session: ReviewQueueSessionState, events?: readonly ReviewSessionEvent[]): ReviewWorkbenchSessionExport;
-export declare function validateReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayIssue[];
 export declare function replayReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;
 export declare function buildReviewWorkbenchSessionExportForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewWorkbenchSessionExport;
+export declare function deriveReviewSessionApplyResultForSnapshot(options: DeriveReviewSessionApplyResultForSnapshotOptions): DeriveReviewSessionApplyResultForSnapshotResult;
 export declare function createInMemoryReviewSessionEventStore(initialEvents?: readonly ReviewSessionEvent[]): ReviewSessionEventStore & {
     events(): readonly ReviewSessionEvent[];
 };

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

@@ -1,10 +1,12 @@
 import { candidateForDecision, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
 import { reviewResourceApiVersion, } from "../review-resource.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
+export { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 export function buildReviewDecision(state) {
     if (!state.decision) {
         return undefined;
@@ -91,49 +93,6 @@ export function buildReviewWorkbenchSessionExport(session, events = buildReviewS
         results: buildReviewWorkbenchResultsFromSession(session),
     };
 }
-export function validateReviewSessionEventsForSnapshot(snapshot, events) {
-    const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
-    return events.flatMap((event) => {
-        const issues = [];
-        const activeItemName = event.spec.activeItemName;
-        const reviewItemName = event.spec.reviewItemName;
-        const itemName = reviewItemName ?? activeItemName;
-        const eventRef = {
-            eventName: event.metadata.name,
-            sequence: event.spec.sequence,
-        };
-        if (activeItemName && !itemsByName.has(activeItemName)) {
-            issues.push({
-                ...eventRef,
-                code: "unknown-active-item",
-                reviewItemName: activeItemName,
-                message: `ReviewSessionEvent ${event.metadata.name} references active item ${activeItemName}, but the supplied session snapshot does not contain that ReviewItem.`,
-            });
-        }
-        if (reviewItemName && !itemsByName.has(reviewItemName)) {
-            issues.push({
-                ...eventRef,
-                code: "unknown-review-item",
-                reviewItemName,
-                message: `ReviewSessionEvent ${event.metadata.name} references review item ${reviewItemName}, but the supplied session snapshot does not contain that ReviewItem.`,
-            });
-        }
-        if (event.spec.candidateId && itemName && itemsByName.has(itemName)) {
-            const item = itemsByName.get(itemName);
-            const hasCandidate = item?.spec.candidates.some((candidate) => candidate.id === event.spec.candidateId);
-            if (!hasCandidate) {
-                issues.push({
-                    ...eventRef,
-                    code: "unknown-candidate",
-                    reviewItemName: itemName,
-                    candidateId: event.spec.candidateId,
-                    message: `ReviewSessionEvent ${event.metadata.name} references candidate ${event.spec.candidateId}, but ReviewItem ${itemName} in the supplied session snapshot does not contain that candidate.`,
-                });
-            }
-        }
-        return issues;
-    });
-}
 export function replayReviewSessionEventsForSnapshot(snapshot, events) {
     const issues = validateReviewSessionEventsForSnapshot(snapshot, events);
     if (issues.length > 0) {
@@ -145,6 +104,59 @@ export function buildReviewWorkbenchSessionExportForSnapshot(snapshot, events) {
     const replayedSession = replayReviewSessionEventsForSnapshot(snapshot, events);
     return buildReviewWorkbenchSessionExport(replayedSession, events);
 }
+export function deriveReviewSessionApplyResultForSnapshot(options) {
+    const requiredResolvedItems = options.requiredResolvedItems ?? "none";
+    const replayIssues = validateReviewSessionEventsForSnapshot(options.snapshot, options.events);
+    if (replayIssues.length > 0) {
+        return {
+            ok: false,
+            issues: replayIssues,
+            unresolvedItemNames: options.snapshot.items.map((item) => item.metadata.name),
+            decisions: [],
+            results: [],
+        };
+    }
+    const replayedSession = replayReviewSessionEvents(options.snapshot, options.events);
+    const sessionExport = buildReviewWorkbenchSessionExport(replayedSession, options.events);
+    const resolvedItemNames = new Set(sessionExport.results.map((result) => result.reviewItemName));
+    const unresolvedItemNames = options.snapshot.items
+        .map((item) => item.metadata.name)
+        .filter((itemName) => !resolvedItemNames.has(itemName));
+    const issues = [];
+    if (requiredResolvedItems === "all") {
+        issues.push(...unresolvedItemNames.map((reviewItemName) => ({
+            code: "unresolved-review-item",
+            reviewItemName,
+            message: `Review item ${reviewItemName} has no resolved review decision.`,
+        })));
+    }
+    if (requiredResolvedItems === "any" && sessionExport.results.length === 0) {
+        issues.push({
+            code: "no-resolved-review-items",
+            message: "Review session has no resolved review decisions.",
+        });
+    }
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            issues,
+            unresolvedItemNames,
+            replayedSession,
+            sessionExport,
+            decisions: sessionExport.decisions,
+            results: sessionExport.results,
+        };
+    }
+    return {
+        ok: true,
+        issues: [],
+        unresolvedItemNames,
+        replayedSession,
+        sessionExport,
+        decisions: sessionExport.decisions,
+        results: sessionExport.results,
+    };
+}
 export function createInMemoryReviewSessionEventStore(initialEvents = []) {
     let savedEvents = [...initialEvents];
     return {

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

@@ -0,0 +1,56 @@
+import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
+import type { ReviewSessionEvent } from "../review-resource.js";
+import type { ReviewQueueSessionState } from "./review-queue-session.js";
+export interface ServerReviewSessionRecord {
+    readonly sessionName: string;
+    readonly snapshot: ReviewQueueSessionState;
+    readonly snapshotHash: string;
+    readonly eventCount?: number;
+    readonly updatedAt: string;
+}
+export type ServerReviewSessionFreshnessStatus = "current" | "stale";
+export interface ServerReviewSessionFreshnessComparison {
+    readonly status: ServerReviewSessionFreshnessStatus;
+    readonly expectedSnapshotHash: string;
+    readonly actualSnapshotHash: string;
+    readonly expectedEventCount?: number;
+    readonly actualEventCount?: number;
+}
+export type ServerReviewSessionStaleIssueCode = "snapshot-hash-mismatch" | "event-count-mismatch";
+export interface ServerReviewSessionStaleIssue {
+    readonly code: ServerReviewSessionStaleIssueCode;
+    readonly message: string;
+    readonly expected: string | number;
+    readonly actual: string | number;
+}
+export declare class StaleServerReviewSessionError extends Error {
+    readonly name = "StaleServerReviewSessionError";
+    readonly issues: readonly ServerReviewSessionStaleIssue[];
+    readonly comparison: ServerReviewSessionFreshnessComparison;
+    constructor(comparison: ServerReviewSessionFreshnessComparison);
+}
+export type ServerReviewSessionEventValidationIssue = ReviewSessionReplayIssue | {
+    readonly code: "session-name-mismatch";
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly expectedSessionName: string;
+    readonly actualSessionName: string;
+    readonly message: string;
+};
+export declare class ServerReviewSessionEventValidationError extends Error {
+    readonly name = "ServerReviewSessionEventValidationError";
+    readonly issues: readonly ServerReviewSessionEventValidationIssue[];
+    constructor(issues: readonly ServerReviewSessionEventValidationIssue[]);
+}
+export interface CreateServerReviewSessionRecordOptions {
+    readonly sessionName: string;
+    readonly snapshot: ReviewQueueSessionState;
+    readonly eventCount?: number;
+    readonly updatedAt?: string | Date;
+}
+export declare function createServerReviewSessionRecord(options: CreateServerReviewSessionRecordOptions): ServerReviewSessionRecord;
+export declare function hashReviewSessionSnapshot(snapshot: ReviewQueueSessionState): string;
+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[];
+export declare function assertServerReviewSessionEvents(record: ServerReviewSessionRecord, events: readonly ReviewSessionEvent[]): void;

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

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+export class StaleServerReviewSessionError extends Error {
+    name = "StaleServerReviewSessionError";
+    issues;
+    comparison;
+    constructor(comparison) {
+        const issues = staleIssuesForComparison(comparison);
+        super(`Review session is stale: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+        this.comparison = comparison;
+    }
+}
+export class ServerReviewSessionEventValidationError extends Error {
+    name = "ServerReviewSessionEventValidationError";
+    issues;
+    constructor(issues) {
+        super(`Review session events are invalid: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+    }
+}
+export function createServerReviewSessionRecord(options) {
+    return {
+        sessionName: options.sessionName,
+        snapshot: options.snapshot,
+        snapshotHash: hashReviewSessionSnapshot(options.snapshot),
+        eventCount: options.eventCount,
+        updatedAt: isoTimestamp(options.updatedAt ?? new Date()),
+    };
+}
+export function hashReviewSessionSnapshot(snapshot) {
+    return sha256(canonicalJson(snapshot));
+}
+export function compareServerReviewSessionFreshness(record, snapshot, eventCount) {
+    const actualSnapshotHash = hashReviewSessionSnapshot(snapshot);
+    const eventCountMatches = record.eventCount === undefined || eventCount === undefined || record.eventCount === eventCount;
+    const current = record.snapshotHash === actualSnapshotHash && eventCountMatches;
+    return {
+        status: current ? "current" : "stale",
+        expectedSnapshotHash: record.snapshotHash,
+        actualSnapshotHash,
+        expectedEventCount: record.eventCount,
+        actualEventCount: eventCount,
+    };
+}
+export function assertServerReviewSessionFreshness(record, snapshot, eventCount) {
+    const comparison = compareServerReviewSessionFreshness(record, snapshot, eventCount);
+    if (comparison.status === "stale") {
+        throw new StaleServerReviewSessionError(comparison);
+    }
+}
+export function validateServerReviewSessionEvents(record, events) {
+    const replayIssues = validateReviewSessionEventsForSnapshot(record.snapshot, events);
+    const sessionIssues = events.flatMap((event) => {
+        if (event.spec.sessionName === record.sessionName) {
+            return [];
+        }
+        return [{
+                code: "session-name-mismatch",
+                eventName: event.metadata.name,
+                sequence: event.spec.sequence,
+                expectedSessionName: record.sessionName,
+                actualSessionName: event.spec.sessionName,
+                message: `ReviewSessionEvent ${event.metadata.name} references session ${event.spec.sessionName}, but the server session is ${record.sessionName}.`,
+            }];
+    });
+    return [...sessionIssues, ...replayIssues];
+}
+export function assertServerReviewSessionEvents(record, events) {
+    const issues = validateServerReviewSessionEvents(record, events);
+    if (issues.length > 0) {
+        throw new ServerReviewSessionEventValidationError(issues);
+    }
+}
+function staleIssuesForComparison(comparison) {
+    const issues = [];
+    if (comparison.expectedSnapshotHash !== comparison.actualSnapshotHash) {
+        issues.push({
+            code: "snapshot-hash-mismatch",
+            expected: comparison.expectedSnapshotHash,
+            actual: comparison.actualSnapshotHash,
+            message: `Expected snapshot hash ${comparison.expectedSnapshotHash}, received ${comparison.actualSnapshotHash}.`,
+        });
+    }
+    if (comparison.expectedEventCount !== undefined
+        && comparison.actualEventCount !== undefined
+        && comparison.expectedEventCount !== comparison.actualEventCount) {
+        issues.push({
+            code: "event-count-mismatch",
+            expected: comparison.expectedEventCount,
+            actual: comparison.actualEventCount,
+            message: `Expected ${comparison.expectedEventCount} events, received ${comparison.actualEventCount}.`,
+        });
+    }
+    return issues;
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalize(entry));
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return Object.fromEntries(entries.map(([key, entryValue]) => [key, canonicalize(entryValue)]));
+    }
+    return value;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function isoTimestamp(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.17",
+  "version": "0.4.20",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,10 @@
       "types": "./dist/src/review-workbench/review-workbench.d.ts",
       "default": "./dist/src/review-workbench/review-workbench.js"
     },
+    "./review-workbench/server-review-session": {
+      "types": "./dist/src/review-workbench/server-review-session.d.ts",
+      "default": "./dist/src/review-workbench/server-review-session.js"
+    },
     "./review-workbench.css": "./dist/src/review-workbench/review-workbench.css",
     "./review-workbench/standalone.css": "./dist/src/review-workbench/review-workbench.standalone.css",
     "./fixtures/public-field-review": "./dist/fixtures/public-field-review.js",