@kontourai/survey 0.4.17 → 0.4.19

package/README.md

@@ -103,8 +103,11 @@ review events, exported results, and optional Surface projection, see
 That guide also covers the server-side apply boundary: producers should derive
 write results from reviewed 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.
+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 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).
 For the current decision on why Survey is not adding a generic review adapter

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

@@ -1,5 +1,5 @@
 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>;
@@ -10,7 +10,9 @@ export interface FacilityCredentialConsumerExample {
     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"
@@ -70,8 +70,15 @@ export async function buildFacilityCredentialConsumerExample() {
             return { eventCount: persistedEvents.length };
         },
     });
-    const sessionExport = buildReviewWorkbenchSessionExportForSnapshot(reviewedSnapshot, persisted.events);
-    const [result] = sessionExport.results;
+    const applyResult = deriveReviewSessionApplyResultForSnapshot({
+        snapshot: reviewedSnapshot,
+        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.");
     }
@@ -87,7 +94,7 @@ export async function buildFacilityCredentialConsumerExample() {
         eventsToPersist,
         persistedEvents: persisted.events,
         persistedEventCount: persisted.eventCount,
-        sessionExport,
+        applyResult,
         itemPresentation,
         resultPresentation,
         surfaceProjectionPreview,

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

@@ -11,7 +11,7 @@ export interface ReviewWorkbenchSessionExport {
     readonly decisions: readonly ReviewDecision[];
     readonly results: readonly ReviewWorkbenchResult[];
 }
-export type ReviewSessionReplayIssueCode = "unknown-active-item" | "unknown-review-item" | "unknown-candidate";
+export type ReviewSessionReplayIssueCode = "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;
@@ -20,6 +20,37 @@ export interface ReviewSessionReplayIssue {
     readonly candidateId?: string;
     readonly message: 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;
@@ -80,6 +111,7 @@ export declare function buildReviewWorkbenchSessionExport(session: ReviewQueueSe
 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

@@ -118,6 +118,52 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                 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);
@@ -134,6 +180,11 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
         return issues;
     });
 }
+function replayableWorkbenchDecision(value) {
+    return typeof value === "string" && value in workbenchDecisionDefinitions
+        ? value
+        : undefined;
+}
 export function replayReviewSessionEventsForSnapshot(snapshot, events) {
     const issues = validateReviewSessionEventsForSnapshot(snapshot, events);
     if (issues.length > 0) {
@@ -145,6 +196,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",