@kontourai/survey 0.4.7 → 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-surface-preview.js

@@ -15,7 +15,24 @@ export function buildSurfaceProjectionPreview(item, decision) {
     };
 }
 export function formatValue(value) {
-    return typeof value === "string" ? value : JSON.stringify(value);
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value === undefined) {
+        return "";
+    }
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
 }
 function selectedPreviewCandidate(item, decision) {
     if (!decision?.spec.candidateId) {

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

@@ -1,5 +1,5 @@
-import { type ReviewQueueSessionState, type ReviewWorkbenchState } from "./review-queue-session.js";
-import { type ReviewDecision, type ReviewSession, type ReviewSessionEvent } from "../review-resource.js";
+import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.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 { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
 export declare function buildReviewDecision(state: ReviewWorkbenchState): ReviewDecision | undefined;
@@ -7,23 +7,72 @@ export interface ReviewWorkbenchSessionExport {
     readonly session: ReviewSession;
     readonly events: readonly ReviewSessionEvent[];
     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;
 }
+export type ReviewSessionPersistenceStatus = "idle" | "saving" | "saved" | "error";
+export interface ReviewSessionPersistenceState {
+    readonly status: ReviewSessionPersistenceStatus;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly error?: unknown;
+}
+export interface ReviewSessionPersistenceRequest {
+    readonly session: ReviewQueueSessionState;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly expectedEventCount: number;
+}
+export interface ReviewSessionPersistenceResult {
+    readonly eventCount?: number;
+}
+export interface PersistentReviewSessionEventStoreOptions {
+    readonly initialEvents?: readonly ReviewSessionEvent[];
+    readonly persist: (request: ReviewSessionPersistenceRequest) => Promise<ReviewSessionPersistenceResult | void>;
+    readonly onStatusChange?: (state: ReviewSessionPersistenceState) => void;
+}
 export interface MountReviewWorkbenchOptions {
     readonly eventStore?: ReviewSessionEventStore;
 }
 export interface BrowserReviewWorkbenchConfig {
     readonly startState?: ReviewQueueSessionState | ReviewWorkbenchState;
 }
+export interface ReviewWorkbenchResult {
+    readonly reviewItemName: string;
+    readonly decision: ReviewWorkbenchDecision;
+    readonly selectedCandidate: ReviewCandidate;
+    readonly selectedCandidateId: string;
+    readonly selectedCandidateRole?: ReviewCandidate["role"];
+    readonly selectedValue: unknown;
+    readonly selectedDisplayValue: string;
+    readonly unselectedCandidates: readonly ReviewCandidate[];
+    readonly reviewDecision: ReviewDecision;
+    readonly status: ReviewDecision["spec"]["status"];
+    readonly rationale?: string;
+}
 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[];
 };
 export declare function createLocalStorageReviewSessionEventStore(storage: Pick<Storage, "getItem" | "setItem">, keyPrefix?: string): ReviewSessionEventStore;
+export declare function createPersistentReviewSessionEventStore(options: PersistentReviewSessionEventStoreOptions): ReviewSessionEventStore & {
+    events(): readonly ReviewSessionEvent[];
+};
 export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, events?: readonly ReviewSessionEvent[]): string;
 export declare function mountReviewWorkbench(root: HTMLElement, startState?: ReviewQueueSessionState | ReviewWorkbenchState, options?: MountReviewWorkbenchOptions): void;
 export declare function browserReviewWorkbenchStartState(): ReviewQueueSessionState | ReviewWorkbenchState | undefined;

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

@@ -51,13 +51,98 @@ export function buildReviewDecisionsFromSession(session) {
         return reviewDecision ? [reviewDecision] : [];
     });
 }
