@kontourai/survey 8.1.1 → 8.2.1

package/README.md

@@ -38,12 +38,14 @@ The Review Workbench rendering a real example queue — current vs proposed valu
 ## Quickstart
 
 ```sh
-npm install @kontourai/survey @kontourai/surface
+npm install @kontourai/survey @kontourai/surface@^4
 ```
 
-Survey supports `@kontourai/surface` 2.13 and later 2.x, and 3.x, and CI tests
-the lowest 2.x and the newest 3.x. Install either major and your project and
-Survey share one Surface copy (`npm ls @kontourai/surface` shows one entry).
+Survey supports `@kontourai/surface` 2.13 and later 2.x, 3.x, and 4.x. CI tests
+2.13.0 and the newest 3.x and 4.x. Install a Surface version in that range so
+your project and Survey share one Surface copy (`npm ls @kontourai/surface`
+shows one entry). Without a version, npm installs the latest Surface, which
+can fall outside that range; npm then installs a separate copy for Survey.
 
 Requires Node.js >=22. TypeScript >=5.0 is required to compile against
 Survey's published type declarations (`defineProductVocabulary`'s `const`

package/dist/src/console/review-console-server.d.ts

@@ -14,9 +14,11 @@
  */
 import { type ServerReviewSessionRecord } from "../review-workbench/server-review-session.js";
 import { type ReviewQueueBinding } from "../review-workbench/queue-binding.js";
