@kontourai/survey 2.2.4 → 2.4.0

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

@@ -0,0 +1,324 @@
+/**
+ * Queue-binding attestation: a decision is only projectable against the exact
+ * queue bytes it was recorded against.
+ *
+ * The binding is a small, serializable record created ONCE, when a review
+ * round/session opens, and carried unchanged by every later write. Validation
+ * compares a presented queue against that stored record. The division of labor
+ * is deliberate and is the entire security property:
+ *
+ * - **The consumer persists the binding beside the queue and never recomputes
+ *   it.** A digest a writer recomputes as it saves attests nothing — both sides
+ *   of the comparison then regenerate from the same mutable bytes and agree by
+ *   construction. That tautology shipped in a real consumer and let a
+ *   post-decision edit export a substituted value (kontourai/fieldwork#60).
+ * - **Survey owns the rule and the refusal.** What a queue edit looks like, in
+ *   both directions, and when a comparison is vacuous, is decided here so no
+ *   consumer rediscovers it four adversarial review rounds at a time
+ *   (kontourai/survey#213).
+ *
+ * The binding alone cannot survive a writer who edits the queue AND re-binds —
+ * hashing mutated bytes yields a self-consistent pair. For queues imported from
+ * an extraction envelope, {@link validateReviewQueueAgainstExtractionImport}
+ * narrows that hole to the record: it re-derives the canonical items from the
+ * presented import record and refuses a queue that diverges from it in either
+ * direction, so a queue edited independently of its record fails. What it
+ * attests is queue-to-record CONSISTENCY, not record integrity. The portable
+ * envelope carries the prepared artifact's digest and contentLength, never the
+ * prepared bytes, so a library handed only the record cannot verify proposal
+ * bytes against the digested artifact — a writer who edits the RECORD's
+ * proposals and re-derives the queue from the edited record presents a
+ * self-consistent pair this module blesses (pinned as a boundary test and by
+ * check:guards). Keeping the stored record equal to the record originally
+ * imported is the caller's storage obligation, and validating prepared bytes
+ * against `result.preparedArtifact.digest` does NOT discharge it: that digest
+ * covers the prepared artifact only, so it protects artifact integrity and
+ * stays green through a proposal rewrite. Preserving record integrity takes
+ * one of: a record digest/MAC anchored where the record's writer cannot
+ * reach, immutable or authenticated record storage, or independently
+ * re-deriving the proposals from trusted prepared bytes and comparing.
+ *
+ * Four bypasses from fieldwork#60's rounds, each a design input here:
+ * 1. Self-agreement (above) — the binding's origin is the open, not the save.
+ * 2. One-way set checks — validation walks BOTH directions, because checking
+ *    only the items present can never notice one was removed.
+ * 3. Trusting a mutable label over the identity it claims — out of scope here
+ *    by construction: nothing in this module dispatches on a label; recheck
+ *    semantics stay with the consumer that owns them.
+ * 4. Vacuous success — an empty queue cannot be bound and never validates,
+ *    because a receipt over nothing certifies nothing.
+ */
+import { canonicalJson } from "./canonical.js";
+import { sha256Hex } from "../sha256.js";
+import { reviewResourceApiVersion } from "../review-resource.js";
+import { buildReviewItemsFromExtractionEnvelopeImport, validateExtractionEnvelopeImport, } from "../extraction-envelope.js";
+export class UnattestedReviewQueueError extends Error {
+    name = "UnattestedReviewQueueError";
+    issues;
+    constructor(issues) {
+        super(`Review queue is not attested by its binding: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+    }
+}
+/**
+ * The digest a binding stores: sha256 over the canonical JSON of the whole
+ * open-time session state. Byte-identical to server-review-session's
+ * `hashReviewSessionSnapshot` (pinned by test), so a consumer already
+ * persisting that digest adopts the binding without invalidating stored state.
+ */
+export function hashReviewQueueSnapshot(snapshot) {
+    return sha256Hex(canonicalJson(snapshot));
+}
+/**
+ * Take the binding for a queue, once, when the round/session opens.
+ *
+ * Call this at queue construction and persist the result beside the queue.
+ * Calling it again later, on bytes that may have changed, produces a binding
+ * that agrees with whatever it was given — which is the self-agreement bypass,
+ * not an attestation.
+ *
+ * Refuses an empty queue: a binding over nothing validates nothing, and every
+ * later check against it would be vacuously green. Refuses duplicate item
+ * names: the binding's set comparison is by name, so an ambiguous name would
+ * let two different items answer for one membership.
+ */
+export function bindReviewQueue(snapshot, options) {
+    if (!options.sessionName) {
+        throw new Error("bindReviewQueue requires a non-empty sessionName.");
+    }
+    if (snapshot.items.length === 0) {
+        throw new Error("bindReviewQueue refuses an empty queue: a binding over nothing attests nothing.");
+    }
+    const names = snapshot.items.map((item) => item.metadata.name);
+    const unique = new Set(names);
+    if (unique.size !== names.length) {
+        const duplicate = names.find((name, index) => names.indexOf(name) !== index);
+        throw new Error(`bindReviewQueue refuses a queue with duplicate ReviewItem name ${duplicate}: set membership by name must be unambiguous.`);
+    }
+    return {
+        apiVersion: reviewResourceApiVersion,
+        kind: "ReviewQueueBinding",
+        spec: {
+            sessionName: options.sessionName,
+            snapshotHash: hashReviewQueueSnapshot(snapshot),
+            itemNames: [...unique].sort(),
+            boundAt: options.boundAt instanceof Date ? options.boundAt.toISOString() : options.boundAt ?? new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Compare a presented queue against its stored binding.
+ *
+ * `binding` must be the record persisted when the round opened — passing one
+ * derived from `snapshot` here checks nothing (see module doc). `snapshot` is
+ * the base queue the binding was taken over, not the state after event replay:
+ * decisions live in the event log precisely so the bound bytes never move.
+ *
+ * A malformed binding fails closed with `binding-malformed` rather than
+ * skipping the checks it cannot perform.
+ */
+export function validateReviewQueueBinding(binding, snapshot, options = {}) {
+    const structural = structuralBindingIssues(binding);
+    if (structural.length > 0) {
+        return structural;
+    }
+    const issues = [];
+    if (options.sessionName !== undefined && binding.spec.sessionName !== options.sessionName) {
+        issues.push({
+            code: "session-name-mismatch",
+            message: `Binding names session ${binding.spec.sessionName}, but this queue belongs to session ${options.sessionName}.`,
+        });
+    }
+    if (snapshot.items.length === 0) {
+        issues.push({
+            code: "empty-queue",
+            message: "The presented queue is empty. The binding covers items this queue no longer carries, and an empty queue attests nothing.",
+        });
+    }
+    const presentNames = snapshot.items.map((item) => item.metadata.name);
+    const present = new Set(presentNames);
+    if (present.size !== presentNames.length) {
+        const duplicate = presentNames.find((name, index) => presentNames.indexOf(name) !== index);
+        issues.push({
+            code: "ambiguous-item-identity",
+            message: `The presented queue carries duplicate ReviewItem name ${duplicate}; set membership by name is ambiguous.`,
+            itemName: duplicate,
+        });
+    }
+    // Set equality in BOTH directions. Walking only the items present can never
+    // notice an item was removed; walking only the bound names can never notice
+    // one was added. Each direction is a different edit.
+    const bound = new Set(binding.spec.itemNames);
+    for (const name of binding.spec.itemNames) {
+        if (!present.has(name)) {
+            issues.push({
+                code: "item-removed",
+                message: `ReviewItem ${name} is covered by the binding but missing from the presented queue.`,
+                itemName: name,
+            });
+        }
+    }
+    for (const name of present) {
+        if (!bound.has(name)) {
+            issues.push({
+                code: "item-added",
+                message: `ReviewItem ${name} is in the presented queue but not covered by the binding.`,
+                itemName: name,
+            });
+        }
+    }
+    const actualHash = hashReviewQueueSnapshot(snapshot);
+    if (binding.spec.snapshotHash !== actualHash) {
+        issues.push({
+            code: "snapshot-hash-mismatch",
+            message: `The presented queue's bytes do not match the binding (expected ${binding.spec.snapshotHash}, got ${actualHash}). The queue changed after the round opened.`,
+        });
+    }
+    return issues;
+}
+export function assertReviewQueueBinding(binding, snapshot, options = {}) {
+    const issues = validateReviewQueueBinding(binding, snapshot, options);
+    if (issues.length > 0) {
+        throw new UnattestedReviewQueueError(issues);
+    }
+}
+export class UnattestedExtractionQueueError extends Error {
+    name = "UnattestedExtractionQueueError";
+    issues;
+    constructor(issues) {
+        super(`Review queue is not attested by its extraction import: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+    }
+}
+/**
+ * Check a stored queue for consistency with the extraction import record it
+ * was derived from.
+ *
+ * The queue binding alone cannot catch a writer who edits the queue and
+ * re-binds: hashing mutated bytes yields a self-consistent pair. This check
+ * closes the QUEUE half of that hole: it revalidates the presented record
+ * through the public import boundary (a forged `grounded` status throws; an
+ * ungrounded import is refused), re-derives the canonical ReviewItems from it,
+ * and requires the stored queue to be the SAME SET, byte-identically per item,
+ * in both directions. A queue edited independently of its record fails.
+ *
+ * What it does NOT attest: the record itself. The envelope carries the
+ * prepared artifact's digest and contentLength, never the prepared bytes, so
+ * a library handed only the record cannot verify a proposal's bytes against
+ * the digested artifact. A writer who edits the record's proposals and
+ * re-derives the queue from the edited record presents a pair this check
+ * blesses, while `result.preparedArtifact.digest` still names the honest
+ * bytes. Record integrity is therefore the caller's storage obligation, and
+ * checking prepared bytes against that digest does not meet it — the digest
+ * covers the artifact, not the proposals, so it stays green through the
+ * rewrite. Meeting it takes one of: a record digest/MAC anchored where the
+ * record's writer cannot reach, immutable or authenticated record storage,
+ * or independently re-deriving the proposals from trusted prepared bytes and
+ * comparing. This limit is pinned by a boundary test and by
+ * scripts/check-guards.mjs.
+ *
+ * This is the whole-extraction rule: it applies to a queue whose items all come
+ * from one import. A consumer whose rounds mix in items the extraction cannot
+ * attest (recheck rounds against a prior observation, for one) owns that
+ * dispatch and those semantics — deciding which attestation applies to which
+ * item from a mutable label is bypass 3, and it stays with the data that can
+ * cross-check the label.
+ */
+export function validateReviewQueueAgainstExtractionImport(items, importResult) {
+    const record = validateExtractionEnvelopeImport(importResult.record);
+    if (record.status.state !== "grounded") {
+        return [{
+                code: "import-not-grounded",
+                message: `Extraction import ${record.metadata.name} is ${record.status.state}, not grounded; it cannot attest a review queue.`,
+            }];
+    }
+    if (items.length === 0) {
+        return [{
+                code: "empty-queue",
+                message: "The stored queue is empty; there is nothing it can certify against this extraction.",
+            }];
+    }
+    // Re-derived through the public import boundary, not read from the caller's
+    // importResult.reviewItems: the record is validated above, and the canonical
+    // items are a pure function of it, so the comparison is against what the
+    // presented record actually says — not against a reviewItems array the
+    // caller could have edited separately from it. The record itself is
+    // caller-supplied and is NOT attested here; see the function doc.
+    const attesting = new Map(buildReviewItemsFromExtractionEnvelopeImport(record).map((item) => [item.metadata.name, item]));
+    const stored = new Map(items.map((item) => [item.metadata.name, item]));
+    const issues = [];
+    for (const [name, item] of attesting) {
+        const found = stored.get(name);
+        if (!found) {
+            issues.push({
+                code: "item-missing-from-queue",
+                message: `ReviewItem ${name} is in the extraction but missing from the stored queue.`,
+                itemName: name,
+            });
+            continue;
+        }
+        if (canonicalJson(found) !== canonicalJson(item)) {
+            issues.push({
+                code: "item-diverges-from-extraction",
+                message: `ReviewItem ${name} does not match the extraction it was imported from.`,
+                itemName: name,
+            });
+        }
+    }
+    for (const name of stored.keys()) {
+        if (!attesting.has(name)) {
+            issues.push({
+                code: "item-not-in-extraction",
+                message: `ReviewItem ${name} is in the stored queue but not in the extraction.`,
+                itemName: name,
+            });
+        }
+    }
+    return issues;
+}
+export function assertReviewQueueAgainstExtractionImport(items, importResult) {
+    const issues = validateReviewQueueAgainstExtractionImport(items, importResult);
+    if (issues.length > 0) {
+        throw new UnattestedExtractionQueueError(issues);
+    }
+}
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+function structuralBindingIssues(binding) {
+    const malformed = (message) => [{
+            code: "binding-malformed",
+            message: `Malformed ReviewQueueBinding: ${message}`,
+        }];
+    if (typeof binding !== "object" || binding === null || Array.isArray(binding)) {
+        return malformed("not an object.");
+    }
+    if (binding.apiVersion !== reviewResourceApiVersion || binding.kind !== "ReviewQueueBinding") {
+        return malformed(`unexpected identity ${String(binding.apiVersion)}/${String(binding.kind)}.`);
+    }
+    const spec = binding.spec;
+    if (typeof spec !== "object" || spec === null) {
+        return malformed("missing spec.");
+    }
+    if (typeof spec.sessionName !== "string" || spec.sessionName.length === 0) {
+        return malformed("sessionName must be a non-empty string.");
+    }
+    if (typeof spec.snapshotHash !== "string" || !SHA256_HEX.test(spec.snapshotHash)) {
+        return malformed("snapshotHash must be a 64-character lowercase hex sha256.");
+    }
+    if (typeof spec.boundAt !== "string" || spec.boundAt.length === 0) {
+        return malformed("boundAt must be a non-empty ISO timestamp string.");
+    }
+    if (!Array.isArray(spec.itemNames) || spec.itemNames.length === 0) {
+        return malformed("itemNames must be a non-empty array: a binding over nothing attests nothing.");
+    }
+    for (const name of spec.itemNames) {
+        if (typeof name !== "string" || name.length === 0) {
+            return malformed("itemNames must contain only non-empty strings.");
+        }
+    }
+    const sorted = [...spec.itemNames].sort();
+    if (new Set(spec.itemNames).size !== spec.itemNames.length
+        || spec.itemNames.some((name, index) => name !== sorted[index])) {
+        return malformed("itemNames must be unique and sorted.");
+    }
+    return [];
+}

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

@@ -1,3 +1,4 @@
+import { findSoleCandidateById } from "../review-resource.js";
 import { formatValue } from "./review-surface-preview.js";
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
@@ -34,7 +35,7 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
     const targetLabel = item && itemContext
         ? adapter.labelForTarget?.(target, itemContext) ?? humanizeIdentifier(target)
         : humanizeIdentifier(target);
-    const selectedCandidate = item?.spec.candidates.find((candidate) => candidate.role === result.selectedCandidateRole || candidate.id === result.selectedCandidateId);
+    const selectedCandidate = item ? selectedCandidateForResult(item, result) : undefined;
     return {
         result,
         item,
@@ -53,6 +54,32 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
             : [{ label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" }],
     };
 }
+/**
+ * The candidate a result selected, resolved by its complete identity.
+ *
+ * `find(role === … || id === …)` returned whichever candidate matched EITHER
+ * half, so on an item carrying a repeated candidate id it could return a
+ * different candidate than the result names — presenting one candidate's value
+ * against another's decision, which is exactly what it did.
+ *
+ * The id is the identity; {@link findSoleCandidateById} makes it fail closed
+ * rather than pick a winner when it is ambiguous, and the declared role has to
+ * agree when the result states one. Falling back to the role alone is kept for
+ * results that carry no id, and requires the role to be unambiguous too.
+ */
+function selectedCandidateForResult(item, result) {
+    if (result.selectedCandidateId) {
+        const candidate = findSoleCandidateById(item, result.selectedCandidateId);
+        if (candidate && (result.selectedCandidateRole === undefined || candidate.role === result.selectedCandidateRole)) {
+            return candidate;
+        }
+    }
+    if (result.selectedCandidateRole === undefined) {
+        return undefined;
+    }
+    const byRole = item.spec.candidates.filter((candidate) => candidate.role === result.selectedCandidateRole);
+    return byRole.length === 1 ? byRole[0] : undefined;
+}
 export function humanizeIdentifier(value) {
     return value
         .replace(/[_-]+/g, " ")

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

@@ -91,6 +91,17 @@ export declare function reviewSessionSummary(session: ReviewQueueSessionState):
  * would invent a prior value, with provenance, that the source never had.
  */
 export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boolean): ReviewWorkbenchDecision | undefined;
+/**
+ * The candidate a workbench decision applies to.
+ *
+ * Selection is by role, but the id this returns is what every caller makes
+ * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
+ * replay expectation. So the id has to name exactly one candidate before it
+ * leaves here. Guarding the render path alone let the workbench emit an
+ * undecidable decision through the export path and then present a different
+ * candidate's value against it; this is the shared selector all of those go
+ * through, which is why the check belongs here rather than at each of them.
+ */
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline

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

@@ -1,6 +1,6 @@
 import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
-import { reviewResourceApiVersion, } from "../../src/review-resource.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";
 export const workbenchDecisionDefinitions = {
@@ -148,12 +148,24 @@ export function keepActionDecision(item, flaggedWrong) {
     }
     return "keep-current";
 }
+/**
+ * The candidate a workbench decision applies to.
+ *
+ * Selection is by role, but the id this returns is what every caller makes
+ * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
+ * replay expectation. So the id has to name exactly one candidate before it
+ * leaves here. Guarding the render path alone let the workbench emit an
+ * undecidable decision through the export path and then present a different
+ * candidate's value against it; this is the shared selector all of those go
+ * through, which is why the check belongs here rather than at each of them.
+ */
 export function candidateForDecision(item, decision) {
     const definition = workbenchDecisionDefinitions[decision];
     const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no ${definition.candidateRole} candidate.`);
     }
+    assertSoleCandidateId(item, candidate.id);
     return candidate;
 }
 /**

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

@@ -1,3 +1,4 @@
+import { findSoleCandidateById } from "../review-resource.js";
 export function buildSurfaceProjectionPreview(item, decision, presentationAdapter = {}) {
     const selectedCandidate = selectedPreviewCandidate(item, decision);
     if (!selectedCandidate || !decision) {
@@ -38,7 +39,7 @@ function selectedPreviewCandidate(item, decision) {
     if (!decision?.spec.candidateId) {
         return undefined;
     }
-    const candidate = item.spec.candidates.find((entry) => entry.id === decision.spec.candidateId);
+    const candidate = findSoleCandidateById(item, decision.spec.candidateId);
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no candidate ${decision.spec.candidateId}.`);
     }

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

@@ -202,11 +202,37 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .inspector-pager button:disabled, .survey-workbench-embed .queue-pager button:disabled{ opacity: .45; }
 .survey-workbench-embed .inspector-candidates{ margin: 0; padding-left: 1.5rem; }
 .survey-workbench-embed .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); }
-.survey-workbench-embed .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; }
+.survey-workbench-embed .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; }
 .survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
 .survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
-.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
-.survey-workbench-embed .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. */
+.survey-workbench-embed .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. */
+.survey-workbench-embed .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;
+}
+
+.survey-workbench-embed .source-highlight:focus-visible{
+  outline: 3px solid var(--k-active);
+  outline-offset: 1px;
+}
 .survey-workbench-embed .source-unavailable{ color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
@@ -639,6 +665,22 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   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). */
+.survey-workbench-embed .derr{
+  display: block;
+  margin-top: 6px;
+  text-align: right;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .derr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{
@@ -1080,14 +1122,6 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   text-transform: uppercase;
 }
 
-.survey-workbench-embed .preview-section.is-neutral{
-  background: var(--k-raised);
-}
-
-.survey-workbench-embed .preview-section.is-neutral h3{
-  color: var(--k-faint);
-}
-
 .survey-workbench-embed .reference-details{
   margin-top: 8px;
 }

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

@@ -298,7 +298,30 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
             if (this.#session.activeItemName !== item.metadata.name)
                 this.#session = { ...this.#session, activeItemName: item.metadata.name };
             this.#remount();
-            queueMicrotask(() => this.#root.querySelector(`#highlight-${CSS.escape(detail.candidateId.replace(/[^a-zA-Z0-9_-]/g, "-"))}`)?.focus());
+            // Both lookups below are published contracts, used as published.
+            // Reconstructing the element id from candidateId — which this did — meant
+            // carrying a copy of Survey's private id sanitizer and ignoring the
+            // collision suffix that makes the id unique, which is exactly what the
+            // consumer guide tells embedders not to do.
+            const { highlightElementId } = detail;
+            if (!highlightElementId)
+                return;
+            queueMicrotask(() => {
+                // Routed on the highlight element id, which is unique by construction.
+                // candidateId is the candidate's own identity and a caller-authored
+                // model may repeat it, so a `[data-…="<candidateId>"]` lookup can select
+                // a different candidate's highlight — confidently wrong, on the surface
+                // whose job is showing which span a value came from. `~=` matches one
+                // whitespace-separated token, so a mark over a shared span is found too.
+                const highlight = this.#root.querySelector(`[data-highlight-return-to~="${CSS.escape(highlightElementId)}"]`);
+                if (highlight) {
+                    highlight.focus();
+                    return;
+                }
+                // Off the current page there is nothing painted; bring the link target
+                // into view instead of leaving the reader where they were.
+                this.#root.querySelector(`#${CSS.escape(highlightElementId)}`)?.scrollIntoView({ block: "center" });
+            });
         });
     }
     /** The review queue session to display. Setting this property re-mounts the workbench. */

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

