@kontourai/survey 0.4.21 → 0.4.22

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

@@ -1,7 +1,7 @@
 import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
-import { type ReviewCandidate, type ReviewDecision, type ReviewSession, type ReviewSessionEvent } from "../review-resource.js";
+import { type ReviewCandidate, type ReviewDecision, type ReviewItem, 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 { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
@@ -98,7 +98,60 @@ export interface ReviewWorkbenchResult {
     readonly status: ReviewDecision["spec"]["status"];
     readonly rationale?: string;
 }
+export interface ReviewApplyResultExpectation {
+    readonly decision?: ReviewWorkbenchDecision;
+    readonly status?: ReviewDecision["spec"]["status"];
+    readonly selectedCandidateRole?: ReviewCandidate["role"];
+    readonly selectedCandidateId?: string;
+    readonly selectedValue?: unknown;
+    readonly equals?: (left: unknown, right: unknown) => boolean;
+}
+export interface ReviewApplyActionMapping<TAction> {
+    readonly result: ReviewWorkbenchResult;
+    readonly item: ReviewItem;
+    readonly action: TAction;
+}
+export type ReviewApplyActionIssue = {
+    readonly code: "unknown-review-item";
+    readonly reviewItemName: string;
+    readonly message: string;
+} | {
+    readonly code: "duplicate-review-target";
+    readonly target: string;
+    readonly message: string;
+} | {
+    readonly code: "selected-candidate-mismatch";
+    readonly reviewItemName: string;
+    readonly message: string;
+} | {
+    readonly code: "unmapped-review-result";
+    readonly reviewItemName: string;
+    readonly message: string;
+};
+export declare class ReviewApplyActionMappingError extends Error {
+    readonly name = "ReviewApplyActionMappingError";
+    readonly issues: readonly ReviewApplyActionIssue[];
+    constructor(issues: readonly ReviewApplyActionIssue[]);
+}
+export interface ReviewApplyActionContext {
+    readonly result: ReviewWorkbenchResult;
+    readonly item: ReviewItem;
+    readonly target: ReviewItem["spec"]["target"];
+    readonly selectedCandidate: ReviewCandidate;
+    readonly unselectedCandidates: readonly ReviewCandidate[];
+}
+export interface MapReviewWorkbenchResultsToApplyActionsOptions<TAction> {
+    readonly results: readonly ReviewWorkbenchResult[];
+    readonly items: readonly ReviewItem[];
+    readonly requireUniqueTargets?: boolean;
+    readonly skip?: (context: ReviewApplyActionContext) => boolean;
+    readonly map: (context: ReviewApplyActionContext) => TAction | readonly TAction[] | undefined;
+}
 export declare function buildReviewDecisionsFromSession(session: ReviewQueueSessionState): ReviewDecision[];
+export declare function requireReviewResultForItem(item: ReviewItem, results: readonly ReviewWorkbenchResult[]): ReviewWorkbenchResult;
+export declare function assertReviewResultMatches(result: ReviewWorkbenchResult, expectation: ReviewApplyResultExpectation): void;
+export declare function mapReviewWorkbenchResultsToApplyActions<TAction>(options: MapReviewWorkbenchResultsToApplyActionsOptions<TAction>): ReviewApplyActionMapping<TAction>[];
+export declare const mapReviewApplyActions: typeof mapReviewWorkbenchResultsToApplyActions;
 export declare function buildReviewWorkbenchResultsFromSession(session: ReviewQueueSessionState): ReviewWorkbenchResult[];
 export declare function buildReviewWorkbenchSessionExport(session: ReviewQueueSessionState, events?: readonly ReviewSessionEvent[]): ReviewWorkbenchSessionExport;
 export declare function replayReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;

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

@@ -42,6 +42,14 @@ export function buildReviewDecision(state) {
         },
     };
 }
