@kontourai/survey 7.0.0 → 8.0.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.js

@@ -617,6 +617,30 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .chip.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
 .survey-workbench-embed .chip.could-not-confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
 
+/* Field-state panel: one row per field, content and lifecycle derived from
+   the records, never stored labels. A field that was not read is listed. */
+.survey-workbench-embed .field-states{ padding: var(--k-space-3, 12px) 1rem; border-bottom: 1px solid var(--k-line); background: var(--k-panel); }
+.survey-workbench-embed .field-states h2{ margin: 0 0 8px; font-size: 13px; font-weight: 700; color: var(--k-text); }
+.survey-workbench-embed .field-states ul{ list-style: none; margin: 0; padding: 0; display: grid; gap: 6px; }
+.survey-workbench-embed .field-states-lead{ margin: 0 0 8px; font-size: 13px; line-height: 1.45; color: var(--k-caution); }
+.survey-workbench-embed .field-state-row{ display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 4px 12px; align-items: center; padding: 6px 0; border-top: 1px solid var(--k-line); }
+.survey-workbench-embed .field-state-row:first-child{ border-top: 0; }
+.survey-workbench-embed .field-state-name{ font-family: var(--k-font-mono, ui-monospace, monospace); font-size: 12px; color: var(--k-text); overflow-wrap: anywhere; }
+.survey-workbench-embed .field-state-chips{ display: inline-flex; flex-wrap: wrap; gap: 6px; justify-content: flex-end; }
+.survey-workbench-embed .field-state-note{ grid-column: 1 / -1; font-size: 12px; color: var(--k-muted); }
+.survey-workbench-embed .field-state-note.signal{ color: var(--k-caution); }
+.survey-workbench-embed .chip.state-content.value{ color: var(--k-positive); background: var(--k-positive-wash); }
+.survey-workbench-embed .chip.state-content.conflicting,
+.survey-workbench-embed .chip.state-content.excluded,
+.survey-workbench-embed .chip.state-content.not_covered{ color: var(--k-caution); background: var(--k-caution-wash); }
+.survey-workbench-embed .chip.state-content.unsupported{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.state-content.none,
+.survey-workbench-embed .chip.state-lifecycle.superseded{ color: var(--k-muted); background: var(--k-sunken); }
+.survey-workbench-embed .chip.state-lifecycle.pending{ color: var(--k-brand); background: var(--k-brand-wash); }
+.survey-workbench-embed .chip.state-lifecycle.accepted{ color: var(--k-positive); background: var(--k-positive-wash); }
+.survey-workbench-embed .chip.state-lifecycle.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.state-lifecycle.could_not_confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
+
 .survey-workbench-embed .frow1 .push{
   margin-left: auto;
 }
@@ -861,6 +885,12 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   background: var(--k-negative-wash);
 }
 