@@ -199,11 +199,37 @@
 .survey-workbench-embed .inspector-pager button:disabled, .survey-workbench-embed .queue-pager button:disabled{ opacity: .45; }
 .survey-workbench-embed .inspector-candidates{ margin: 0; padding-left: 1.5rem; }
 .survey-workbench-embed .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); }
-.survey-workbench-embed .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; }
+.survey-workbench-embed .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; }
 .survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
 .survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
-.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
-.survey-workbench-embed .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. */
+.survey-workbench-embed .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. */
+.survey-workbench-embed .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;
+}
+
+.survey-workbench-embed .source-highlight:focus-visible{
+  outline: 3px solid var(--k-active);
+  outline-offset: 1px;
+}
 .survey-workbench-embed .source-unavailable{ color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
@@ -636,6 +662,22 @@
   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). */
+.survey-workbench-embed .derr{
+  display: block;
+  margin-top: 6px;
+  text-align: right;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .derr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{
@@ -1077,14 +1119,6 @@
   text-transform: uppercase;
 }
 
-.survey-workbench-embed .preview-section.is-neutral{
-  background: var(--k-raised);
-}
-
-.survey-workbench-embed .preview-section.is-neutral h3{
-  color: var(--k-faint);
-}
-
 .survey-workbench-embed .reference-details{
   margin-top: 8px;
 }

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

@@ -2,7 +2,9 @@ import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type Review
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewValueDescriptor } from "../review-resource.js";
-export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, type ExtractionAlignmentState, type ArtifactUnavailableCode, type ExtractionInspectorCandidate, type ExtractionInspectorEntry, type ExtractionInspectorExportOptions, type ExtractionInspectorFilters, type ExtractionInspectorInput, type ExtractionInspectorMountOptions, type ExtractionInspectorModel, type ExtractionInspectorSource, type ResolvedExtractionArtifact, } from "./extraction-inspector.js";
+export { reviewAuditRowKeys, type ReviewAuditRowKey } from "./audit-rows.js";
+export { assertReviewQueueAgainstExtractionImport, assertReviewQueueBinding, bindReviewQueue, hashReviewQueueSnapshot, UnattestedExtractionQueueError, UnattestedReviewQueueError, validateReviewQueueAgainstExtractionImport, validateReviewQueueBinding, type BindReviewQueueOptions, type ReviewQueueBinding, type ReviewQueueBindingIssue, type ReviewQueueBindingIssueCode, 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, 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 { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, 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";