@kontourai/survey 7.0.0 → 8.1.0

package/dist/src/review-workbench/field-state-view.js

@@ -0,0 +1,84 @@
+import { isScoreBlind } from "./review-queue-session.js";
+const CONTENT_TEXT = {
+    value: "Value found",
+    conflicting: "Conflicting values",
+    unsupported: "Not supported by verifier",
+    excluded: "Proposals excluded",
+    not_covered: "Not read",
+};
+const LIFECYCLE_TEXT = {
+    pending: "Needs review",
+    accepted: "Accepted",
+    rejected: "Rejected",
+    could_not_confirm: "Could not confirm",
+    superseded: "Superseded",
+};
+const WORKBENCH_LIFECYCLE = {
+    "accept-proposed": "accepted",
+    "select-proposed": "accepted",
+    "keep-current": "accepted",
+    "reject-proposed": "rejected",
+    "could-not-confirm": "could_not_confirm",
+};
+/**
+ * The field-state panel: one row per field the extraction was asked for or
+ * proposed, with its derived content state, its lifecycle, and its signals.
+ * Fields with no review card (not read, only excluded proposals, no proposal)
+ * are listed too, so a run that lost content never reads as complete.
+ *
+ * The lifecycle of a field in the queue is read from the live session, so it
+ * follows the reviewer's decisions. Only what the session cannot know comes
+ * from the derived states: a decision carried forward from an earlier round,
+ * and a superseded one. In a score-blind session a content state derived from
+ * verifier records is shown as the state its candidates alone give.
+ */
+export function renderFieldStatesHtml(states, session) {
+    if (states.length === 0)
+        return "";
+    const itemsByName = new Map(session.items.map((item) => [item.metadata.name, item]));
+    const rows = states.map((state) => {
+        const item = state.reviewItemName !== undefined ? itemsByName.get(state.reviewItemName) : undefined;
+        const content = state.content === "unsupported" && isScoreBlind(session)
+            ? (item && item.spec.candidates.filter((candidate) => candidate.role === "proposed").length > 1 ? "conflicting" : "value")
+            : state.content;
+        const live = item ? session.decisionsByItemName[item.metadata.name] : undefined;
+        const lifecycle = live !== undefined
+            ? WORKBENCH_LIFECYCLE[live]
+            : state.lifecycle === "superseded" || state.decisionBasis === "carried-forward"
+                ? state.lifecycle
+                : state.reviewItemName !== undefined ? "pending" : undefined;
+        const carried = live === undefined && state.decisionBasis === "carried-forward";
+        const signals = [
+            ...(state.signals.incompleteRun ? ["The extraction stopped before reading all of the source."] : []),
+            ...(state.signals.excludedProposals ? [`${state.signals.excludedProposals} proposal${state.signals.excludedProposals === 1 ? " was" : "s were"} excluded: the excerpt is not at the cited span.`] : []),
+            ...(state.signals.unresolvedImport ? ["The import could not ground any value."] : []),
+        ];
+        const label = `${state.slot.fieldOrBehavior}${state.slot.pathIndices?.length ? `[${state.slot.pathIndices.join("][")}]` : ""}`;
+        return `
+      <li class="field-state-row" data-testid="field-state" data-field="${escapeHtml(label)}" data-content="${content ?? "none"}" data-lifecycle="${lifecycle ?? "none"}"${carried ? ' data-basis="carried-forward"' : ""}>
+        <span class="field-state-name">${escapeHtml(label)}</span>
+        <span class="field-state-chips">
+          <span class="chip state-content ${content ?? "none"}" data-testid="field-state-content">${escapeHtml(content === undefined ? "No proposal" : CONTENT_TEXT[content])}</span>
+          ${lifecycle === undefined ? "" : `<span class="chip state-lifecycle ${lifecycle}" data-testid="field-state-lifecycle">${escapeHtml(LIFECYCLE_TEXT[lifecycle])}${carried ? " · carried forward" : ""}</span>`}
+        </span>
+        ${content === undefined ? `<span class="field-state-note">No value was proposed. That is not the same as the source not stating one.</span>` : ""}
+        ${signals.map((signal) => `<span class="field-state-note signal" data-testid="field-state-signal">${escapeHtml(signal)}</span>`).join("")}
+      </li>`;
+    }).join("");
+    const unread = states.filter((state) => state.content === "not_covered").length;
+    return `
+    <section class="field-states" data-testid="field-states" aria-label="Field states">
+      <h2>Field states</h2>
+      ${unread > 0 ? `<p class="field-states-lead" data-testid="field-states-incomplete">${unread} field${unread === 1 ? " was" : "s were"} not read: the extraction stopped short. ${unread === 1 ? "It has" : "They have"} no value to review, and that does not mean the source lacks ${unread === 1 ? "it" : "them"}.</p>` : ""}
+      <ul>${rows}</ul>
+    </section>
+  `;
+}
+function escapeHtml(value) {
+    return String(value)
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

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

@@ -1,4 +1,5 @@
-import { type ReviewCandidate, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewSessionEventSpec } from "../../src/review-resource.js";
+import { type ReviewCandidate, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewSessionEventSpec, type ReviewSessionPresentation, type ReviewSessionSampling } from "../../src/review-resource.js";
+export type { ReviewSessionPresentation, ReviewSessionSampling } from "../../src/review-resource.js";
 /**
  * The decisions a reviewer can record on a ReviewItem.
  *
@@ -31,6 +32,10 @@ export interface ReviewWorkbenchState {
      * decision and ignored for every other one.
      */
     readonly selectedCandidateId?: string;
+    /** The session's presentation; recorded on the decision. See {@link ReviewSessionPresentation}. */
+    readonly presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen; recorded on the decision. */
+    readonly sampling?: ReviewSessionSampling;
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -53,7 +58,47 @@ export interface ReviewQueueSessionState {
      * `select-proposed` decision and never read it.
      */
     readonly selectedCandidateIdsByItemName?: Readonly<Record<string, string>>;
+    /**
+     * Session-level presentation, set when the session is opened. Every
+     * decision event is stamped with it and replay refuses a mismatch; a
+     * `ReviewQueueBinding` also covers it. Without a binding, an edit to both the
+     * snapshot and every event stamp is not detectable. Absent: scores are shown
+     * and decisions record no presentation.
+     */
+    readonly presentation?: ReviewSessionPresentation;
+    /** How the session's items were chosen. Absent: decisions record no sampling. */
+    readonly sampling?: ReviewSessionSampling;
 }
+/** Whether the session hides confidence and verifier results from its reviewer. */
+export declare function isScoreBlind(session: {
+    readonly presentation?: ReviewSessionPresentation;
+}): boolean;
+/**
+ * Throws unless the session's presentation and sampling are well formed:
+ * `scoreBlind` a boolean, and a `random-audit` sampling with a rate in (0, 1]
+ * and a non-empty seed. Unknown keys are refused so a decision never records
+ * a condition nothing reads.
+ */
+export declare function assertReviewSessionConditions(session: {
+    readonly presentation?: unknown;
+    readonly sampling?: unknown;
+}): void;
+/**
+ * The session conditions a decision event carries, or `undefined` for a
+ * session that declares none. Stamped on every decision event so replay can
+ * refuse events recorded under other conditions than the snapshot's: sighted
+ * events replayed over a blind snapshot, or a snapshot whose presentation was
+ * changed after decisions were recorded.
+ */
+export declare function sessionConditionsStamp(session: {
+    readonly presentation?: ReviewSessionPresentation;
+    readonly sampling?: ReviewSessionSampling;
+}): {
+    presentation?: ReviewSessionPresentation;
+    sampling?: ReviewSessionSampling;
+} | undefined;
+export declare function assertAuditRate(rate: unknown): asserts rate is number;
+export declare function assertAuditSeed(seed: unknown): asserts seed is string;
 export interface ReviewSessionSummary {
     readonly accepted: number;
     readonly keptCurrent: number;

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

@@ -4,6 +4,71 @@ import { checkEditedValueForItem } from "./edited-value.js";
 import { assertSoleCandidateId, reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
+/** Whether the session hides confidence and verifier results from its reviewer. */
+export function isScoreBlind(session) {
+    return session.presentation?.scoreBlind === true;
+}
+/**
+ * Throws unless the session's presentation and sampling are well formed:
+ * `scoreBlind` a boolean, and a `random-audit` sampling with a rate in (0, 1]
+ * and a non-empty seed. Unknown keys are refused so a decision never records
+ * a condition nothing reads.
+ */
+export function assertReviewSessionConditions(session) {
+    const { presentation, sampling } = session;
+    if (presentation !== undefined) {
+        if (!isPlainRecord(presentation) || Object.keys(presentation).join(",") !== "scoreBlind" || typeof presentation.scoreBlind !== "boolean") {
+            throw new Error("Review session presentation must be { scoreBlind: boolean }.");
+        }
+    }
+    if (sampling !== undefined) {
+        if (!isPlainRecord(sampling))
+            throw new Error("Review session sampling must be an object.");
+        const keys = Object.keys(sampling).sort().join(",");
+        if (sampling.kind === "queue") {
+            if (keys !== "kind")
+                throw new Error("Review session sampling of kind queue takes no rate or seed.");
+        }
+        else if (sampling.kind === "random-audit") {
+            if (keys !== "kind,rate,seed")
+                throw new Error("Review session sampling of kind random-audit requires exactly rate and seed.");
+            assertAuditRate(sampling.rate);
+            assertAuditSeed(sampling.seed);
+        }
+        else {
+            throw new Error("Review session sampling kind must be queue or random-audit.");
+        }
+    }
+}
+/**
+ * The session conditions a decision event carries, or `undefined` for a
+ * session that declares none. Stamped on every decision event so replay can
+ * refuse events recorded under other conditions than the snapshot's: sighted
+ * events replayed over a blind snapshot, or a snapshot whose presentation was
+ * changed after decisions were recorded.
+ */
+export function sessionConditionsStamp(session) {
+    if (session.presentation === undefined && session.sampling === undefined)
+        return undefined;
+    return {
+        ...(session.presentation !== undefined ? { presentation: { scoreBlind: session.presentation.scoreBlind } } : {}),
+        ...(session.sampling !== undefined ? { sampling: { ...session.sampling } } : {}),
+    };
+}
+export function assertAuditRate(rate) {
+    if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0 || rate > 1) {
+        throw new Error("A random-audit rate must be a number greater than 0 and at most 1.");
+    }
+}
+export function assertAuditSeed(seed) {
+    if (typeof seed !== "string" || !AUDIT_SEED.test(seed)) {
+        throw new Error("A random-audit seed must be a stable identity: 1-256 characters from letters, digits and . _ : @ / + ~ -, starting with a letter or digit.");
+    }
+}
+const AUDIT_SEED = /^[A-Za-z0-9][A-Za-z0-9._:@/+~-]{0,255}$/;
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export const workbenchDecisionDefinitions = {
     "accept-proposed": {
         label: "Accept proposed",
@@ -67,6 +132,8 @@ export function currentReviewWorkbenchState(session) {
         selectedCandidateId: session.selectedCandidateIdsByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
+        ...(session.presentation !== undefined ? { presentation: session.presentation } : {}),
+        ...(session.sampling !== undefined ? { sampling: session.sampling } : {}),
     };
 }
 export function currentReviewItem(session) {
@@ -360,9 +427,13 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             actor: session.actorId,
             reviewedAt: session.reviewedAt,
         });
-        const data = editedValue !== undefined
-            ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
-            : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) };
+        const conditions = sessionConditionsStamp(session);
+        const data = {
+            ...(editedValue !== undefined
+                ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
+                : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) }),
+            ...(conditions ? { sessionConditions: conditions } : {}),
+        };
         events.push(buildReviewSessionEvent(session, {
             sessionName,
             sequence: events.length + 1,

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

@@ -1,6 +1,6 @@
 import type { ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
-export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "invalid-conflict-selection" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch";
+export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "invalid-conflict-selection" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch" | "session-conditions-mismatch";
 export interface ReviewSessionReplayIssue {
     readonly code: ReviewSessionReplayIssueCode;
     readonly eventName: string;

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

@@ -1,5 +1,6 @@
-import { candidateForDecision, conflictSelectionIssue, decisionSelectsNoCandidate, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, conflictSelectionIssue, decisionSelectsNoCandidate, isClearedWorkbenchDecisionEvent, sessionConditionsStamp, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { checkEditedValueForItem } from "./edited-value.js";
+import { canonicalJson } from "./canonical.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
     const sequenceIssues = validateEventSequence(events);
@@ -44,6 +45,19 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
         }
         else if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
             const decision = replayableWorkbenchDecision(event.spec.data?.workbenchDecision);
+            // A decision recorded under other presentation or sampling than the
+            // snapshot's must not be replayed as if made under the snapshot's.
+            const expectedConditions = sessionConditionsStamp(snapshot);
+            const carried = event.spec.data?.sessionConditions;
+            if (decision && canonicalJson(carried ?? null) !== canonicalJson(expectedConditions ?? null)) {
+                issues.push({
+                    ...eventRef,
+                    code: "session-conditions-mismatch",
+                    reviewItemName,
+                    candidateId: event.spec.candidateId,
+                    message: `ReviewSessionEvent ${event.metadata.name} was recorded under session conditions ${JSON.stringify(carried ?? "none")}, but the snapshot's are ${JSON.stringify(expectedConditions ?? "none")}.`,
+                });
+            }
             if (!decision) {
                 issues.push({
                     ...eventRef,

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

@@ -1,2 +1,11 @@
 export declare const REVIEW_WORKBENCH_CSS: string;
+/** Literal dark token defaults for the element's :host, from @kontourai/ui tokens.css :root. */
+export declare const REVIEW_WORKBENCH_DARK_TOKEN_DECLARATIONS: string;
+/** Literal light token values for the element's color-scheme="light", from @kontourai/ui tokens.css [data-theme="light"]. */
+export declare const REVIEW_WORKBENCH_LIGHT_TOKEN_DECLARATIONS: string;
+/** Each built-in preset's dark and light values, from @kontourai/ui themes.css. */
+export declare const REVIEW_WORKBENCH_THEME_TOKEN_DECLARATIONS: Readonly<Record<string, {
+    readonly dark: string;
+    readonly light: string;
+}>>;
 export default REVIEW_WORKBENCH_CSS;