@kontourai/survey 2.2.4 → 2.4.0

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

@@ -4,9 +4,12 @@ import { candidateForDecision, keepActionDecision, buildReviewSessionEvent, buil
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
 import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "./review-presentation.js";
-import { reviewResourceApiVersion, } from "../review-resource.js";
+import { findSoleCandidateById, reviewResourceApiVersion, } from "../review-resource.js";
 import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review-authorizing.js";
 import { humanizeIdentifier } from "./review-presentation.js";
+import { createAuditFactTrace, } from "./audit-rows.js";
+export { reviewAuditRowKeys } from "./audit-rows.js";
+export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, } from "./queue-binding.js";
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, } from "./extraction-inspector.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
@@ -251,7 +254,7 @@ function buildReviewApplyActionContext(result, itemByName, issues) {
     };
 }
 function matchingSelectedCandidate(item, result) {
-    const candidate = item.spec.candidates.find((entry) => entry.id === result.selectedCandidateId);
+    const candidate = findSoleCandidateById(item, result.selectedCandidateId);
     return candidate
         && candidate.role === result.selectedCandidateRole
         && structuralEqual(candidate.value, result.selectedValue)
@@ -660,6 +663,14 @@ function renderFieldCard(item, session, presentationAdapter) {
           </label>
           <button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>` : ""}
         </div>
+        <!--
+          A control's precondition message belongs where the control is. The
+          reason "Could not confirm" needs lives in the collapsed audit
+          accordion, so writing the failure only into that textarea's validation
+          bubble put it somewhere the reviewer could not see at the moment they
+          clicked, and the button read as permanently dead (kontourai/survey#208).
+        -->
+        <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)}</span>
           <button class="undo" type="button" data-testid="undo-decision" data-item-name="${escapeHtml(item.metadata.name)}">Change</button>
@@ -886,6 +897,10 @@ function renderAuditDetails(item, current, proposed, session, presentationAdapte
     };
     const reviewDecisionPayload = buildReviewDecision(state);
     const preview = buildSurfaceProjectionPreview(item, reviewDecisionPayload, presentationAdapter);
+    // Seeded with what the card face already shows, so the audit surface never
+    // reprints it. Passed down through every section: the sections render in DOM
+    // order, so "first placement wins" is also "highest-context placement wins".
+    const trace = createAuditFactTrace(proposed ? [{ of: proposed.id, property: "locator.excerpt", value: proposed.locator?.excerpt }] : []);
     return `
     <details class="audit-details" data-testid="audit-details">
       <summary>Audit details</summary>
@@ -897,17 +912,17 @@ function renderAuditDetails(item, current, proposed, session, presentationAdapte
         ${definition ? `<p class="field-value"><span class="field-label">Decision effect</span> ${escapeHtml(definition.effect)}</p>` : ""}
         ${renderProducerFeedbackTags(item)}
         <dl class="field-stack compact">
-          ${current ? fieldItem("Current candidate ID", current.id) : ""}
-          ${proposed ? fieldItem("Proposed candidate ID", proposed.id) : ""}
-          ${proposed ? fieldItem("Claim ID", proposed.claimTarget.claimId ?? proposed.claimTarget.fieldOrBehavior) : ""}
-          ${proposed ? fieldItem("Raw Source ID", proposed.source.sourceId ?? proposed.source.sourceRef) : ""}
-          ${proposed?.locator ? fieldItem("Locator", proposed.locator.locator ?? proposed.locator.scheme) : ""}
-          ${proposed?.extraction.model ? fieldItem("Model", proposed.extraction.model) : ""}
-          ${proposed ? fieldItem("Extractor", proposed.extraction.extractor ?? "unknown") : ""}
-          ${proposed ? fieldItem("Extracted at", proposed.extraction.extractedAt ?? "unknown") : ""}
+          ${current ? fieldItem("current-candidate-id", "Current candidate ID", current.id) : ""}
+          ${proposed ? fieldItem("proposed-candidate-id", "Proposed candidate ID", proposed.id) : ""}
+          ${proposed ? fieldItem("claim-id", "Claim ID", proposed.claimTarget.claimId ?? proposed.claimTarget.fieldOrBehavior) : ""}
+          ${proposed ? placementItem(trace, { of: proposed.id, property: "source.sourceId" }, "raw-source-id", "Raw Source ID", proposed.source.sourceId ?? proposed.source.sourceRef) : ""}
+          ${proposed?.locator ? fieldItem("locator", "Locator", proposed.locator.locator ?? proposed.locator.scheme) : ""}
+          ${proposed?.extraction.model ? fieldItem("model", "Model", proposed.extraction.model) : ""}
+          ${proposed ? placementItem(trace, { of: proposed.id, property: "extraction.extractor" }, "extractor", "Extractor", proposed.extraction.extractor ?? "unknown") : ""}
+          ${proposed ? fieldItem("extracted-at", "Extracted at", proposed.extraction.extractedAt ?? "unknown") : ""}
         </dl>
         ${preview
-        ? `<div class="preview-section-grid">${renderSurfacePreviewSections(preview)}</div><p class="preview-disclaimer preview-disclaimer-footer">${escapeHtml(preview.postureDisclaimer)}</p>`
+        ? `<div class="preview-section-grid">${renderSurfacePreviewSections(preview, trace)}</div><p class="preview-disclaimer preview-disclaimer-footer">${escapeHtml(preview.postureDisclaimer)}</p>`
         : "<p class=\"preview-disclaimer\">No decision recorded yet — pick an option above to preview the saved record.</p>"}
         ${reviewDecisionPayload
         ? `<details class="reference-details">
@@ -949,57 +964,83 @@ function renderFooterTally(session) {
     </footer>
   `;
 }
-function renderSurfacePreviewSections(preview) {
+function renderSurfacePreviewSections(preview, trace) {
+    // Every row below describes the SELECTED candidate. When the reviewer kept the
+    // current value, that is a different record from the one the ID stack above
+    // describes, so none of these are repeat placements and all of them render —
+    // which is the point of keying on fact identity rather than on strings.
+    const selected = preview.canonicalClaim.candidateId;
     return [
         renderCandidateHistory(preview),
-        renderSourceEvidence(preview),
+        renderSourceEvidence(preview, trace, selected),
         renderReviewEvent(preview),
-        renderIntegrityPosture(preview),
+        renderIntegrityPosture(preview, trace, selected),
         renderAuthorityTrace(preview),
     ].join("");
 }
 function renderReviewEvent(preview) {
+    // A could-not-confirm resolution projects no review event; five rows reading
+    // "unknown / not recorded / pending / not provided" report an absence the
+    // decided chip on the card face already states (kontourai/survey#207).
+    if (!preview.reviewEvent) {
+        return "";
+    }
     return `
     <section class="preview-section" data-testid="surface-review-event">
       <h3>${escapeHtml("Review event")}</h3>
       <dl class="field-stack compact">
-        ${fieldItem("Actor", preview.reviewEvent?.actor ?? "unknown")}
-        ${fieldItem("Reviewed at", preview.reviewEvent?.reviewedAt ?? "not recorded")}
-        ${fieldItem("Status", preview.reviewEvent?.status ?? "pending")}
-        ${fieldItem("Rationale", preview.reviewEvent?.rationale ?? "No reviewer rationale provided.", "rationale-clamp")}
-        ${fieldItem("Outcome", preview.reviewEvent?.reviewOutcomeId ?? "not provided")}
+        ${fieldItem("actor", "Actor", preview.reviewEvent.actor)}
+        ${fieldItem("reviewed-at", "Reviewed at", preview.reviewEvent.reviewedAt)}
+        ${fieldItem("status", "Status", preview.reviewEvent.status)}
+        ${fieldItem("rationale", "Rationale", preview.reviewEvent.rationale, "rationale-clamp")}
+        ${fieldItem("outcome", "Outcome", preview.reviewEvent.reviewOutcomeId)}
       </dl>
     </section>
   `;
 }
-function renderIntegrityPosture(preview) {
+function renderIntegrityPosture(preview, trace, selected) {
     return renderPreviewSection("Integrity posture", "surface-integrity-posture", [
-        ["Checksum", preview.integrityPosture.checksum],
-    ], undefined, [
-        ["Candidate set ID", preview.integrityPosture.candidateSetId],
-        ["Raw source ID", preview.integrityPosture.rawSourceId],
-        ["Extraction ID", preview.integrityPosture.extractionId],
-    ]);
+        { key: "checksum", label: "Checksum", value: preview.integrityPosture.checksum },
+    ], [
+        { key: "candidate-set-id", label: "Candidate set ID", value: preview.integrityPosture.candidateSetId },
+        { key: "raw-source-id", label: "Raw source ID", value: preview.integrityPosture.rawSourceId, fact: { of: selected, property: "source.sourceId" } },
+        { key: "extraction-id", label: "Extraction ID", value: preview.integrityPosture.extractionId, fact: { of: selected, property: "extraction.extractionId" } },
+    ], trace);
 }
 function renderAuthorityTrace(preview) {
+    // An absent portable authority trace is the common case, and the two rows
+    // that said so were the same sentence on every card of every queue. The
+    // posture statement it repeated lives in the footer disclaimer; the data
+    // stays on SurfaceProjectionPreview for hosts that project it.
+    if (preview.authorityTrace.status === "empty") {
+        return "";
+    }
     return renderPreviewSection("Authority trace", "surface-authority-trace", [
-        ["Status", preview.authorityTrace.label],
-        ["Detail", preview.authorityTrace.detail],
-    ], preview.authorityTrace.status === "empty" ? " is-neutral" : "");
+        { key: "authority-trace-status", label: "Status", value: preview.authorityTrace.label },
+        { key: "authority-trace-detail", label: "Detail", value: preview.authorityTrace.detail },
+    ]);
 }
 function renderCandidateHistory(preview) {
+    // Nothing unselected is not history; the row that said so carried no fact.
     if (preview.candidateHistory.length === 0) {
-        return renderPreviewSection("Unselected candidate history", "surface-candidate-history", [["History", "No unselected candidates."]], undefined, []);
+        return "";
     }
     const VISIBLE_COUNT = 3;
     const total = preview.candidateHistory.length;
     const visibleCandidates = preview.candidateHistory.slice(0, VISIBLE_COUNT);
     const overflowCandidates = preview.candidateHistory.slice(VISIBLE_COUNT);
-    const renderHistoryRows = (candidates) => candidates.flatMap((candidate) => [
-        fieldItem("History", candidate.historyLabel),
-        fieldItem("Value", candidate.value),
-    ]).join("");
-    const referenceRows = preview.candidateHistory.map((candidate) => fieldItem("Candidate ID", candidate.candidateId)).join("");
+    // `historyLabel` is the section's own heading, so a "History: Unselected
+    // candidate history" row above every value restated the <h3> once per
+    // candidate. The label stays on PreviewCandidateHistory for hosts that
+    // project it without a heading of their own.
+    const renderHistoryRows = (candidates) => candidates.map((candidate) => fieldItem("history-value", "Value", candidate.value)).join("");
+    // Deliberately NOT deduplicated. With two candidates this repeats the ID
+    // stack's "Current candidate ID", but it is the only row that names WHICH
+    // unselected candidate a value belongs to, it stops being a repeat the moment
+    // there are three, and suppressing it would make this section's disclosure
+    // appear and disappear with the candidate count — structure a host would then
+    // have to key on. Row-level suppression is what `data-audit-row` is for.
+    const referenceRows = preview.candidateHistory.map((candidate) => fieldItem("candidate-id", "Candidate ID", candidate.candidateId)).join("");
     const overflowHtml = overflowCandidates.length > 0
         ? `<div class="history-overflow">${renderHistoryRows(overflowCandidates)}</div>`
         : "";
@@ -1019,53 +1060,75 @@ function renderCandidateHistory(preview) {
         </dl>
         ${expanderHtml}
       </div>
-      ${preview.candidateHistory.length > 0 ? `<details class="reference-details">
+      <details class="reference-details">
         <summary>IDs and trace links</summary>
         <dl class="field-stack compact">${referenceRows}</dl>
-      </details>` : ""}
+      </details>
     </section>
   `;
 }
-function renderSourceEvidence(preview) {
-    const clampedExcerptHtml = fieldItemClamped("Excerpt", preview.sourceEvidence.excerpt, "excerpt");
+function renderSourceEvidence(preview, trace, selected) {
+    // The excerpt is quoted on the card face for the PROPOSED candidate. A
+    // decision that selected some other candidate has a different excerpt, and it
+    // renders here.
+    const clampedExcerptHtml = trace.isRepeatPlacement({ of: selected, property: "locator.excerpt" }, preview.sourceEvidence.excerpt)
+        ? ""
+        : fieldItemClamped("excerpt", "Excerpt", preview.sourceEvidence.excerpt, "excerpt");
     return `
     <section class="preview-section" data-testid="surface-source-evidence">
       <h3>${escapeHtml("Raw Source")}</h3>
       <dl class="field-stack compact">
-        ${fieldItem("Source Reference", preview.sourceEvidence.sourceRef)}
+        ${fieldItem("source-reference", "Source Reference", preview.sourceEvidence.sourceRef)}
         ${clampedExcerptHtml}
-        ${fieldItem("Extractor", preview.sourceEvidence.extractor)}
-        ${fieldItem("Observed", preview.sourceEvidence.observedAt)}
+        ${placementItem(trace, { of: selected, property: "extraction.extractor" }, "extractor", "Extractor", preview.sourceEvidence.extractor)}
+        ${fieldItem("observed", "Observed", preview.sourceEvidence.observedAt)}
         ${preview.sourceEvidence.sourceAuthority ? [
-        fieldItem("Source authority class", preview.sourceEvidence.sourceAuthority.authorityClass),
-        fieldItem("Declared by", preview.sourceEvidence.sourceAuthority.declaredBy),
-        fieldItem("Authority scope", preview.sourceEvidence.sourceAuthority.scope),
+        fieldItem("source-authority-class", "Source authority class", preview.sourceEvidence.sourceAuthority.authorityClass),
+        fieldItem("declared-by", "Declared by", preview.sourceEvidence.sourceAuthority.declaredBy),
+        fieldItem("authority-scope", "Authority scope", preview.sourceEvidence.sourceAuthority.scope),
     ].join("") : ""}
       </dl>
       ${renderReferenceDetails([
-        ["Raw Source ID", preview.sourceEvidence.sourceId],
-        ["Extraction ID", preview.sourceEvidence.extractionId],
-    ])}
+        { key: "raw-source-id", label: "Raw Source ID", value: preview.sourceEvidence.sourceId, fact: { of: selected, property: "source.sourceId" } },
+        { key: "extraction-id", label: "Extraction ID", value: preview.sourceEvidence.extractionId, fact: { of: selected, property: "extraction.extractionId" } },
+    ], trace)}
     </section>
   `;
 }
-function renderPreviewSection(title, testId, rows, extraClass = "", references = []) {
+function renderPreviewRows(rows, trace) {
+    return rows
+        .map((row) => (row.fact && trace
+        ? placementItem(trace, row.fact, row.key, row.label, row.value)
+        : fieldItem(row.key, row.label, row.value)))
+        .join("");
+}
+function renderPreviewSection(title, testId, rows, references = [], trace) {
     return `
