@kontourai/survey 0.4.8 → 0.4.9

package/README.md

@@ -87,6 +87,16 @@ application's `body` or `:root` styles. Hosts should mount into an element like:
 The package also exposes `@kontourai/survey/review-workbench/standalone.css` for
 the standalone demo page. Use that only when Survey owns the whole page.
 
+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
+browser-computed decisions or exported result payloads.
+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).
+
 ## Contributor checks
 
 Install the repo-owned Git hooks once per clone:

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

@@ -9,6 +9,15 @@ 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;
+    readonly message: string;
+}
 export interface ReviewSessionEventStore {
     load(session: ReviewQueueSessionState): readonly ReviewSessionEvent[] | undefined;
     save(session: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): void;
@@ -54,6 +63,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 createInMemoryReviewSessionEventStore(initialEvents?: readonly ReviewSessionEvent[]): ReviewSessionEventStore & {
     events(): readonly ReviewSessionEvent[];
 };

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

@@ -89,6 +89,60 @@ 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) {
+        throw new Error(`Review session events do not match the supplied session snapshot: ${issues.map((issue) => issue.message).join(" ")}`);
+    }
+    return replayReviewSessionEvents(snapshot, events);
+}
+export function buildReviewWorkbenchSessionExportForSnapshot(snapshot, events) {
+    const replayedSession = replayReviewSessionEventsForSnapshot(snapshot, events);
+    return buildReviewWorkbenchSessionExport(replayedSession, events);
+}
 export function createInMemoryReviewSessionEventStore(initialEvents = []) {
     let savedEvents = [...initialEvents];
     return {

package/package.json

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