@kontourai/survey 0.4.16 → 0.4.19

package/README.md

@@ -70,10 +70,20 @@ Survey also exposes a framework-neutral review workbench for downstream
 products that already produce `ReviewItem` queues.
 
 ```ts
-import { mountReviewWorkbench } from "@kontourai/survey/review-workbench";
+import {
+  mountReviewWorkbench,
+  type ReviewPresentationAdapter,
+} from "@kontourai/survey/review-workbench";
 import "@kontourai/survey/review-workbench.css";
 
-mountReviewWorkbench(element, reviewQueueSession);
+const presentationAdapter = {
+  labelForTarget: (target) => target === "registrationStatus"
+    ? "Registration status"
+    : undefined,
+  linkForReviewItem: (item) => ({ href: `/review/${item.metadata.name}` }),
+} satisfies ReviewPresentationAdapter;
+
+mountReviewWorkbench(element, reviewQueueSession, { presentationAdapter });
 ```
 
 The default stylesheet is scoped to `.survey-workbench-embed` and bundles the
@@ -93,6 +103,13 @@ 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,
+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
 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

@@ -0,0 +1,19 @@
+import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.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 reviewedSnapshot: ReturnType<typeof initialReviewQueueSessionState>;
+    readonly eventsToPersist: readonly ReviewSessionEvent[];
+    readonly persistedEvents: readonly ReviewSessionEvent[];
+    readonly persistedEventCount: number;
+    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

@@ -0,0 +1,116 @@
+import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.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"
+        : undefined,
+    labelForCandidateRole: (role) => role === "current"
+        ? "Current managed credential"
+        : role === "proposed"
+            ? "Registry candidate"
+            : undefined,
+    summarizeValue: (value) => {
+        if (!isCredentialValue(value)) {
+            return undefined;
+        }
+        const serviceSummary = value.permittedServices.length === 0
+            ? "no listed services"
+            : value.permittedServices.join(", ");
+        return `${value.licenseNumber} is ${value.status} through ${value.expiresAt}; services: ${serviceSummary}`;
+    },
+    linkForReviewItem: (item) => ({
+        label: typeof item.metadata.producer?.displayName === "string"
+            ? item.metadata.producer.displayName
+            : "Review item",
+        href: `/review/items/${encodeURIComponent(item.metadata.name)}`,
+    }),
+    linkForSource: (sourceRef, { candidate }) => ({
+        label: candidate.role === "current" ? "Managed record" : "Registry source",
+        href: sourceRef.startsWith("http") ? sourceRef : `/sources/${encodeURIComponent(sourceRef)}`,
+    }),
+    linkForTraceRef: (ref) => {
+        if (ref.kind === "claim") {
+            return {
+                label: "Claim target",
+                href: `/claims/${encodeURIComponent(ref.value)}`,
+            };
+        }
+        if (ref.kind === "candidate-set") {
+            return {
+                label: "Candidate set",
+                href: `/candidate-sets/${encodeURIComponent(ref.value)}`,
+            };
+        }
+        return undefined;
+    },
+};
+export async function buildFacilityCredentialConsumerExample() {
+    const reviewedSnapshot = {
+        ...initialReviewQueueSessionState([facilityCredentialReviewItemFixture]),
+        actorId: "review-operator@example.test",
+        reviewedAt: "2026-01-17T16:15:00.000Z",
+        decisionsByItemName: {
+            [facilityCredentialReviewItemFixture.metadata.name]: "accept-proposed",
+        },
+        notesByItemName: {
+            [facilityCredentialReviewItemFixture.metadata.name]: "Registry credential supersedes the managed snapshot.",
+        },
+    };
+    const eventsToPersist = buildReviewSessionEvents(reviewedSnapshot);
+    const persistedEvents = [];
+    const persisted = await persistReviewSessionEvents({
+        session: reviewedSnapshot,
+        events: eventsToPersist,
+        expectedEventCount: persistedEvents.length,
+        persist: async ({ events, expectedEventCount }) => {
+            if (expectedEventCount !== persistedEvents.length) {
+                throw new Error(`Expected ${expectedEventCount} persisted events, found ${persistedEvents.length}.`);
+            }
+            persistedEvents.splice(0, persistedEvents.length, ...events);
+            return { eventCount: persistedEvents.length };
+        },
+    });
+    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.");
+    }
+    const itemPresentation = buildReviewItemPresentation(facilityCredentialReviewItemFixture, facilityCredentialPresentationAdapter);
+    const resultPresentation = buildReviewResultPresentation(result, facilityCredentialReviewItemFixture, facilityCredentialPresentationAdapter);
+    const surfaceProjectionPreview = buildSurfaceProjectionPreview(facilityCredentialReviewItemFixture, result.reviewDecision, facilityCredentialPresentationAdapter);
+    if (!surfaceProjectionPreview) {
+        throw new Error("Expected the reviewed credential result to produce a Surface projection preview.");
+    }
+    return {
+        reviewItem: facilityCredentialReviewItemFixture,
+        reviewedSnapshot,
+        eventsToPersist,
+        persistedEvents: persisted.events,
+        persistedEventCount: persisted.eventCount,
+        applyResult,
+        itemPresentation,
+        resultPresentation,
+        surfaceProjectionPreview,
+    };
+}
+export const facilityCredentialConsumerExample = await buildFacilityCredentialConsumerExample();
+function isCredentialValue(value) {
+    return typeof value === "object"
+        && value !== null
+        && "licenseNumber" in value
+        && typeof value.licenseNumber === "string"
+        && "status" in value
+        && typeof value.status === "string"
+        && "expiresAt" in value
+        && typeof value.expiresAt === "string"
+        && "permittedServices" in value
+        && Array.isArray(value.permittedServices)
+        && value.permittedServices.every((service) => typeof service === "string");
+}

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;
@@ -36,8 +67,19 @@ export interface ReviewSessionPersistenceRequest {
     readonly expectedEventCount: number;
 }
 export interface ReviewSessionPersistenceResult {
+    readonly events?: readonly ReviewSessionEvent[];
     readonly eventCount?: number;
 }