-    <section class="preview-section${extraClass}" data-testid="${testId}">
+    <section class="preview-section" data-testid="${testId}">
       <h3>${escapeHtml(title)}</h3>
       <dl class="field-stack compact">
-        ${rows.map(([label, value]) => fieldItem(label, value)).join("")}
+        ${renderPreviewRows(rows, trace)}
       </dl>
-      ${references.length > 0 ? renderReferenceDetails(references) : ""}
+      ${references.length > 0 ? renderReferenceDetails(references, trace) : ""}
     </section>
   `;
 }
-function renderReferenceDetails(references) {
+/**
+ * The per-section "IDs and trace links" list.
+ *
+ * Every call site includes at least one reference that is a first placement and
+ * so can never be suppressed — Raw Source keeps its extraction id, Integrity
+ * posture its candidate set id, and the history section's candidate ids are
+ * exempt outright. The disclosure therefore does not appear and disappear with
+ * the data, which is what a host selecting on structure would otherwise be
+ * exposed to. Keep that property when adding a reference list.
+ */
+function renderReferenceDetails(references, trace) {
     return `
     <details class="reference-details">
       <summary>IDs and trace links</summary>
       <dl class="field-stack compact">
-        ${references.map(([label, value]) => fieldItem(label, value)).join("")}
+        ${renderPreviewRows(references, trace)}
       </dl>
     </details>
   `;
@@ -1253,6 +1316,24 @@ function queueSessionFromStartState(startState) {
         actorId: startState.actorId,
     };
 }
+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
+ * tries to focus it or anchor a validation bubble on it.
+ *
+ * The browser will not show a validation message on, or move focus into, a
+ * control inside a closed `<details>` — the call silently does nothing. Any
+ * decision path that blocks on an input the reviewer cannot currently see must
+ * go through here, or the control it guards reads as dead (kontourai/survey#208,
+ * after #201 and #203 in the same family).
+ */
+function revealControl(control) {
+    let ancestor = control?.parentElement?.closest?.("details") ?? null;
+    while (ancestor) {
+        ancestor.open = true;
+        ancestor = ancestor.parentElement?.closest?.("details") ?? null;
+    }
+}
 function bindFieldCardInteractions(root, controller) {
     root.querySelectorAll("[data-testid='use-proposed']").forEach((button) => {
         button.addEventListener("click", () => {
@@ -1312,12 +1393,25 @@ function bindFieldCardInteractions(root, controller) {
             const note = controller.currentSession().notesByItemName[itemName]?.trim() ?? "";
             const field = button.closest("[data-testid='review-field']");
             const textarea = field?.querySelector("[data-testid='reviewer-note']");
+            const errorEl = field?.querySelector("[data-testid='decision-error']");
             if (!note) {
-                textarea?.setCustomValidity?.("A reason is required when you could not confirm.");
-                textarea?.reportValidity?.();
+                // Say it where the button is, then open the way to the input that
+                // satisfies it. Focusing (and validating) a control inside a collapsed
+                // <details> is a no-op the reviewer never sees (kontourai/survey#208).
+                if (errorEl) {
+                    errorEl.textContent = COULD_NOT_CONFIRM_REASON_REQUIRED;
+                    errorEl.hidden = false;
+                }
+                textarea?.setCustomValidity?.(COULD_NOT_CONFIRM_REASON_REQUIRED);
+                revealControl(textarea);
                 textarea?.focus();
+                textarea?.reportValidity?.();
                 return;
             }
+            if (errorEl) {
+                errorEl.textContent = "";
+                errorEl.hidden = true;
+            }
             textarea?.setCustomValidity?.("");
             controller.setDecision(itemName, "could-not-confirm");
             controller.renderCurrentState();
@@ -1332,6 +1426,13 @@ function bindFieldCardInteractions(root, controller) {
     root.querySelectorAll("[data-testid='reviewer-note']").forEach((textarea) => {
         textarea.addEventListener("input", () => {
             textarea.setCustomValidity?.("");
+            const decisionError = textarea
+                .closest("[data-testid='review-field']")
+                ?.querySelector("[data-testid='decision-error']");
+            if (decisionError) {
+                decisionError.textContent = "";
+                decisionError.hidden = true;
+            }
             const itemName = textarea.dataset.itemName ?? "";
             controller.updateReviewerNote(itemName, textarea.value);
             refreshAuditPayloadForItem(textarea, controller, itemName);
@@ -1403,9 +1504,9 @@ function bindHistoryExpanders(root) {
         });
     });
 }
-function fieldItemClamped(label, value, extraClass = "") {
+function fieldItemClamped(key, label, value, extraClass = "") {
     return `