+/* A score-blind session: an informational note, not a warning. */
+.survey-workbench-embed .queue-attestation.score-blind{
+  color: var(--k-active);
+  background: var(--k-active-soft);
+}
+
 /* Conflicting proposed values: each value is listed with its own choice
    control until the field is decided, then marked chosen or not chosen. */
 .survey-workbench-embed .conflict-values ul{
@@ -1421,6 +1451,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 /* The diff-collapse must also hold in host contexts without a query container
    (e.g. an embed that doesn't establish \`container-type\`): fall back to viewport. */
 @media (max-width: 620px) {
+  .survey-workbench-embed .field-state-row{ grid-template-columns: minmax(0, 1fr); }
+  .survey-workbench-embed .field-state-chips{ justify-content: flex-start; }
   .survey-workbench-embed .diff{
     grid-template-columns: 1fr;
   }

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

@@ -614,6 +614,30 @@
 .survey-workbench-embed .chip.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
 .survey-workbench-embed .chip.could-not-confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
 
+/* Field-state panel: one row per field, content and lifecycle derived from
+   the records, never stored labels. A field that was not read is listed. */
+.survey-workbench-embed .field-states{ padding: var(--k-space-3, 12px) 1rem; border-bottom: 1px solid var(--k-line); background: var(--k-panel); }
+.survey-workbench-embed .field-states h2{ margin: 0 0 8px; font-size: 13px; font-weight: 700; color: var(--k-text); }
+.survey-workbench-embed .field-states ul{ list-style: none; margin: 0; padding: 0; display: grid; gap: 6px; }
+.survey-workbench-embed .field-states-lead{ margin: 0 0 8px; font-size: 13px; line-height: 1.45; color: var(--k-caution); }
+.survey-workbench-embed .field-state-row{ display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 4px 12px; align-items: center; padding: 6px 0; border-top: 1px solid var(--k-line); }
+.survey-workbench-embed .field-state-row:first-child{ border-top: 0; }
+.survey-workbench-embed .field-state-name{ font-family: var(--k-font-mono, ui-monospace, monospace); font-size: 12px; color: var(--k-text); overflow-wrap: anywhere; }
+.survey-workbench-embed .field-state-chips{ display: inline-flex; flex-wrap: wrap; gap: 6px; justify-content: flex-end; }
+.survey-workbench-embed .field-state-note{ grid-column: 1 / -1; font-size: 12px; color: var(--k-muted); }
+.survey-workbench-embed .field-state-note.signal{ color: var(--k-caution); }
+.survey-workbench-embed .chip.state-content.value{ color: var(--k-positive); background: var(--k-positive-wash); }
+.survey-workbench-embed .chip.state-content.conflicting,
+.survey-workbench-embed .chip.state-content.excluded,
+.survey-workbench-embed .chip.state-content.not_covered{ color: var(--k-caution); background: var(--k-caution-wash); }
+.survey-workbench-embed .chip.state-content.unsupported{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.state-content.none,
+.survey-workbench-embed .chip.state-lifecycle.superseded{ color: var(--k-muted); background: var(--k-sunken); }
+.survey-workbench-embed .chip.state-lifecycle.pending{ color: var(--k-brand); background: var(--k-brand-wash); }
+.survey-workbench-embed .chip.state-lifecycle.accepted{ color: var(--k-positive); background: var(--k-positive-wash); }
+.survey-workbench-embed .chip.state-lifecycle.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.state-lifecycle.could_not_confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
+
 .survey-workbench-embed .frow1 .push{
   margin-left: auto;
 }
@@ -858,6 +882,12 @@
   background: var(--k-negative-wash);
 }
 
+/* A score-blind session: an informational note, not a warning. */
+.survey-workbench-embed .queue-attestation.score-blind{
+  color: var(--k-active);
+  background: var(--k-active-soft);
+}
+
 /* Conflicting proposed values: each value is listed with its own choice
    control until the field is decided, then marked chosen or not chosen. */
 .survey-workbench-embed .conflict-values ul{
@@ -1418,6 +1448,8 @@
 /* The diff-collapse must also hold in host contexts without a query container
    (e.g. an embed that doesn't establish `container-type`): fall back to viewport. */
 @media (max-width: 620px) {
+  .survey-workbench-embed .field-state-row{ grid-template-columns: minmax(0, 1fr); }
+  .survey-workbench-embed .field-state-chips{ justify-content: flex-start; }
   .survey-workbench-embed .diff{
     grid-template-columns: 1fr;
   }

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

@@ -3,10 +3,13 @@ import { type ReviewSessionReplayIssue, type ReviewSessionReplayWarning } from "
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewValueDescriptor } from "../review-resource.js";
 import type { ExtractionEnvelopeImport, ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import type { FieldState } from "../field-states.js";
 export { reviewAuditRowKeys, type ReviewAuditRowKey } from "./audit-rows.js";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, attestReviewQueueExtraction, bindReviewQueue, reviewItemCarriesExtractionBinding, unverifiedExtractionQueueSentence, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, type BindReviewQueueOptions, type ReviewQueueBinding, type ReviewQueueBindingIssue, type ReviewQueueBindingIssueCode, type ReviewQueueExtractionAttestation, type ReviewQueueExtractionIssue, type ReviewQueueExtractionIssueCode, type ValidateReviewQueueBindingOptions, } from "./queue-binding.js";
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, type ExtractionAlignmentState, type ArtifactUnavailableCode, type BuiltExtractionInspectorCandidate, type BuiltExtractionInspectorModel, type ExtractionInspectorCandidate, type ExtractionInspectorEntry, type ExtractionInspectorExportOptions, type ExtractionInspectorFilters, type ExtractionInspectorInput, type ExtractionInspectorMountOptions, type ExtractionInspectorModel, type ExtractionInspectorSource, type ResolvedExtractionArtifact, } from "./extraction-inspector.js";
-export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, conflictSelectionIssue, unchosenProposedCandidates, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, 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 { renderFieldStatesHtml } from "./field-state-view.js";
+export { drawRandomAuditSample, openRandomAuditSession, type RandomAuditSampleOptions, } from "./audit-sample.js";
+export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, conflictSelectionIssue, unchosenProposedCandidates, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, isScoreBlind, assertReviewSessionConditions, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewSessionPresentation, type ReviewSessionSampling, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ExcludedProposalPresentation, type ExcludedProposalsUnreadable, 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";
 export { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, type ReviewSessionReplayIssue, type ReviewSessionReplayIssueCode, type ReviewSessionReplayWarning, } from "./review-session-replay.js";
@@ -109,6 +112,13 @@ export interface MountReviewWorkbenchOptions {
     readonly extractionImport?: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult;
     /** Maximum review cards mounted at once. Defaults to 50 and is capped at 250. */
     readonly pageSize?: number;
+    /**
+     * The queue's derived field states (`deriveFieldStates`). When supplied, a
+     * field-state panel lists every field with its content state, lifecycle and
+     * signals, including fields that have no review card because they were not
+     * read. Lifecycles of queued fields follow the live session.
+     */
+    readonly fieldStates?: readonly FieldState[];
 }
 export type ReviewQueueDisposition = "all" | "unresolved" | "accepted" | "kept" | "rejected" | "could-not-confirm";
 export interface ReviewQueueView {
@@ -230,6 +240,8 @@ export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState |
     readonly queueView?: Partial<ReviewQueueView>;
     /** See {@link MountReviewWorkbenchOptions.extractionImport}. */
     readonly extractionImport?: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult;
+    /** See {@link MountReviewWorkbenchOptions.fieldStates}. */
+    readonly fieldStates?: readonly FieldState[];
 }): string;
 export declare function buildReviewQueueWindow(session: ReviewQueueSessionState, view?: Partial<ReviewQueueView>): ReviewQueueWindow;
 /**

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

@@ -1,6 +1,6 @@
 import { canonicalJson } from "./canonical.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
-import { candidateForDecision, conflictSelectionIssue, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, unchosenProposedCandidates, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewWorkbenchState, defaultReviewSessionName, effectiveValueForDecision, initialReviewQueueSessionState, replayReviewSessionEvents, reviewWorkbenchSessionStorageKey, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, conflictSelectionIssue, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, unchosenProposedCandidates, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewWorkbenchState, defaultReviewSessionName, effectiveValueForDecision, initialReviewQueueSessionState, isScoreBlind, assertReviewSessionConditions, sessionConditionsStamp, replayReviewSessionEvents, reviewWorkbenchSessionStorageKey, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
@@ -9,11 +9,14 @@ import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review
 import { attestReviewQueueExtraction } from "./queue-binding.js";
 import { candidateVerificationNotes, excludedProposalsSentence, excludedProposalsUnreadableSentence } from "./review-presentation.js";
 import { editedValueFromEditorText, isIsoCalendarDate, parsePlainDecimal } from "./edited-value.js";
+import { renderFieldStatesHtml } from "./field-state-view.js";
 import { createAuditFactTrace, } from "./audit-rows.js";
 export { reviewAuditRowKeys } from "./audit-rows.js";
 export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, attestReviewQueueExtraction, bindReviewQueue, reviewItemCarriesExtractionBinding, unverifiedExtractionQueueSentence, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./queue-binding.js";
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, } from "./extraction-inspector.js";
-export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, conflictSelectionIssue, unchosenProposedCandidates, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+export { renderFieldStatesHtml } from "./field-state-view.js";
+export { drawRandomAuditSample, openRandomAuditSession, } from "./audit-sample.js";
+export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, conflictSelectionIssue, unchosenProposedCandidates, decisionCandidateId, decisionSelectsNoCandidate, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, isScoreBlind, assertReviewSessionConditions, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
 export { reviewSessionReplayWarningsForSnapshot, validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
@@ -24,6 +27,7 @@ export function buildReviewDecision(state, options = {}) {
         return undefined;
     }
     const definition = workbenchDecisionDefinitions[state.decision];
+    assertReviewSessionConditions(state);
     if (state.decision === "could-not-confirm" && !state.note.trim()) {
         throw new Error("Could not confirm requires a non-empty reason.");
     }
@@ -70,6 +74,10 @@ export function buildReviewDecision(state, options = {}) {
                 : {}),
             // A choice between conflicting values records the rivals it passed over.
             ...(unchosen.length ? { unselectedCandidateIds: unchosen.map((entry) => entry.id) } : {}),
+            // The session's conditions, never the reviewer's: a score-blind session
+            // records that the decision was made without scores on screen.
+            ...(state.presentation !== undefined ? { presentation: { scoreBlind: state.presentation.scoreBlind } } : {}),
+            ...(state.sampling !== undefined ? { sampling: { ...state.sampling } } : {}),
         },
         status: {
             ...(candidateProjection?.claimId ? { appliedToClaimIds: [candidateProjection.claimId] } : {}),
@@ -140,7 +148,8 @@ function decisionCardRenderedPrompt(state, presentation, adapter) {
     const excluded = excludedProposalsSentence(presentation.excludedProposals);
     const unreadable = excludedProposalsUnreadableSentence(presentation.excludedProposalsUnreadable);
     // Likewise the verifier records the card shows, read against the same value.
-    const verification = candidateVerificationNotes(state.item, state.decision === "accept-proposed" ? state.editedValue : undefined).map((note) => note.sentence);
+    // A score-blind card shows no verifier result, so the recorded prompt names none.
+    const verification = isScoreBlind(state) ? [] : candidateVerificationNotes(state.item, state.decision === "accept-proposed" ? state.editedValue : undefined).map((note) => note.sentence);
     return [decisionCardBasePrompt(state, presentation.targetLabel, adapter), ...(excluded ? [excluded] : []), ...(unreadable ? [unreadable] : []), ...verification].join(" ");
 }
 function decisionCardBasePrompt(state, targetLabel, adapter) {
@@ -514,7 +523,7 @@ export function createPersistentReviewSessionEventStore(options) {
 }
 export function renderReviewWorkbenchHtml(state, _events, options = {}) {
     const session = queueSessionFromStartState(state);
-    return renderReviewQueueSessionHtml(session, options.presentationAdapter, normalizeReviewQueueView(options.queueView), attestReviewQueueExtraction(session.items, options.extractionImport));
+    return renderReviewQueueSessionHtml(session, options.presentationAdapter, normalizeReviewQueueView(options.queueView), attestReviewQueueExtraction(session.items, options.extractionImport), options.fieldStates);
 }
 /**
  * The visual/decision state of a field card, derived from the reviewer's local
@@ -602,7 +611,7 @@ function isEmptyValue(value) {
 }
 const ARROW_SVG = "<svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><path d=\"M5 12h14M13 6l6 6-6 6\"/></svg>";
 const WARNING_SVG = "<svg width=\"15\" height=\"15\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><path d=\"M12 9v4M12 17h.01\"/><path d=\"M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z\"/></svg>";
-function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, attestation) {
+function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, attestation, fieldStates) {
     // A queue that does not match its stored extraction import is not reviewed:
     // its items could hide or alter what the source said.
     if (attestation.state === "diverges") {
@@ -625,6 +634,9 @@ function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, a
       ${attestation.state === "unverified"
         ? `<div class="queue-attestation unverified" data-testid="queue-attestation" data-state="unverified" role="note">${WARNING_SVG}<span>${escapeHtml(attestation.message)}</span></div>`
         : ""}
+      ${isScoreBlind(session)
+        ? `<div class="queue-attestation score-blind" data-testid="score-blind-notice" data-sampling="${escapeHtml(session.sampling?.kind ?? "")}" role="note"><span>${escapeHtml(scoreBlindNotice(session))}</span></div>`
+        : ""}
       <header class="rhead">
         <div class="top">
           <div class="subj">
@@ -641,6 +653,7 @@ function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, a
           <button class="apply" type="button" data-testid="apply-button"${decidedCount === 0 ? " disabled" : ""}>Apply ${decidedCount} decision${decidedCount === 1 ? "" : "s"}</button>
         </div>
       </header>
+      ${fieldStates ? renderFieldStatesHtml(fieldStates, session) : ""}
       <nav class="queue-controls" aria-label="Review queue navigation">
         <label>
           <span>Find fields</span>
@@ -730,9 +743,9 @@ function renderFieldCard(item, session, presentationAdapter) {
         : proposedCandidates.length > 1
             ? renderConflictingProposals(item, proposedCandidates, presentationAdapter, presentation.targetLabel, decision, session.selectedCandidateIdsByItemName?.[item.metadata.name])
             : "<p class=\"field-value\">No proposed value is available for this field.</p>"}
-        ${proposed ? renderProvenanceRow(item, proposed, presentationAdapter) : ""}
+        ${proposed ? renderProvenanceRow(item, proposed, presentationAdapter, isScoreBlind(session)) : ""}
         ${renderExtractionImportNotes(presentation)}
-        ${renderVerificationNotes(candidateVerificationNotes(item, decision === "accept-proposed" ? editedValue : undefined))}
+        ${isScoreBlind(session) ? "" : renderVerificationNotes(candidateVerificationNotes(item, decision === "accept-proposed" ? editedValue : undefined))}
         <div class="decide">
           ${keepDecision === undefined ? "" : `<button class="btn keep" type="button" data-testid="keep-current" data-item-name="${escapeHtml(item.metadata.name)}">${keepLabel}</button>`}
           ${proposed ? `<button class="btn use" type="button" data-testid="use-proposed" data-item-name="${escapeHtml(item.metadata.name)}">Use proposed</button>
@@ -955,7 +968,7 @@ export function validateProposedValue(descriptor, rawValue) {
             return undefined;
     }
 }
-function renderProvenanceRow(item, proposed, presentationAdapter) {
+function renderProvenanceRow(item, proposed, presentationAdapter, scoreBlind) {
     const excerpt = proposed.locator?.excerpt;
     if (!excerpt) {
         return `
@@ -968,7 +981,8 @@ function renderProvenanceRow(item, proposed, presentationAdapter) {
       </div>
     `;
     }
-    const confidence = proposed.extraction.confidence ?? proposed.confidence;
+    // A score-blind session never renders the proposer's confidence.
+    const confidence = scoreBlind ? undefined : proposed.extraction.confidence ?? proposed.confidence;
     const presentation = buildReviewCandidatePresentation(item, proposed, presentationAdapter);
     const sourceLinkHtml = presentation.sourceLink
         ? `<a href="${escapeHtml(presentation.sourceLink.href)}">${escapeHtml(presentation.sourceLink.label ?? presentation.sourceText)}</a>`
@@ -1064,6 +1078,8 @@ function renderAuditDetails(item, current, proposed, session, presentationAdapte
         selectedCandidateId: session.selectedCandidateIdsByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
+        ...(session.presentation !== undefined ? { presentation: session.presentation } : {}),
+        ...(session.sampling !== undefined ? { sampling: session.sampling } : {}),
     };
     const reviewDecisionPayload = buildReviewDecision(state, { presentationAdapter });
     const preview = buildSurfaceProjectionPreview(item, reviewDecisionPayload, presentationAdapter);
@@ -1348,10 +1364,14 @@ function createReviewWorkbenchController(root, startState, options) {
         const attemptEvidenceIds = itemName && decision === "could-not-confirm"
             ? session.attemptEvidenceIdsByItemName?.[itemName]
             : undefined;
+        const conditions = sessionConditionsStamp(session);
         const defaultData = decision
-            ? (editedValue !== undefined
-                ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
-                : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) })
+            ? {
+                ...(editedValue !== undefined
+                    ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
+                    : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) }),
+                ...(conditions ? { sessionConditions: conditions } : {}),
+            }
             : undefined;
         return buildReviewSessionEvent(session, {
             sessionName: defaultReviewSessionName,
@@ -1439,7 +1459,7 @@ function createReviewWorkbenchController(root, startState, options) {
         currentSession: () => session,
         currentSessionExport: () => buildReviewWorkbenchSessionExport(session, events, { presentationAdapter: options.presentationAdapter }),
         presentationAdapter: options.presentationAdapter,
-        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter, queueView, attestation),
+        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter, queueView, attestation, options.fieldStates),
         setDecision,
         clearDecision,
         updateReviewerNote,
@@ -1459,8 +1479,8 @@ function reviewSessionStorageKey(session, keyPrefix) {
     const itemNames = buildReviewSessionResource(session).spec.reviewItemNames.join(",");
     return `${keyPrefix}:${itemNames}`;
 }
-function renderCurrentState(root, session, controller, presentationAdapter, queueView, attestation) {
-    root.innerHTML = renderReviewQueueSessionHtml(session, presentationAdapter, queueView ?? normalizeReviewQueueView(undefined), attestation ?? attestReviewQueueExtraction(session.items, undefined));
+function renderCurrentState(root, session, controller, presentationAdapter, queueView, attestation, fieldStates) {
+    root.innerHTML = renderReviewQueueSessionHtml(session, presentationAdapter, queueView ?? normalizeReviewQueueView(undefined), attestation ?? attestReviewQueueExtraction(session.items, undefined), fieldStates);
     bindFieldCardInteractions(root, controller);
     bindApplyButton(root, controller);
     bindClampToggles(root);
@@ -1513,8 +1533,14 @@ function queueSessionFromStartState(startState) {
             : {}),
         reviewedAt: startState.reviewedAt,
         actorId: startState.actorId,
+        ...(startState.presentation !== undefined ? { presentation: startState.presentation } : {}),
+        ...(startState.sampling !== undefined ? { sampling: startState.sampling } : {}),
     };
 }
+function scoreBlindNotice(session) {
+    const audit = session.sampling?.kind === "random-audit" ? "Random audit sample. " : "";
+    return `${audit}Score-blind review: confidence and verifier results are hidden for this whole session. Decide from the source and its excerpt.`;
+}
 const COULD_NOT_CONFIRM_REASON_REQUIRED = "A reason is required when you could not confirm.";
 /**
  * Opens every collapsed region between `control` and the card before anything