+export function buildReviewWorkbenchResultsFromSession(session) {
+    return session.items.flatMap((item) => {
+        const decision = session.decisionsByItemName[item.metadata.name];
+        if (!decision) {
+            return [];
+        }
+        const state = currentReviewWorkbenchState({
+            ...session,
+            activeItemName: item.metadata.name,
+        });
+        const reviewDecision = buildReviewDecision(state);
+        if (!reviewDecision) {
+            return [];
+        }
+        const selectedCandidate = candidateForDecision(item, decision);
+        return [{
+                reviewItemName: item.metadata.name,
+                decision,
+                selectedCandidate,
+                selectedCandidateId: selectedCandidate.id,
+                selectedCandidateRole: selectedCandidate.role,
+                selectedValue: selectedCandidate.value,
+                selectedDisplayValue: formatValue(selectedCandidate.value),
+                unselectedCandidates: item.spec.candidates.filter((candidate) => candidate.id !== selectedCandidate.id),
+                reviewDecision,
+                status: reviewDecision.spec.status,
+                rationale: reviewDecision.spec.rationale,
+            }];
+    });
+}
 export function buildReviewWorkbenchSessionExport(session, events = buildReviewSessionEvents(session)) {
     return {
         session: buildReviewSessionResource(session, events),
         events,
         decisions: buildReviewDecisionsFromSession(session),
+        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 {
@@ -88,6 +173,45 @@ export function createLocalStorageReviewSessionEventStore(storage, keyPrefix = r
         },
     };
 }
+export function createPersistentReviewSessionEventStore(options) {
+    let savedEvents = [...(options.initialEvents ?? [])];
+    let lastPersistedSerialized = JSON.stringify(savedEvents);
+    let lastPersistedEventCount = savedEvents.length;
+    let pendingSave = Promise.resolve();
+    const emit = (state) => {
+        options.onStatusChange?.(state);
+    };
+    return {
+        events: () => [...savedEvents],
+        load: () => savedEvents.length > 0 ? [...savedEvents] : undefined,
+        save: (session, events) => {
+            const normalizedEvents = [...events];
+            const serialized = JSON.stringify(normalizedEvents);
+            if (serialized === lastPersistedSerialized) {
+                return;
+            }
+            pendingSave = pendingSave
+                .then(async () => {
+                if (serialized === lastPersistedSerialized) {
+                    return;
+                }
+                emit({ status: "saving", events: normalizedEvents });
+                const result = await options.persist({
+                    session,
+                    events: normalizedEvents,
+                    expectedEventCount: lastPersistedEventCount,
+                });
+                savedEvents = normalizedEvents;
+                lastPersistedSerialized = serialized;
+                lastPersistedEventCount = result?.eventCount ?? normalizedEvents.length;
+                emit({ status: "saved", events: normalizedEvents });
+            })
+                .catch((error) => {
+                emit({ status: "error", events: normalizedEvents, error });
+            });
+        },
+    };
+}
 export function renderReviewWorkbenchHtml(state, events) {
     if ("items" in state) {
         return renderReviewQueueSessionHtml(state, events);
@@ -673,7 +797,7 @@ function refreshSessionAudit(root, session, sessionExport, renderCurrentState) {
 }
 function producerFeedbackTags(item) {
     const tags = item.spec.producerPolicy?.feedbackTags;
-    return Array.isArray(tags) ? tags.map(String) : [];
+    return Array.isArray(tags) ? tags.map(formatValue) : [];
 }
 function renderCandidateCard(candidate, state) {
     const selectedRole = selectedCandidateRole(state);
@@ -734,10 +858,11 @@ function formatConfidence(value) {
     return `${Math.round(value * 100)}% (${value.toFixed(2)})`;
 }
 function titleCase(value) {
-    return value.slice(0, 1).toUpperCase() + value.slice(1);
+    const displayValue = formatValue(value);
+    return displayValue.slice(0, 1).toUpperCase() + displayValue.slice(1);
 }
 function escapeHtml(value) {
-    return value
+    return formatValue(value)
         .replaceAll("&", "&")
         .replaceAll("<", "&lt;")
         .replaceAll(">", "&gt;")

package/package.json

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