@kontourai/survey 0.4.16 → 0.4.17

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,10 @@ 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.
+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,17 @@
+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 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 sessionExport: ReturnType<typeof buildReviewWorkbenchSessionExportForSnapshot>;
+    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,109 @@
+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";
+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 sessionExport = buildReviewWorkbenchSessionExportForSnapshot(reviewedSnapshot, persisted.events);
+    const [result] = sessionExport.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,
+        sessionExport,
+        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

@@ -36,8 +36,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>;
@@ -73,6 +84,7 @@ export declare function createInMemoryReviewSessionEventStore(initialEvents?: re
     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

@@ -175,6 +175,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 +211,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.17",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",