+export class ReviewApplyActionMappingError extends Error {
+    name = "ReviewApplyActionMappingError";
+    issues;
+    constructor(issues) {
+        super(`Review apply action mapping failed: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+    }
+}
 export function buildReviewDecisionsFromSession(session) {
     return session.items.flatMap((item) => {
         const decision = session.decisionsByItemName[item.metadata.name];
@@ -55,6 +63,116 @@ export function buildReviewDecisionsFromSession(session) {
         return reviewDecision ? [reviewDecision] : [];
     });
 }
+export function requireReviewResultForItem(item, results) {
+    const matching = results.filter((result) => result.reviewItemName === item.metadata.name);
+    if (matching.length !== 1) {
+        throw new Error(`Expected exactly one resolved Survey result for ${item.metadata.name}.`);
+    }
+    return matching[0];
+}
+export function assertReviewResultMatches(result, expectation) {
+    if (expectation.decision && result.decision !== expectation.decision) {
+        throw new Error(`Review result ${result.reviewItemName} has decision ${result.decision}; expected ${expectation.decision}.`);
+    }
+    if (expectation.status && result.status !== expectation.status) {
+        throw new Error(`Review result ${result.reviewItemName} has status ${result.status}; expected ${expectation.status}.`);
+    }
+    if (expectation.selectedCandidateRole && result.selectedCandidateRole !== expectation.selectedCandidateRole) {
+        throw new Error(`Review result ${result.reviewItemName} selected ${result.selectedCandidateRole ?? "unknown"} candidate; expected ${expectation.selectedCandidateRole}.`);
+    }
+    if (expectation.selectedCandidateId && result.selectedCandidateId !== expectation.selectedCandidateId) {
+        throw new Error(`Review result ${result.reviewItemName} selected candidate ${result.selectedCandidateId}; expected ${expectation.selectedCandidateId}.`);
+    }
+    if ("selectedValue" in expectation) {
+        const equals = expectation.equals ?? Object.is;
+        if (!equals(result.selectedValue, expectation.selectedValue)) {
+            throw new Error(`Review result ${result.reviewItemName} selected value does not match the expected value.`);
+        }
+    }
+}
+export function mapReviewWorkbenchResultsToApplyActions(options) {
+    const issues = [];
+    const itemByName = new Map(options.items.map((item) => [item.metadata.name, item]));
+    if (options.requireUniqueTargets) {
+        const seenTargets = new Set();
+        for (const item of options.items) {
+            if (seenTargets.has(item.spec.target)) {
+                issues.push({
+                    code: "duplicate-review-target",
+                    target: item.spec.target,
+                    message: `Review target ${item.spec.target} appears on more than one ReviewItem.`,
+                });
+            }
+            seenTargets.add(item.spec.target);
+        }
+    }
+    const mappings = options.results.flatMap((result) => {
+        const item = itemByName.get(result.reviewItemName);
+        if (!item) {
+            issues.push({
+                code: "unknown-review-item",
+                reviewItemName: result.reviewItemName,
+                message: `Review result ${result.reviewItemName} does not reference a known ReviewItem.`,
+            });
+            return [];
+        }
+        const selectedCandidate = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        if (!selectedCandidate
+            || selectedCandidate.role !== result.selectedCandidateRole
+            || !structuralEqual(selectedCandidate.value, result.selectedValue)) {
+            issues.push({
+                code: "selected-candidate-mismatch",
+                reviewItemName: result.reviewItemName,
+                message: `Review result ${result.reviewItemName} selected candidate does not match the supplied ReviewItem.`,
+            });
+            return [];
+        }
+        const context = {
+            result,
+            item,
+            target: item.spec.target,
+            selectedCandidate,
+            unselectedCandidates: item.spec.candidates.filter((candidate) => candidate.id !== selectedCandidate.id),
+        };
+        if (options.skip?.(context)) {
+            return [];
+        }
+        const action = options.map(context);
+        if (action === undefined) {
+            issues.push({
+                code: "unmapped-review-result",
+                reviewItemName: result.reviewItemName,
+                message: `Review result ${result.reviewItemName} did not produce an apply action.`,
+            });
+            return [];
+        }
+        return (Array.isArray(action) ? action : [action]).map((entry) => ({
+            result,
+            item,
+            action: entry,
+        }));
+    });
+    if (issues.length > 0) {
+        throw new ReviewApplyActionMappingError(issues);
+    }
+    return mappings;
+}
+export const mapReviewApplyActions = mapReviewWorkbenchResultsToApplyActions;
+function structuralEqual(left, right) {
+    return JSON.stringify(canonicalJson(left)) === JSON.stringify(canonicalJson(right));
+}
+function canonicalJson(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(canonicalJson);
+    }
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, canonicalJson(entry)]));
+}
 export function buildReviewWorkbenchResultsFromSession(session) {
     return session.items.flatMap((item) => {
         const decision = session.decisionsByItemName[item.metadata.name];

package/package.json

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