-import type { ReviewWorkbenchResult } from "../review-workbench/review-workbench.js";
+import type { ReviewWorkbenchResult, ReviewQueuePresentation } from "../review-workbench/review-workbench.js";
 import type { ReviewSessionEvent } from "../review-resource.js";
 export interface ReviewConsoleServerOptions {
+    /** Producer-owned display hints; independent of queue binding and application authority. */
+    readonly presentation?: ReviewQueuePresentation;
     /** Absolute path to the session JSON file. */
     readonly sessionPath: string;
     /** TCP port. Defaults to 0 (OS-assigned). */

package/dist/src/console/review-console-server.js

@@ -286,6 +286,7 @@ body {
   color: var(--k-text, #eef3f8);
   font-size: 13px;
 }
+.console-save-status[data-state="success"] { border-color: var(--k-positive); }
 .console-save-status[hidden] { display: none; }
 #review-workbench {
   flex: 1;
@@ -325,7 +326,7 @@ body {
     </button>
   </div>
 </header>
-${canApply ? '<div style="display:flex;justify-content:flex-end;padding:8px 16px"><button type="button" id="apply-review" class="theme-toggle">Send review to workflow</button></div>' : ''}
+${canApply ? '<div style="display:flex;justify-content:flex-end;padding:8px 16px"><button type="button" id="apply-review" class="theme-toggle" disabled>Send review to workflow</button></div>' : ''}
 <div id="console-save-status" class="console-save-status" role="alert" data-testid="console-save-status" hidden></div>
 <main id="review-workbench" class="workbench survey-workbench-embed" data-testid="review-workbench"></main>
 <script type="module">
@@ -342,11 +343,13 @@ import { mountReviewWorkbench, replayReviewSessionEvents, defaultReviewSessionNa
 // stored session, re-mounts from it and tells the reviewer once.
 let saveChain = Promise.resolve();
 
-function showSaveStatus(message) {
+function showSaveStatus(message, state = "error") {
   const el = document.getElementById("console-save-status");
   if (!el) return;
   if (message) {
     el.textContent = message;
+    el.dataset.state = state;
+    el.setAttribute("role", state === "success" ? "status" : "alert");
     el.hidden = false;
   } else {
     el.textContent = "";
@@ -366,7 +369,9 @@ function createConsoleEventStore(baseRevision) {
 
   async function refused(message) {
     abandoned = true;
-    showSaveStatus(message);
+    saveFailed = true;
+    updateApplyButton();
+    showSaveStatus(message + " Reload before sending the review, or retry the change.");
     await fetchAndMount();
   }
 
@@ -387,9 +392,11 @@ function createConsoleEventStore(baseRevision) {
       return;
     }
     if (res.ok) {
-      const body = await res.json().catch(() => ({}));
-      if (typeof body.revision === "string") { revision = body.revision; currentRevision = revision; }
+      const body = await res.json();
+      if (typeof body.revision !== "string") throw new Error("Missing saved revision");
+      revision = body.revision; currentRevision = revision;
       persistedCount = localEvents.length;
+      saveFailed = false;
       showSaveStatus("");
       return;
     }
@@ -404,9 +411,18 @@ function createConsoleEventStore(baseRevision) {
   return {
     // The mount state is already replayed from the stored log.
     load: () => undefined,
-    save: (_session, events) => {
+    save: (session, events) => {
+      currentState = session;
+      stateGeneration++;
+      pendingSaveCount++;
+      updateApplyButton();
       const localEvents = [...events];
-      saveChain = saveChain.then(() => persist(localEvents));
+      saveChain = saveChain.then(() => persist(localEvents)).catch(async () => {
+        await refused("Your last change was not saved. The console reloaded the stored session.");
+      }).finally(() => {
+        pendingSaveCount--;
+        updateApplyButton();
+      });
       pendingSave = saveChain;
       return saveChain;
     },
@@ -418,9 +434,19 @@ let currentRevision = null;
 let applying = false;
 let wasApplied = false;
 let pendingSave = Promise.resolve();
+let pendingSaveCount = 0;
+let saveFailed = false;
+let currentState = null;
+let stateGeneration = 0;
+let fetchGeneration = 0;
+function updateApplyButton() {
+  if (!applyButton) return;
+  const complete = currentState?.items?.length > 0 && currentState.items.every(item => currentState.decisionsByItemName[item.metadata.name] !== undefined);
+  applyButton.disabled = applying || wasApplied || pendingSaveCount > 0 || saveFailed || !currentRevision || !complete;
+}
 const applyButton = document.getElementById("apply-review");
 applyButton?.addEventListener("click", async () => {
-  if (applying || !currentRevision) return;
+  if (applyButton.disabled || applying || !currentRevision) return;
   applying = true;
   applyButton.disabled = true;
   try {
@@ -430,31 +456,41 @@ applyButton?.addEventListener("click", async () => {
       body: JSON.stringify({ baseRevision: currentRevision }),
     });
     const body = await response.json();
-    showSaveStatus(response.ok ? body.application.summary : body.error);
+    showSaveStatus(response.ok ? body.application.summary : body.error, response.ok ? "success" : "error");
     await fetchAndMount();
-  } catch { showSaveStatus("The review could not reach the workflow. Reload before trying again."); }
-  finally { applying = false; applyButton.disabled = wasApplied || !currentRevision; }
+  } catch { saveFailed = true; showSaveStatus("The review could not reach the workflow. Reload before trying again."); }
+  finally { applying = false; updateApplyButton(); }
 });
 
 async function fetchAndMount() {
+  const fetchBasis = ++fetchGeneration;
+  const stateBasis = stateGeneration;
   try {
     const res = await fetch("/api/session");
+    if (fetchBasis !== fetchGeneration || stateBasis !== stateGeneration) return;
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
+      if (fetchBasis !== fetchGeneration || stateBasis !== stateGeneration) return;
+      currentRevision = null;
+      updateApplyButton();
       showSaveStatus(body.error || ("The session could not be loaded (HTTP " + res.status + ")."));
       const root = document.getElementById("review-workbench");
       if (root) root.innerHTML = "";
       return;
     }
     const data = await res.json();
-    const { snapshot, events, revision, extractionImport } = data;
+    if (fetchBasis !== fetchGeneration || stateBasis !== stateGeneration) return;
+    const { snapshot, events, revision, extractionImport, presentation } = data;
     currentRevision = revision;
     wasApplied = Boolean(data.producerApplication);
-    if (applyButton) applyButton.disabled = applying || wasApplied;
+    if (data.producerApplication) showSaveStatus(data.producerApplication.summary, "success");
     const state = events && events.length > 0
       ? replayReviewSessionEvents(snapshot, events)
       : snapshot;
 
+    currentState = state;
+    updateApplyButton();
+
     // Preserve active item selection across reloads
     if (activeItemName && state.items && state.items.some(i => i.metadata.name === activeItemName)) {
       state.activeItemName = activeItemName;
@@ -463,8 +499,14 @@ async function fetchAndMount() {
     const root = document.getElementById("review-workbench");
     if (!root) return;
 
-    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision), ...(extractionImport ? { extractionImport } : {}) });
+    mountReviewWorkbench(root, state, { hideApply: Boolean(applyButton), queuePresentation: presentation, eventStore: createConsoleEventStore(revision), ...(extractionImport ? { extractionImport } : {}) });
+    if (wasApplied) root.querySelectorAll("button[data-item-name], input[data-item-name], textarea[data-item-name], select[data-item-name]").forEach(control => { control.disabled = true; });
   } catch (err) {
+    if (fetchBasis !== fetchGeneration || stateBasis !== stateGeneration) return;
+    currentRevision = null;
+    currentState = null;
+    updateApplyButton();
+    showSaveStatus("The session could not be loaded. Reload before sending the review.");
     console.error("[console] Mount error:", err);
   }
 }
@@ -486,7 +528,7 @@ function connectSse() {
     if (label) label.textContent = "live";
   });
   sse.addEventListener("update", () => {
-    fetchAndMount();
+    if (pendingSaveCount === 0 && !applying) fetchAndMount();
   });
   sse.addEventListener("error", () => {
     if (dot) dot.classList.add("disconnected");
@@ -664,6 +706,7 @@ export async function startReviewConsoleServer(options) {
                     events: content.events,
                     revision: reviewSessionRevision(content.events),
                     state: currentSessionState(content.snapshot, content.events),
+                    ...(options.presentation ? { presentation: options.presentation } : {}),
                     queueAttestation: attestation.state,
                     ...(content.producerApplication ? { producerApplication: content.producerApplication } : {}),
                     ...(content.extractionImport !== undefined ? { extractionImport: content.extractionImport } : {}),

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

@@ -1781,6 +1781,17 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   }
 }
 
+.survey-workbench-embed .review-context{
+  margin: var(--k-space-4);
+  padding: var(--k-space-4);
+  border: var(--k-border-thin) solid var(--k-line-strong);
+  border-radius: var(--k-radius-sm);
+  background: var(--k-panel-raised);
+  color: var(--k-text);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
 
 .survey-workbench-embed {
   overflow: hidden;

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

@@ -1778,6 +1778,17 @@
   }
 }
 
+.survey-workbench-embed .review-context{
+  margin: var(--k-space-4);
+  padding: var(--k-space-4);
+  border: var(--k-border-thin) solid var(--k-line-strong);
+  border-radius: var(--k-radius-sm);
+  background: var(--k-panel-raised);
+  color: var(--k-text);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
 
 .survey-workbench-embed {
   overflow: hidden;

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

@@ -100,7 +100,20 @@ export interface PersistentReviewSessionEventStoreOptions {
     readonly persist: (request: ReviewSessionPersistenceRequest) => Promise<ReviewSessionPersistenceResult | void>;
     readonly onStatusChange?: (state: ReviewSessionPersistenceState) => void;
 }
+/** Serializable producer-owned display hints. Never alter canonical items, events or apply authority. */
+export interface ReviewQueuePresentation {
+    readonly title?: string;
+    readonly context?: string;
+    readonly items?: Readonly<Record<string, {
+        readonly title?: string;
+        readonly kind?: "acknowledgment" | "choice";
+        readonly candidateLabels?: Readonly<Record<string, string>>;
+    }>>;
+}
 export interface MountReviewWorkbenchOptions {
+    readonly queuePresentation?: ReviewQueuePresentation;
+    /** A host that owns submission can hide the local apply/export control. */
+    readonly hideApply?: boolean;
     readonly eventStore?: ReviewSessionEventStore;
     readonly presentationAdapter?: ReviewPresentationAdapter;
     /**
@@ -238,6 +251,8 @@ export declare function createPersistentReviewSessionEventStore(options: Persist
 export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, _events?: readonly ReviewSessionEvent[], options?: {
     readonly presentationAdapter?: ReviewPresentationAdapter;
     readonly queueView?: Partial<ReviewQueueView>;
+    readonly queuePresentation?: ReviewQueuePresentation;
+    readonly hideApply?: boolean;
     /** See {@link MountReviewWorkbenchOptions.extractionImport}. */
     readonly extractionImport?: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult;
     /** See {@link MountReviewWorkbenchOptions.fieldStates}. */

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

@@ -135,10 +135,12 @@ function buildDecisionCardAuthorizing(state, adapter) {
  * Renders the decision card's prompt for a review item and decision.
  *
  * It is rebuilt from the item when the decision is built, not captured from
- * what a reviewer's screen showed: it records what the card states for this
- * item, with the same presentation adapter, target label and value text.
+ * what a reviewer's screen showed: it records a deterministic semantic basis
+ * from the canonical item, decision and presentation adapter. Queue display
+ * hints (title, context, action labels) are not a verbatim prompt capture and
+ * do not change this server-reconstructable authorizing basis.
  *
- * Format mirrors the review question shown in the workbench header:
+ * The current/proposed semantic form is:
  * "For {target}, decide whether {proposed} should replace {current}."
  * followed by the selected decision label so the block is self-contained.
  */
@@ -523,7 +525,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), options.fieldStates);
+    return renderReviewQueueSessionHtml(session, options.presentationAdapter, normalizeReviewQueueView(options.queueView), attestReviewQueueExtraction(session.items, options.extractionImport), options.fieldStates, options.queuePresentation, options.hideApply);
 }
 /**
  * The visual/decision state of a field card, derived from the reviewer's local
@@ -611,7 +613,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, fieldStates) {
+function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, attestation, fieldStates, queuePresentation, hideApply) {
     // 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") {
@@ -641,7 +643,7 @@ function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, a
         <div class="top">
           <div class="subj">
             <p class="eyebrow">Proposed changes</p>
-            <h1>${escapeHtml(headerTitle)}</h1>
+            <h1>${escapeHtml(queuePresentation?.title ?? headerTitle)}</h1>
           </div>
         </div>
         <div class="meta">
@@ -650,9 +652,10 @@ function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, a
         <div class="progress">
           <div class="bar"><i style="width:${progressPct}%"></i></div>
           <span class="ptext"><b data-testid="decided-count">${decidedCount}</b> of <b>${totalCount}</b> decided</span>
-          <button class="apply" type="button" data-testid="apply-button"${decidedCount === 0 ? " disabled" : ""}>Apply ${decidedCount} decision${decidedCount === 1 ? "" : "s"}</button>
+          ${hideApply ? "" : `<button class="apply" type="button" data-testid="apply-button"${decidedCount === 0 ? " disabled" : ""}>Apply ${decidedCount} decision${decidedCount === 1 ? "" : "s"}</button>`}
         </div>
       </header>
+      ${queuePresentation?.context ? `<section class="review-context" data-testid="review-context" aria-label="Review context">${escapeHtml(queuePresentation.context)}</section>` : ""}
       ${fieldStates ? renderFieldStatesHtml(fieldStates, session) : ""}
       <nav class="queue-controls" aria-label="Review queue navigation">
         <label>
@@ -673,7 +676,7 @@ function renderReviewQueueSessionHtml(session, presentationAdapter, queueView, a
         </div>` : ""}
       </nav>
       <div class="fields" data-testid="review-fields">
-        ${window.items.map((item) => renderFieldCard(item, session, presentationAdapter)).join("")
+        ${window.items.map((item) => renderFieldCard(item, session, presentationAdapter, queuePresentation?.items?.[item.metadata.name])).join("")
         || '<p class="queue-empty">No review fields match the current search and disposition.</p>'}
       </div>
       ${renderFooterTally(session)}
@@ -691,7 +694,7 @@ function queueDispositionOptions(selected) {
     ];
     return options.map(([value, label]) => `<option value="${value}"${selected === value ? " selected" : ""}>${label}</option>`).join("");
 }
-function renderFieldCard(item, session, presentationAdapter) {
+function renderFieldCard(item, session, presentationAdapter, hints) {
     const decision = session.decisionsByItemName[item.metadata.name];
     const state = fieldCardState(item, decision);
     const decided = decision !== undefined;
@@ -703,6 +706,10 @@ function renderFieldCard(item, session, presentationAdapter) {
     const conflict = proposedCandidates.length > 1;
     const proposed = proposedCandidates.length === 1 ? proposedCandidates[0] : undefined;
     const presentation = buildReviewItemPresentation(item, presentationAdapter);
+    const title = hints?.title ?? presentation.targetLabel;
+    const acknowledgment = hints?.kind === "acknowledgment" && proposed !== undefined;
+    const choice = hints?.kind === "choice";
+    const statusLabel = decision === "could-not-confirm" ? "Could not confirm" : choice ? (decided ? "Action recorded" : "Choose an action") : acknowledgment ? (decided ? "Reviewed" : "Needs review") : chipLabel(state, current !== undefined && !isEmptyValue(current.value), conflict ? proposedCandidates.length : undefined);
     const hasCurrentValue = current !== undefined && !isEmptyValue(current.value);
     const kind = hasCurrentValue ? "Update" : "New";
     const keepLabel = hasCurrentValue ? "Keep current" : conflict ? "Reject all values" : "Leave unset";
@@ -734,26 +741,28 @@ function renderFieldCard(item, session, presentationAdapter) {
       <div class="stripe"></div>
       <div class="fbody">
         <div class="frow1">
-          <span class="fname">${escapeHtml(presentation.targetLabel)}</span>
+          <span class="fname">${escapeHtml(title)}</span>
           <span class="fkind">${kind}</span>
-          <span class="chip ${state} push" data-testid="field-chip">${chipLabel(state, hasCurrentValue, conflict ? proposedCandidates.length : undefined)}</span>
+          <span class="chip ${state} push" data-testid="field-chip">${statusLabel}</span>
         </div>
         ${proposed
         ? renderDiffRow(item, current, proposed, presentation.targetLabel, decided, effectiveProposedText, currentPresentationText)
         : proposedCandidates.length > 1
-            ? renderConflictingProposals(item, proposedCandidates, presentationAdapter, presentation.targetLabel, decision, session.selectedCandidateIdsByItemName?.[item.metadata.name])
+            ? renderConflictingProposals(item, proposedCandidates, presentationAdapter, presentation.targetLabel, decision, session.selectedCandidateIdsByItemName?.[item.metadata.name], choice ? hints : undefined)
             : "<p class=\"field-value\">No proposed value is available for this field.</p>"}
         ${proposed ? renderProvenanceRow(item, proposed, presentationAdapter, isScoreBlind(session)) : ""}
         ${renderExtractionImportNotes(presentation)}
         ${isScoreBlind(session) ? "" : renderVerificationNotes(candidateVerificationNotes(item, decision === "accept-proposed" ? editedValue : undefined))}
+        ${choice ? renderReviewerNote(item, session) : ""}
         <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>
-          <label class="wrong">
+          ${acknowledgment || keepDecision === undefined || (choice && !current) ? "" : `<button class="btn keep" type="button" data-testid="keep-current" data-item-name="${escapeHtml(item.metadata.name)}">${escapeHtml(choice && current ? hints?.candidateLabels?.[current.id] ?? keepLabel : keepLabel)}</button>`}
+          ${proposed ? `<button class="btn use" type="button" data-testid="use-proposed" data-item-name="${escapeHtml(item.metadata.name)}">${acknowledgment ? "Mark reviewed" : choice ? escapeHtml(hints?.candidateLabels?.[proposed.id] ?? proposedPresentationText) : "Use proposed"}</button>
+          ${acknowledgment || choice ? "" : `<label class="wrong">
             <input type="checkbox" class="wrongbox" data-testid="wrong-toggle" data-item-name="${escapeHtml(item.metadata.name)}">
             Suggestion was wrong
           </label>
-          <button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>` : ""}
+          <button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>`}
+          ${acknowledgment || choice ? `<button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>` : ""}` : ""}
           ${conflict ? `<button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>` : ""}
         </div>
         <!--
@@ -765,10 +774,10 @@ function renderFieldCard(item, session, presentationAdapter) {
         -->
         <span class="derr" data-testid="decision-error" role="alert" hidden></span>
         <div class="decided">
-          <span class="chip ${state}" data-testid="decided-chip">${chipLabel(state, hasCurrentValue, conflict ? proposedCandidates.length : undefined)}</span>
+          <span class="chip ${state}" data-testid="decided-chip">${statusLabel}</span>
           <button class="undo" type="button" data-testid="undo-decision" data-item-name="${escapeHtml(item.metadata.name)}">Change</button>
         </div>
-        ${renderAuditDetails(item, current, proposed, session, presentationAdapter)}
+        ${renderAuditDetails(item, current, proposed, session, presentationAdapter, choice)}
       </div>
     </section>
   `;
@@ -782,23 +791,24 @@ function renderFieldCard(item, session, presentationAdapter) {
  * one value. Proposals excluded at import are not candidates: they are listed
  * by {@link renderExtractionImportNotes} and cannot be chosen.
  */
-function renderConflictingProposals(item, candidates, presentationAdapter, targetLabel, decision, selectedCandidateId) {
+function renderConflictingProposals(item, candidates, presentationAdapter, targetLabel, decision, selectedCandidateId, hints) {
     const chose = decision === "select-proposed";
     const values = candidates.map((candidate) => {
         const text = buildReviewCandidatePresentation(item, candidate, presentationAdapter, targetLabel).valueText;
+        const actionLabel = hints?.candidateLabels?.[candidate.id] ?? text;
         const excerpt = candidate.locator?.excerpt;
         const chosen = chose && candidate.id === selectedCandidateId;
         const mark = chose
             ? ` <span class="choice-tag ${chosen ? "chosen" : "not-chosen"}" data-testid="choice-tag">${chosen ? "Chosen" : "Not chosen"}</span>`
             : "";
         const control = decision === undefined
-            ? `<button class="btn choose" type="button" data-testid="select-value" data-item-name="${escapeHtml(item.metadata.name)}" data-candidate-id="${escapeHtml(candidate.id)}" aria-label="Use ${escapeHtml(text)} for ${escapeHtml(targetLabel)}">Use this value</button>`
+            ? `<button class="btn choose" type="button" data-testid="select-value" data-item-name="${escapeHtml(item.metadata.name)}" data-candidate-id="${escapeHtml(candidate.id)}" aria-label="${hints ? escapeHtml(actionLabel) : `Use ${escapeHtml(text)} for ${escapeHtml(targetLabel)}`}">${hints ? escapeHtml(actionLabel) : "Use this value"}</button>`
             : "";
         return `<li data-testid="conflicting-value" data-candidate-id="${escapeHtml(candidate.id)}"${chose ? ` data-chosen="${chosen ? "true" : "false"}"` : ""}>
         <span class="conflict-text"><span class="vtext">${escapeHtml(text)}</span>${excerpt ? ` <q>${escapeHtml(excerpt)}</q>` : ""}${mark}</span>${control}
       </li>`;
     }).join("");
-    const intro = decision === undefined
+    const intro = hints ? (decision === undefined ? "Choose an action. Add a reviewer note when a correction or explanation is needed." : "Action recorded.") : decision === undefined
         ? `${candidates.length} different values were proposed for this field. Use the value the source supports, reject them all, or mark the field Could not confirm with a reason.`
         : chose
             ? `${candidates.length} different values were proposed for this field. One was chosen; ${candidates.length === 2 ? "the other was" : "the others were"} seen and not chosen.`
@@ -1066,7 +1076,10 @@ function renderConfidenceMeter(confidence) {
  * here is secondary detail tucked behind one `<details>` toggle, kept off the
  * primary review surface.
  */
-function renderAuditDetails(item, current, proposed, session, presentationAdapter) {
+function renderReviewerNote(item, session) {
+    return `<label class="note-field"><span class="field-label">Reviewer note</span><textarea data-testid="reviewer-note" data-item-name="${escapeHtml(item.metadata.name)}">${escapeHtml(session.notesByItemName[item.metadata.name] ?? "")}</textarea></label>`;
+}
+function renderAuditDetails(item, current, proposed, session, presentationAdapter, noteOnCard = false) {
     const decision = session.decisionsByItemName[item.metadata.name];
     const note = session.notesByItemName[item.metadata.name] ?? "";
     const definition = decision ? workbenchDecisionDefinitions[decision] : undefined;
@@ -1091,10 +1104,7 @@ function renderAuditDetails(item, current, proposed, session, presentationAdapte
     <details class="audit-details" data-testid="audit-details">
       <summary>Audit details</summary>
       <div class="audit-body">
-        <label class="note-field">
-          <span class="field-label">Reviewer note</span>
-          <textarea data-testid="reviewer-note" data-item-name="${escapeHtml(item.metadata.name)}">${escapeHtml(note)}</textarea>
-        </label>
+        ${noteOnCard ? "" : renderReviewerNote(item, session)}
         ${definition ? `<p class="field-value"><span class="field-label">Decision effect</span> ${escapeHtml(definition.effect)}</p>` : ""}
         ${renderProducerFeedbackTags(item)}
         <dl class="field-stack compact">
@@ -1459,7 +1469,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, options.fieldStates),
+        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter, queueView, attestation, options.fieldStates, options.queuePresentation, options.hideApply),
         setDecision,
         clearDecision,
         updateReviewerNote,
@@ -1479,8 +1489,8 @@ function reviewSessionStorageKey(session, keyPrefix) {
     const itemNames = buildReviewSessionResource(session).spec.reviewItemNames.join(",");
     return `${keyPrefix}:${itemNames}`;
 }
-function renderCurrentState(root, session, controller, presentationAdapter, queueView, attestation, fieldStates) {
-    root.innerHTML = renderReviewQueueSessionHtml(session, presentationAdapter, queueView ?? normalizeReviewQueueView(undefined), attestation ?? attestReviewQueueExtraction(session.items, undefined), fieldStates);
+function renderCurrentState(root, session, controller, presentationAdapter, queueView, attestation, fieldStates, queuePresentation, hideApply) {
+    root.innerHTML = renderReviewQueueSessionHtml(session, presentationAdapter, queueView ?? normalizeReviewQueueView(undefined), attestation ?? attestReviewQueueExtraction(session.items, undefined), fieldStates, queuePresentation, hideApply);
     bindFieldCardInteractions(root, controller);
     bindApplyButton(root, controller);
     bindClampToggles(root);

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

@@ -1242,3 +1242,14 @@ pre[data-testid="decision-payload"] {
     transition: none !important;
   }
 }
+
+.review-context {
+  margin: var(--k-space-4);
+  padding: var(--k-space-4);
+  border: var(--k-border-thin) solid var(--k-line-strong);
+  border-radius: var(--k-radius-sm);
+  background: var(--k-panel-raised);
+  color: var(--k-text);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "8.1.1",
+  "version": "8.2.1",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -59,18 +59,17 @@
     "test:browser:concurrent": "npm run build && node scripts/test-playwright-concurrency.mjs",
     "verify": "npm run check:ui-token-drift && npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run test:package-smoke && npm run check:review-workbench && npm run test:browser && npm run test:browser:concurrent",
     "check:content-boundary": "node --test tests/content-boundary-script.test.cjs && node scripts/check-content-boundary.cjs",
-    "check:decisions": "node scripts/check-decisions.cjs check",
+    "check:decisions": "npx -y --package=https://codeload.github.com/kontourai/corpus/tar.gz/08c62ccd72880ff4bd4c378ae252ad437b4b4fb5 -- corpus decisions check --base ${DECISIONS_BASE:-origin/main}",
     "check:guards": "node scripts/check-guards.mjs",
-    "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
-    "freeze:adrs": "node scripts/freeze-adrs.mjs",
+    "gen:decisions-index": "npx -y --package=https://codeload.github.com/kontourai/corpus/tar.gz/08c62ccd72880ff4bd4c378ae252ad437b4b4fb5 -- corpus decisions index",
     "sync:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs",
     "check:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs --check",
     "check:review-workbench": "npm run check:review-workbench:static && npm run check:generated-css",
     "check:review-workbench:static": "npm run build && node scripts/check-review-workbench.cjs",
     "setup:repo-hooks": "node scripts/setup-repo-hooks.cjs",
     "validate:repo-hooks": "node scripts/validate-repo-hooks.cjs",
-    "docs:build": "npx -y github:kontourai/docs-kit#efe0bfe4ad247861ef661c907f6354d6167fa3be docs-kit build",
-    "docs:check": "npx -y github:kontourai/docs-kit#efe0bfe4ad247861ef661c907f6354d6167fa3be docs-kit check",
+    "docs:build": "npx -y --package=https://codeload.github.com/kontourai/corpus/tar.gz/08c62ccd72880ff4bd4c378ae252ad437b4b4fb5 -- corpus build",
+    "docs:check": "npx -y --package=https://codeload.github.com/kontourai/corpus/tar.gz/08c62ccd72880ff4bd4c378ae252ad437b4b4fb5 -- corpus check",
     "docs:demo": "npm run build && node scripts/build-demo.mjs",
     "check:generated-css": "node scripts/copy-review-workbench-package-assets.cjs --check",
     "check:ui-token-drift": "npm run check:generated-css && npm run check:review-workbench-assets",
@@ -93,7 +92,8 @@
   "devDependencies": {
     "@kontourai/flow-agents": "5.10.0",
     "@kontourai/traverse": "^3.0.1",
-    "@kontourai/ui": "^1.18.0",
+    "@kontourai/ui": "^1.20.0",
+    "@kontourai/veritas": "1.11.2",
     "@playwright/test": "^1.62.0",
     "@types/node": "^26.1.2",
     "typescript": "^7.0.2"