@kontourai/survey 0.4.3 → 0.4.4

package/dist/examples/review-workbench/review-queue-session.js

@@ -0,0 +1,122 @@
+import { publicDirectoryReviewItemFixture, reviewWorkbenchQueueFixtures } from "./review-workbench-data.js";
+export const workbenchDecisionDefinitions = {
+    "accept-proposed": {
+        label: "Accept proposed",
+        effect: "Proposed value becomes the verified review outcome.",
+        candidateRole: "proposed",
+        status: "verified",
+    },
+    "keep-current": {
+        label: "Keep current",
+        effect: "Current value remains the verified review outcome.",
+        candidateRole: "current",
+        status: "verified",
+    },
+    "reject-proposed": {
+        label: "Reject proposed",
+        effect: "Proposed value is rejected and the current value remains unmodified.",
+        candidateRole: "proposed",
+        status: "rejected",
+    },
+};
+export function initialReviewWorkbenchState(item = publicDirectoryReviewItemFixture) {
+    return {
+        item,
+        note: "",
+        decision: undefined,
+        reviewedAt: "2026-06-04T00:00:00.000Z",
+        actorId: "review-workbench-operator",
+    };
+}
+export function initialReviewQueueSessionState(items = reviewWorkbenchQueueFixtures) {
+    return {
+        items,
+        activeItemName: items[0]?.metadata.name ?? "",
+        notesByItemName: {},
+        decisionsByItemName: {},
+        reviewedAt: "2026-06-04T00:00:00.000Z",
+        actorId: "review-workbench-operator",
+    };
+}
+export function currentReviewWorkbenchState(session) {
+    const item = currentReviewItem(session);
+    return {
+        item,
+        note: session.notesByItemName[item.metadata.name] ?? "",
+        decision: session.decisionsByItemName[item.metadata.name],
+        reviewedAt: session.reviewedAt,
+        actorId: session.actorId,
+    };
+}
+export function currentReviewItem(session) {
+    const item = session.items.find((entry) => entry.metadata.name === session.activeItemName) ?? session.items[0];
+    if (!item) {
+        throw new Error("Review queue session has no ReviewItems.");
+    }
+    return item;
+}
+export function deriveQueueRowStatus(item, session) {
+    const decision = session.decisionsByItemName[item.metadata.name];
+    if (decision === "reject-proposed") {
+        return "rejected";
+    }
+    if (decision === "accept-proposed" || decision === "keep-current" || item.spec.candidateSetStatus === "resolved") {
+        return "resolved";
+    }
+    if (item.spec.candidateSetStatus === "escalated") {
+        return "escalated";
+    }
+    if (item.metadata.name === session.activeItemName) {
+        return "in-review";
+    }
+    return "pending";
+}
+export function nextUnresolvedItemName(session) {
+    const activeIndex = session.items.findIndex((item) => item.metadata.name === session.activeItemName);
+    const orderedItems = [
+        ...session.items.slice(Math.max(activeIndex, 0) + 1),
+        ...session.items.slice(0, Math.max(activeIndex, 0) + 1),
+    ];
+    return orderedItems.find((item) => deriveQueueRowStatus(item, session) === "pending")?.metadata.name;
+}
+export function reviewSessionSummary(session) {
+    return session.items.reduce((summary, item) => {
+        const decision = session.decisionsByItemName[item.metadata.name];
+        if (decision === "accept-proposed") {
+            return { ...summary, accepted: summary.accepted + 1 };
+        }
+        if (decision === "keep-current") {
+            return { ...summary, keptCurrent: summary.keptCurrent + 1 };
+        }
+        if (decision === "reject-proposed") {
+            return { ...summary, rejected: summary.rejected + 1 };
+        }
+        if (item.spec.candidateSetStatus === "escalated") {
+            return { ...summary, escalated: summary.escalated + 1 };
+        }
+        if (item.spec.candidateSetStatus === "resolved") {
+            return { ...summary, accepted: summary.accepted + 1 };
+        }
+        return { ...summary, unresolved: summary.unresolved + 1 };
+    }, {
+        accepted: 0,
+        keptCurrent: 0,
+        rejected: 0,
+        escalated: 0,
+        unresolved: 0,
+    });
+}
+export function candidateForDecision(item, decision) {
+    const definition = workbenchDecisionDefinitions[decision];
+    const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);
+    if (!candidate) {
+        throw new Error(`ReviewItem ${item.metadata.name} has no ${definition.candidateRole} candidate.`);
+    }
+    return candidate;
+}
+export function selectedCandidateRole(state) {
+    if (!state.decision) {
+        return undefined;
+    }
+    return workbenchDecisionDefinitions[state.decision].candidateRole;
+}

package/dist/examples/review-workbench/review-surface-preview.d.ts