-    <div class="kv ${extraClass}">
+    <div class="kv ${extraClass}" data-audit-row="${key}">
       <dt class="field-label">${escapeHtml(label)}</dt>
       <div class="excerpt-clamp" data-clamp>
         <dd class="field-value">${escapeHtml(value)}</dd>
@@ -1414,14 +1515,26 @@ function fieldItemClamped(label, value, extraClass = "") {
     </div>
   `;
 }
-function fieldItem(label, value, extraClass = "") {
+function fieldItem(key, label, value, extraClass = "") {
     return `
-    <div class="kv ${extraClass}">
+    <div class="kv ${extraClass}" data-audit-row="${key}">
       <dt class="field-label">${escapeHtml(label)}</dt>
       <dd class="field-value">${escapeHtml(value)}</dd>
     </div>
   `;
 }
+/**
+ * A row for a fact the card renders in more than one place. Rendered only if
+ * this card has not already printed the SAME property of the SAME record with
+ * the same value; see {@link AuditFactTrace}.
+ *
+ * Only the four genuinely repeated placements go through here. Every other row
+ * has exactly one home and is rendered with {@link fieldItem} directly, so no
+ * row can ever be suppressed by a fact it has nothing to do with.
+ */
+function placementItem(trace, fact, key, label, value, extraClass = "") {
+    return trace.isRepeatPlacement(fact, value) ? "" : fieldItem(key, label, value, extraClass);
+}
 function escapeHtml(value) {
     return formatValue(value)
         .replaceAll("&", "&amp;")

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

@@ -48,11 +48,37 @@
 .inspector-pager button:disabled, .queue-pager button:disabled { opacity: .45; }
 .inspector-candidates { margin: 0; padding-left: 1.5rem; }
 .inspector-candidate { width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
-.inspector-source pre { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.inspector-source pre { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; line-height: 2.2; }
 .inspector-source mark { background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
 .inspector-candidate:focus { outline: 3px solid var(--k-active); outline-offset: 2px; }
-.highlight-anchor { display: inline-block; width: 1px; height: 1em; }
-.highlight-anchor:focus { outline: 3px solid var(--k-active); }
+/* An inert link target, one per candidate in the model, so a host's
+   `href="#<highlightElementId>"` always resolves. It is not a control and must
+   not behave like one: no size, no tab stop, nothing painted. */
+.highlight-anchor {
+  display: inline;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+/* The highlight IS the return control — the only part of this surface a reader
+   can see, so it is the thing to aim at. Full phrase width, already visibly
+   marked, one tab stop per painted highlight. */
+.source-highlight {
+  cursor: pointer;
+  border-radius: 2px;
+  /* Vertical padding on an inline box grows the hit area without moving the
+     line box, and the prepared text's line-height below leaves room for it, so
+     the target reaches ~24px tall without lines overlapping each other. The
+     phrase itself supplies the width. */
+  padding: 5px 3px;
+  margin: 0 -3px;
+}
+
+.source-highlight:focus-visible {
+  outline: 3px solid var(--k-active);
+  outline-offset: 1px;
+}
 .source-unavailable { color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
@@ -485,6 +511,22 @@ h1, h2, h3, p {
   display: none;
 }
 
+/* Why a decision was refused, next to the button that refused it. The input
+   that satisfies the precondition can be inside the collapsed audit accordion,
+   so the message cannot live only with the input (kontourai/survey#208). */
+.derr {
+  display: block;
+  margin-top: 6px;
+  text-align: right;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.derr[hidden] {
+  display: none;
+}
+
 /* confidence + provenance */
 
 .prov {
@@ -926,14 +968,6 @@ h1, h2, h3, p {
   text-transform: uppercase;
 }
 
-.preview-section.is-neutral {
-  background: var(--k-raised);
-}
-
-.preview-section.is-neutral h3 {
-  color: var(--k-faint);
-}
-
 .reference-details {
   margin-top: 8px;
 }

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

@@ -2,6 +2,7 @@ import { type DeriveReviewSessionApplyResultForSnapshotResult, type MapReviewWor
 import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
+import { type ReviewQueueBinding } from "./queue-binding.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
 export interface ServerReviewSessionRecord {
     readonly sessionName: string;
@@ -56,6 +57,19 @@ export interface DeriveServerReviewSessionApplyResultOptions {
     readonly currentSnapshot?: ReviewQueueSessionState;
     readonly currentEventCount?: number;
     readonly requiredResolvedItems?: ReviewSessionApplyResolutionRequirement;
+    /**
+     * The queue binding taken when this session opened (see
+     * ./queue-binding.ts). When present, the apply derivation refuses unless the
+     * record's snapshot — and the caller's current snapshot, when supplied —
+     * still matches the bound bytes and the bound item set, both directions.
+     *
+     * This is the check the record's own `snapshotHash` cannot provide: a record
+     * rebuilt from a mutated snapshot carries a hash of the mutated bytes and
+     * agrees with itself. The binding's authority is that it was written earlier,
+     * at queue construction, and carried unchanged — so it MUST come from the
+     * consumer's storage, not be recomputed at call time.
+     */
+    readonly binding?: ReviewQueueBinding;
 }
 export declare function createServerReviewSessionRecord(options: CreateServerReviewSessionRecordOptions): ServerReviewSessionRecord;
 export declare function hashReviewSessionSnapshot(snapshot: ReviewQueueSessionState): string;

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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { deriveReviewSessionApplyResultForSnapshot, mapReviewWorkbenchResultsToApplyActions, ReviewApplyActionMappingError, } from "./review-workbench.js";
 import { validateReviewDecisionMode, } from "./producer-decision-mode.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+import { assertReviewQueueBinding } from "./queue-binding.js";
 import { replayReviewSessionEvents } from "./review-queue-session.js";
 import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
@@ -92,6 +93,12 @@ export function assertServerReviewSessionEvents(record, events) {
     }
 }
 export function deriveServerReviewSessionApplyResult(options) {
+    if (options.binding) {
+        assertReviewQueueBinding(options.binding, options.record.snapshot, { sessionName: options.record.sessionName });
+        if (options.currentSnapshot) {
+            assertReviewQueueBinding(options.binding, options.currentSnapshot, { sessionName: options.record.sessionName });
+        }
+    }
     assertServerReviewSessionFreshness(options.record, options.record.snapshot);
     if (options.currentSnapshot) {
         assertServerReviewSessionFreshness(options.record, options.currentSnapshot, options.currentEventCount);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "2.2.4",
+  "version": "2.4.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -55,6 +55,7 @@
     "verify": "npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && 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:guards": "node scripts/check-guards.mjs",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
     "freeze:adrs": "node scripts/freeze-adrs.mjs",
     "sync:review-workbench-assets": "node scripts/sync-review-workbench-assets.cjs",