+export interface PersistReviewSessionEventsOptions {
+    readonly session: ReviewQueueSessionState;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly expectedEventCount?: number;
+    readonly persist: (request: ReviewSessionPersistenceRequest) => Promise<ReviewSessionPersistenceResult | void>;
+}
+export interface PersistReviewSessionEventsResult {
+    readonly events: readonly ReviewSessionEvent[];
+    readonly eventCount: number;
+}
 export interface PersistentReviewSessionEventStoreOptions {
     readonly initialEvents?: readonly ReviewSessionEvent[];
     readonly persist: (request: ReviewSessionPersistenceRequest) => Promise<ReviewSessionPersistenceResult | void>;
@@ -69,10 +111,12 @@ 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[];
 };
 export declare function createLocalStorageReviewSessionEventStore(storage: Pick<Storage, "getItem" | "setItem">, keyPrefix?: string): ReviewSessionEventStore;
+export declare function persistReviewSessionEvents(options: PersistReviewSessionEventsOptions): Promise<PersistReviewSessionEventsResult>;
 export declare function createPersistentReviewSessionEventStore(options: PersistentReviewSessionEventStoreOptions): 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 {
@@ -175,6 +279,19 @@ export function createLocalStorageReviewSessionEventStore(storage, keyPrefix = r
         },
     };
 }
+export async function persistReviewSessionEvents(options) {
+    const events = [...options.events];
+    const result = await options.persist({
+        session: options.session,
+        events,
+        expectedEventCount: options.expectedEventCount ?? 0,
+    });
+    const persistedEvents = result?.events ? [...result.events] : events;
+    return {
+        events: persistedEvents,
+        eventCount: result?.eventCount ?? persistedEvents.length,
+    };
+}
 export function createPersistentReviewSessionEventStore(options) {
     let savedEvents = [...(options.initialEvents ?? [])];
     let lastPersistedSerialized = JSON.stringify(savedEvents);
@@ -198,15 +315,16 @@ export function createPersistentReviewSessionEventStore(options) {
                     return;
                 }
                 emit({ status: "saving", events: normalizedEvents });
-                const result = await options.persist({
+                const result = await persistReviewSessionEvents({
                     session,
                     events: normalizedEvents,
                     expectedEventCount: lastPersistedEventCount,
+                    persist: options.persist,
                 });
-                savedEvents = normalizedEvents;
-                lastPersistedSerialized = serialized;
-                lastPersistedEventCount = result?.eventCount ?? normalizedEvents.length;
-                emit({ status: "saved", events: normalizedEvents });
+                savedEvents = result.events;
+                lastPersistedSerialized = JSON.stringify(result.events);
+                lastPersistedEventCount = result.eventCount;
+                emit({ status: "saved", events: result.events });
             })
                 .catch((error) => {
                 emit({ status: "error", events: normalizedEvents, error });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.16",
+  "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",