@@ -0,0 +1,55 @@
+import { type ReviewDecision, type ReviewItem } from "../../src/review-resource.js";
+export interface SurfaceProjectionPreview {
+    readonly canonicalClaim: PreviewClaim;
+    readonly candidateHistory: PreviewCandidateHistory[];
+    readonly sourceEvidence: PreviewSourceEvidence;
+    readonly reviewEvent?: PreviewReviewEvent;
+    readonly integrityPosture: PreviewIntegrityPosture;
+    readonly authorityTrace: PreviewAuthorityTrace;
+    readonly postureDisclaimer: string;
+}
+export interface PreviewClaim {
+    readonly candidateId: string;
+    readonly claimId: string;
+    readonly value: string;
+    readonly status: string;
+}
+export interface PreviewCandidateHistory {
+    readonly candidateId: string;
+    readonly value: string;
+    readonly historyLabel: string;
+}
+export interface PreviewSourceEvidence {
+    readonly sourceRef: string;
+    readonly sourceId: string;
+    readonly excerpt: string;
+    readonly extractionId: string;
+    readonly extractor: string;
+    readonly observedAt: string;
+    readonly sourceAuthority?: PreviewSourceAuthority;
+}
+export interface PreviewSourceAuthority {
+    readonly authorityClass: string;
+    readonly declaredBy: string;
+    readonly scope: string;
+}
+export interface PreviewReviewEvent {
+    readonly actor: string;
+    readonly reviewedAt: string;
+    readonly status: string;
+    readonly rationale: string;
+    readonly reviewOutcomeId: string;
+}
+export interface PreviewIntegrityPosture {
+    readonly candidateSetId: string;
+    readonly rawSourceId: string;
+    readonly extractionId: string;
+    readonly checksum: string;
+}
+export interface PreviewAuthorityTrace {
+    readonly status: "empty" | "provided";
+    readonly label: string;
+    readonly detail: string;
+}
+export declare function buildSurfaceProjectionPreview(item: ReviewItem, decision: ReviewDecision | undefined): SurfaceProjectionPreview | undefined;
+export declare function formatValue(value: unknown): string;

package/dist/examples/review-workbench/review-surface-preview.js

@@ -0,0 +1,104 @@
+export function buildSurfaceProjectionPreview(item, decision) {
+    const selectedCandidate = selectedPreviewCandidate(item, decision);
+    if (!selectedCandidate || !decision) {
+        return undefined;
+    }
+    const projection = decision.spec.projection ?? selectedCandidate.projection;
+    return {
+        canonicalClaim: buildPreviewClaim(selectedCandidate, decision, projection),
+        candidateHistory: buildCandidateHistory(item, selectedCandidate),
+        sourceEvidence: buildSourceEvidence(selectedCandidate),
+        reviewEvent: buildReviewEvent(decision, projection),
+        integrityPosture: buildIntegrityPosture(item, selectedCandidate, projection),
+        authorityTrace: portableAuthorityTrace(selectedCandidate.producer?.authorityTrace),
+        postureDisclaimer: postureDisclaimer(),
+    };
+}
+export function formatValue(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function selectedPreviewCandidate(item, decision) {
+    if (!decision?.spec.candidateId) {
+        return undefined;
+    }
+    const candidate = item.spec.candidates.find((entry) => entry.id === decision.spec.candidateId);
+    if (!candidate) {
+        throw new Error(`ReviewItem ${item.metadata.name} has no candidate ${decision.spec.candidateId}.`);
+    }
+    return candidate;
+}
+function buildPreviewClaim(candidate, decision, projection) {
+    return {
+        candidateId: candidate.id,
+        claimId: projection?.claimId ?? candidate.claimTarget.claimId ?? candidate.claimTarget.fieldOrBehavior,
+        value: formatValue(candidate.value),
+        status: decision.spec.status,
+    };
+}
+function buildCandidateHistory(item, selectedCandidate) {
+    return item.spec.candidates
+        .filter((candidate) => candidate.id !== selectedCandidate.id)
+        .map((candidate) => ({
+        candidateId: candidate.id,
+        value: formatValue(candidate.value),
+        historyLabel: "Unselected candidate history",
+    }));
+}
+function buildSourceEvidence(candidate) {
+    return {
+        sourceRef: candidate.source.sourceRef,
+        sourceId: candidate.source.sourceId ?? candidate.source.sourceRef,
+        excerpt: candidate.locator?.excerpt ?? "No source excerpt provided.",
+        extractionId: candidate.extraction.extractionId ?? "not provided",
+        extractor: candidate.extraction.extractor ?? "unknown",
+        observedAt: candidate.source.observedAt ?? candidate.source.fetchedAt ?? "unknown",
+        sourceAuthority: sourceAuthorityFromProducer(candidate.producer?.sourceAuthority),
+    };
+}
+function buildReviewEvent(decision, projection) {
+    return {
+        actor: decision.spec.actor?.id ?? "unknown",
+        reviewedAt: decision.spec.reviewedAt ?? "not recorded",
+        status: decision.spec.status,
+        rationale: decision.spec.rationale || "No reviewer rationale provided.",
+        reviewOutcomeId: projection?.reviewOutcomeId ?? "not provided",
+    };
+}
+function buildIntegrityPosture(item, candidate, projection) {
+    return {
+        candidateSetId: projection?.candidateSetId ?? item.spec.projection?.candidateSetId ?? "not provided",
+        rawSourceId: projection?.rawSourceId ?? candidate.source.sourceId ?? "not provided",
+        extractionId: projection?.extractionId ?? candidate.extraction.extractionId ?? "not provided",
+        checksum: candidate.source.checksum ?? "not provided",
+    };
+}
+function postureDisclaimer() {
+    return "Survey records source and review posture for projection; it does not validate real-world truth.";
+}
+function sourceAuthorityFromProducer(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        authorityClass: String(value.authorityClass ?? "not provided"),
+        declaredBy: String(value.declaredBy ?? "not provided"),
+        scope: String(value.scope ?? "not provided"),
+    };
+}
+function portableAuthorityTrace(value) {
+    if (Array.isArray(value) && value.length > 0) {
+        return {
+            status: "provided",
+            label: "Portable authority trace provided",
+            detail: `${value.length} authority trace entr${value.length === 1 ? "y" : "ies"} supplied by the fixture.`,
+        };
+    }
+    return {
+        status: "empty",
+        label: "Empty / not provided",
+        detail: "No portable authority trace is present. SourceAuthority metadata is shown as source evidence and is not promoted into authorityTrace.",
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/examples/review-workbench/review-workbench-data.d.ts

@@ -0,0 +1,261 @@
+import { type ReviewItem } from "../../src/review-resource.js";
+export declare const publicDirectoryReviewItemFixture: {
+    apiVersion: "survey.kontourai.io/v1alpha1";
+    kind: "ReviewItem";
+    metadata: {
+        name: string;
+        labels: {
+            domain: string;
+        };
+        producer: {
+            displayName: string;
+            slug: string;
+        };
+    };
+    spec: {
+        target: string;
+        selectedCandidateId: string;
+        candidateSetStatus: "resolved";
+        rationale: string;
+        candidates: ({
+            id: string;
+            role: "current";
+            value: string;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "web-page";
+                observedAt: string;
+                fetchedAt: string;
+                locatorScheme: "html";
+            };
+            locator: {
+                scheme: "html";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "medium";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                reviewOutcomeId: string;
+                claimId: string;
+            };
+            producer: {
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+                proposalId?: undefined;
+                oldValue?: undefined;
+            };
+        } | {
+            id: string;
+            role: "proposed";
+            value: string;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "web-page";
+                observedAt: string;
+                fetchedAt: string;
+                locatorScheme: "html";
+            };
+            locator: {
+                scheme: "html";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "medium";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+                reviewOutcomeId?: undefined;
+            };
+            producer: {
+                proposalId: string;
+                oldValue: string;
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+            };
+        })[];
+    };
+    status: {
+        observedCandidateCount: number;
+        selectedCandidateId: string;
+        reviewDecisionName: string;
+    };
+};
+export declare const reviewWorkbenchQueueFixtures: (ReviewItem | {
+    apiVersion: "survey.kontourai.io/v1alpha1";
+    kind: "ReviewItem";
+    metadata: {
+        name: string;
+        labels: {
+            domain: string;
+        };
+        producer: {
+            displayName: string;
+            slug: string;
+        };
+    };
+    spec: {
+        target: string;
+        selectedCandidateId: string;
+        candidateSetStatus: "resolved";
+        rationale: string;
+        candidates: ({
+            id: string;
+            role: "current";
+            value: string;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "web-page";
+                observedAt: string;
+                fetchedAt: string;
+                locatorScheme: "html";
+            };
+            locator: {
+                scheme: "html";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "medium";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                reviewOutcomeId: string;
+                claimId: string;
+            };
+            producer: {
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+                proposalId?: undefined;
+                oldValue?: undefined;
+            };
+        } | {
+            id: string;
+            role: "proposed";
+            value: string;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "web-page";
+                observedAt: string;
+                fetchedAt: string;
+                locatorScheme: "html";
+            };
+            locator: {
+                scheme: "html";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "medium";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+                reviewOutcomeId?: undefined;
+            };
+            producer: {
+                proposalId: string;
+                oldValue: string;
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+            };
+        })[];
+    };
+    status: {
+        observedCandidateCount: number;
+        selectedCandidateId: string;
+        reviewDecisionName: string;
+    };
+})[];