@kontourai/survey 2.2.4 → 2.4.0

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

@@ -41,7 +41,77 @@ export function buildExtractionInspectorModel(input) {
                 candidates[index].alignment = "excerpt-mismatch";
         }
     }
-    return { sources, candidates };
+    return { sources, candidates: bindHighlightElementIds(candidates) };
+}
+const HIGHLIGHT_ID_PREFIX = "highlight-";
+/**
+ * Assigns every candidate the element id its source highlight will carry.
+ *
+ * Done here, over the whole model, rather than by a pure per-id derivation:
+ * sanitizing a candidate id to an HTML identifier is lossy (`a:b.c` and `a:b-c`
+ * both reduce to `a-b-c`), and two anchors sharing an id silently resolve a
+ * host's link to the wrong sentence. Today's candidate-id scheme happens not to
+ * produce that collision — the entry index always separates two sources — so
+ * the disambiguating suffix is defensive rather than a fix for a reachable bug.
+ * It is here because uniqueness is now a published promise
+ * ({@link ExtractionInspectorCandidate.highlightElementId}) that must survive a
+ * later change to the key scheme rather than depend on one.
+ */
+function bindHighlightElementIds(candidates) {
+    const used = new Set();
+    return candidates.map((candidate) => ({
+        ...candidate,
+        highlightElementId: uniqueHighlightElementId(candidate.id, used),
+    }));
+}
+/**
+ * Derives an element id not already taken.
+ *
+ * `used` holds finished element ids — prefix included — and so does the value
+ * returned, because the two have to be the same form to be comparable. They were
+ * not: uniqueness was checked on the bare token while the set held prefixed ids,
+ * so a published `highlight-alpha` did not stop a candidate with id `alpha` from
+ * deriving `highlight-alpha` and mounting a second element under it. A host's
+ * `href` then resolved to whichever came first.
+ */
+function uniqueHighlightElementId(candidateId, used) {
+    const base = `${HIGHLIGHT_ID_PREFIX}${safeId(candidateId)}`;
+    let elementId = base;
+    for (let suffix = 2; used.has(elementId); suffix += 1)
+        elementId = `${base}-${suffix}`;
+    used.add(elementId);
+    return elementId;
+}
+/** The inspector's own candidate-list id, paired 1:1 with a highlight anchor. Not public. */
+function candidateElementId(highlightElementId) {
+    return `candidate-${highlightElementId.slice(HIGHLIGHT_ID_PREFIX.length)}`;
+}
+/**
+ * The element id each candidate's anchor will carry, for one mount.
+ *
+ * A model from {@link buildExtractionInspectorModel} already carries one per
+ * candidate and it is used verbatim — rewriting a published id is precisely the
+ * drift this contract exists to prevent. A hand-authored model may omit some or
+ * all of them; those get an id derived here, seeded with the published ones so a
+ * derived id can never collide with one a host is already linking to.
+ *
+ * Keyed on the candidate OBJECT, not on `candidate.id`. The builder's ids are
+ * structurally unique, but this function exists for models a caller assembled,
+ * where nothing enforces that — and an id-keyed map silently collapsed two such
+ * candidates into one entry, handing the second's derived id to the first and
+ * discarding the very `highlightElementId` a host was already linking to. Object
+ * identity cannot collide, whatever the data says.
+ */
+function resolveHighlightElementIds(model) {
+    const used = new Set();
+    for (const candidate of model.candidates)
+        if (candidate.highlightElementId)
+            used.add(candidate.highlightElementId);
+    const resolved = new Map();
+    for (const candidate of model.candidates) {
+        resolved.set(candidate, candidate.highlightElementId ?? uniqueHighlightElementId(candidate.id, used));
+    }
+    return resolved;
 }
 function assertResolvedArtifact(artifact) {
     if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
@@ -164,7 +234,9 @@ export function exportExtractionInspector(model, options = {}) {
     return canonicalJson({ apiVersion: "survey.kontourai.io/v1alpha1", kind: "ExtractionInspectorExport", spec: {
             redaction: { preparedTextIncluded: options.includePreparedText === true, excerptsIncluded: options.includeExcerpts === true },
             sources: model.sources.map(({ artifactText, message: _message, ...source }) => ({ ...source, preparedText: options.includePreparedText ? artifactText ?? null : "[redacted]" })),
-            candidates: model.candidates.map((candidate) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
+            // highlightElementId is a DOM binding for a live inspector, not extraction
+            // evidence — it stays out of the canonical export (and out of its digest).
+            candidates: model.candidates.map(({ highlightElementId: _highlightElementId, ...candidate }) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
         } });
 }
 export function mountExtractionInspector(container, model, options = {}) {
@@ -172,6 +244,8 @@ export function mountExtractionInspector(container, model, options = {}) {
         ? Math.min(Number(options.pageSize), 500)
         : 100;
     let page = 0;
+    const highlightIds = resolveHighlightElementIds(model);
+    const highlightIdFor = (candidate) => highlightIds.get(candidate);
     const root = document.createElement("section");
     root.className = "extraction-inspector";
     root.setAttribute("aria-label", "Source-linked extraction inspector");
@@ -188,7 +262,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         page = Math.min(page, pageCount - 1);
         const start = page * pageSize;
         const visible = matching.slice(start, start + pageSize);
-        list.innerHTML = visible.map(c => `<li><button type="button" class="inspector-candidate" id="candidate-${safeId(c.id)}" data-candidate-id="${escapeHtml(c.id)}" aria-controls="highlight-${safeId(c.id)}"><strong>${escapeHtml(c.field)}</strong><span>${escapeHtml(c.provider)}${c.model ? ` / ${escapeHtml(c.model)}` : ""}</span><span>${escapeHtml(c.inferenceType)} ${escapeHtml(c.valueType)} · ${escapeHtml(c.alignment)}</span>${formatContext(c)}</button></li>`).join("") || "<li>No candidates match these filters.</li>";
+        list.innerHTML = visible.map(c => `<li><button type="button" class="inspector-candidate" id="${escapeHtml(candidateElementId(highlightIdFor(c)))}" data-candidate-id="${escapeHtml(c.id)}" data-highlight-element-id="${escapeHtml(highlightIdFor(c))}" aria-controls="${escapeHtml(highlightIdFor(c))}"><strong>${escapeHtml(c.field)}</strong><span>${escapeHtml(c.provider)}${c.model ? ` / ${escapeHtml(c.model)}` : ""}</span><span>${escapeHtml(c.inferenceType)} ${escapeHtml(c.valueType)} · ${escapeHtml(c.alignment)}</span>${formatContext(c)}</button></li>`).join("") || "<li>No candidates match these filters.</li>";
         resultCount.textContent = matching.length === 0 ? "No matching candidates" : `${start + 1}–${Math.min(start + pageSize, matching.length)} of ${matching.length}`;
         pageLabel.textContent = `Page ${page + 1} of ${pageCount}`;
         pageLabel.hidden = pageCount === 1;
@@ -197,7 +271,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         previous.disabled = page === 0;
         next.disabled = page >= pageCount - 1;
         postures.innerHTML = model.sources.map(s => `<div class="inspector-posture ${s.alignment}" role="status"><strong>${escapeHtml(s.importName)}: ${escapeHtml(s.alignment)}</strong><span>${escapeHtml(s.message)}</span></div>`).join("");
-        sourcesRoot.innerHTML = model.sources.map(s => { const candidates = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, candidates)}</pre></div>`; }).join("");
+        sourcesRoot.innerHTML = model.sources.map(s => { const anchored = model.candidates.filter(c => c.sourceKey === s.key); const marked = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `${anchored.map(c => anchorHtml(c, highlightIdFor(c))).join("")}<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, anchored, marked, highlightIdFor)}</pre></div>`; }).join("");
     };
     root.querySelectorAll("select").forEach(select => select.addEventListener("change", event => { event.stopPropagation(); const key = select.dataset.filter; if (select.value)
         filters[key] = select.value;
@@ -209,50 +283,187 @@ export function mountExtractionInspector(container, model, options = {}) {
         delete filters.query; page = 0; render(); });
     previous.addEventListener("click", () => { page = Math.max(0, page - 1); render(); list.querySelector("button")?.focus(); });
     next.addEventListener("click", () => { page += 1; render(); list.querySelector("button")?.focus(); });
-    const activateCandidate = (id) => { const candidate = model.candidates.find(c => c.id === id); if (!candidate)
-        return; root.dispatchEvent(new CustomEvent("survey-extraction-candidate-activate", { bubbles: true, composed: true, detail: { candidateId: id, reviewItemName: candidate.reviewItemName } })); };
-    root.addEventListener("click", event => { const candidate = event.target.closest("button[data-candidate-id]"); if (candidate) {
+    // The event carries the resolved binding as well as the identity: a listener
+    // that wants to focus the highlight must never reconstruct the id, and the
+    // first-party custom element is the reference implementation of that rule.
+    const candidateFor = (highlightElementId) => model.candidates.find(c => highlightIdFor(c) === highlightElementId);
+    const activateCandidate = (highlightElementId) => { const candidate = candidateFor(highlightElementId); if (!candidate)
+        return; root.dispatchEvent(new CustomEvent("survey-extraction-candidate-activate", { bubbles: true, composed: true, detail: { candidateId: candidate.id, reviewItemName: candidate.reviewItemName, highlightElementId } })); };
+    const clearFilters = () => {
+        for (const key of Object.keys(filters))
+            delete filters[key];
+        root.querySelectorAll("select[data-filter]").forEach(select => { select.value = ""; });
+        const search = root.querySelector('input[data-filter="query"]');
+        if (search)
+            search.value = "";
+    };
+    /**
+     * Brings a candidate's row onto the mounted page so it can be focused.
+     *
+     * Anchors exist for every candidate, so a highlight can be activated while its
+     * candidate row is on another page or filtered out entirely. Returning focus
+     * to a row that is not mounted would silently do nothing, so page to it —
+     * clearing the filters first if they are what is hiding it.
+     */
+    const revealCandidateRow = (highlightElementId) => {
+        const candidate = candidateFor(highlightElementId);
+        if (!candidate)
+            return undefined;
+        let index = filterExtractionInspectorCandidates(model, filters).indexOf(candidate);
+        if (index < 0) {
+            clearFilters();
+            index = model.candidates.indexOf(candidate);
+        }
+        if (index < 0)
+            return undefined;
+        page = Math.floor(index / pageSize);
+        render();
+        return candidate;
+    };
+    const returnToCandidate = (highlightElementId) => {
+        if (revealCandidateRow(highlightElementId))
+            root.querySelector(`#${CSS.escape(candidateElementId(highlightElementId))}`)?.focus();
+    };
+    /**
+     * Follows a host's `href="#<highlightElementId>"`.
+     *
+     * The anchor that id names always exists, but a candidate off the current page
+     * or excluded by a filter has no painted highlight, so the link would land the
+     * reader on an invisible marker in the middle of the source text. Page to the
+     * candidate instead, so the highlight it points at is actually painted, and put
+     * focus on it.
+     */
+    const followHighlightFragment = () => {
+        const fragment = typeof location === "undefined" ? "" : location.hash.slice(1);
+        if (!fragment)
+            return;
+        if (!candidateFor(fragment))
+            return;
+        revealCandidateRow(fragment);
+        // `~=` matches one whitespace-separated token: a mark painted over a span
+        // shared by several candidates lists all of them, and this is the one the
+        // reader asked for. Record it, so activating that mark returns to the
+        // candidate they arrived by rather than to whichever is listed first.
+        const mark = root.querySelector(`[data-highlight-return-to~="${CSS.escape(fragment)}"]`);
+        if (!mark)
+            return;
+        mark.dataset.highlightArrivedBy = fragment;
+        mark.focus();
+        mark.scrollIntoView({ block: "center" });
+    };
+    const onHashChange = () => followHighlightFragment();
+    if (typeof window !== "undefined")
+        window.addEventListener("hashchange", onHashChange);
+    /** The candidate a shared mark returns to: the one the reader arrived by, else the first it covers. */
+    const returnTargetOf = (mark) => mark.dataset.highlightArrivedBy ?? mark.dataset.highlightReturnTo.split(" ")[0];
+    root.addEventListener("click", event => { const candidate = event.target.closest("button[data-highlight-element-id]"); if (candidate) {
         event.preventDefault();
         event.stopPropagation();
-        activateCandidate(candidate.dataset.candidateId);
+        activateCandidate(candidate.dataset.highlightElementId);
         return;
-    } const highlight = event.target.closest("button[data-highlight-candidate-id]"); if (highlight) {
+    } const highlight = event.target.closest("[data-highlight-return-to]"); if (highlight) {
         event.preventDefault();
         event.stopPropagation();
-        root.querySelector(`#candidate-${CSS.escape(safeId(highlight.dataset.highlightCandidateId))}`)?.focus();
+        returnToCandidate(returnTargetOf(highlight));
     } });
-    root.addEventListener("keydown", event => { const button = event.target.closest("button[data-candidate-id]"); if (!button)
+    root.addEventListener("keydown", event => { const highlight = event.target.closest("[data-highlight-return-to]"); if (highlight) {
+        if (event.key !== "Enter" && event.key !== " ")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        returnToCandidate(returnTargetOf(highlight));
+        return;
+    } const button = event.target.closest("button[data-highlight-element-id]"); if (!button)
         return; if (event.key === "Enter" || event.key === " ") {
         event.preventDefault();
         event.stopPropagation();
-        activateCandidate(button.dataset.candidateId);
+        activateCandidate(button.dataset.highlightElementId);
         return;
     } if (event.key === "ArrowDown" || event.key === "ArrowUp") {
         event.preventDefault();
-        const buttons = [...list.querySelectorAll("button[data-candidate-id]")];
+        const buttons = [...list.querySelectorAll("button[data-highlight-element-id]")];
         const index = buttons.indexOf(button);
         buttons[event.key === "ArrowDown" ? Math.min(index + 1, buttons.length - 1) : Math.max(index - 1, 0)]?.focus();
     } });
     render();
-    return () => root.remove();
+    followHighlightFragment();
+    return () => { if (typeof window !== "undefined")
+        window.removeEventListener("hashchange", onHashChange); root.remove(); };
 }
-function renderSource(text, candidates) {
+/**
+ * Renders the prepared text with a return anchor for every candidate and a
+ * `<mark>` for the ones on the current page.
+ *
+ * The two sets are deliberately different. `marked` follows the candidate
+ * list's paging and filtering, so the painting tracks what the reviewer is
+ * looking at. `anchored` is every candidate the source has, so that the element
+ * id published on the model resolves whatever page the reviewer is on and
+ * whatever they have typed into the filter box — the anchors carry the contract,
+ * the marks carry the view.
+ */
+function renderSource(text, anchored, marked, highlightIdFor) {
     const boundaries = new Set([0, text.length]);
-    candidates.forEach(c => { boundaries.add(c.start); boundaries.add(c.end); });
-    const points = [...boundaries].sort((a, b) => a - b);
+    anchored.forEach(c => boundaries.add(c.start));
+    marked.forEach(c => { boundaries.add(c.start); boundaries.add(c.end); });
+    const points = [...boundaries].filter(point => point >= 0 && point <= text.length).sort((a, b) => a - b);
     let html = "";
     const starts = new Map();
-    candidates.forEach(c => starts.set(c.start, [...(starts.get(c.start) ?? []), c]));
+    anchored.forEach(c => starts.set(c.start, [...(starts.get(c.start) ?? []), c]));
+    const emitted = new Set();
     for (let i = 0; i < points.length - 1; i++) {
         const start = points[i], end = points[i + 1];
-        for (const c of starts.get(start) ?? [])
-            html += `<button type="button" class="highlight-anchor" id="highlight-${safeId(c.id)}" data-highlight-candidate-id="${escapeHtml(c.id)}" aria-label="Source highlight for ${escapeHtml(c.field)}; activate to return to candidate"></button>`;
+        for (const c of starts.get(start) ?? []) {
+            emitted.add(c);
+            html += anchorHtml(c, highlightIdFor(c));
+        }
         const segment = escapeHtml(text.slice(start, end));
-        const active = candidates.filter(c => c.start < end && c.end > start);
-        html += active.length ? `<mark aria-label="Highlighted for ${active.map(c => escapeHtml(c.field)).join(", ")}">${segment}</mark>` : segment;
+        const active = marked.filter(c => c.start < end && c.end > start);
+        html += active.length ? markHtml(segment, active, highlightIdFor) : segment;
     }
+    // A span starting at or past the end of the prepared text has no segment to
+    // lead; its anchor still has to exist, or its published id resolves nowhere.
+    for (const c of anchored)
+        if (!emitted.has(c))
+            html += anchorHtml(c, highlightIdFor(c));
     return html;
 }
+/**
+ * The link target a host's `href` resolves to: an empty, inert span at the start
+ * of the candidate's span.
+ *
+ * Deliberately NOT a control. It exists for every candidate in the model, which
+ * is what makes the published id resolve unconditionally — but a thing that
+ * exists per candidate must cost nothing to a keyboard or screen-reader user, and
+ * as a `<button>` it did: 600 candidates put 600 invisible tab stops in sequence,
+ * several of them stacked together in the non-grounded postures. It was also a
+ * one-pixel pointer target once its accidental user-agent chrome was removed —
+ * an affordance in name only, at any size, because nothing about it was visible.
+ *
+ * Returning to the candidate is now the job of the thing a reader can actually
+ * see and aim at: the highlight itself. See {@link markHtml}.
+ */
+function anchorHtml(candidate, highlightElementId) {
+    return `<span class="highlight-anchor" id="${escapeHtml(highlightElementId)}" data-highlight-candidate-id="${escapeHtml(candidate.id)}"></span>`;
+}
+/**
+ * The painted highlight, and the control that returns to its candidate.
+ *
+ * The highlight is the only part of this surface a reader can see, so it is the
+ * target: full phrase width rather than a sliver, discoverable because it is
+ * already visibly marked, and one tab stop per painted highlight rather than one
+ * per candidate in the model. `data-highlight-return-to` is separate from the
+ * anchor's `data-highlight-candidate-id` so the documented reverse lookup keeps
+ * resolving to exactly one element.
+ */
+function markHtml(segment, active, highlightIdFor) {
+    const fields = active.map(c => escapeHtml(c.field)).join(", ");
+    // Every candidate the mark covers, not just the first. Two claims over one
+    // span is ordinary in extraction, and naming both in the label while binding
+    // only one left the others with a highlight that could not be navigated to or
+    // returned from — the label said two, the binding said one.
+    const bindings = active.map(c => escapeHtml(highlightIdFor(c))).join(" ");
+    return `<mark class="source-highlight" role="button" tabindex="0" data-highlight-return-to="${bindings}" aria-label="Highlighted for ${fields}; activate to return to candidate">${segment}</mark>`;
+}
 function formatContext(candidate) {
     const context = [];
     if (candidate.pdfRegion) {

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

@@ -0,0 +1,127 @@
+import type { ReviewQueueSessionState } from "./review-queue-session.js";
+import { reviewResourceApiVersion, type ReviewItem } from "../review-resource.js";
+import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+/**
+ * The durable attestation record. Serializable; a consumer stores it beside the
+ * queue when the round opens and presents it, unchanged, at every later
+ * validation.
+ *
+ * `itemNames` is deliberately redundant with the hash: it is what makes a
+ * refusal diagnosable (which item was removed or added, by name) and it keeps
+ * the set comparison independent of the hash derivation.
+ */
+export interface ReviewQueueBinding {
+    readonly apiVersion: typeof reviewResourceApiVersion;
+    readonly kind: "ReviewQueueBinding";
+    readonly spec: {
+        readonly sessionName: string;
+        /** sha256 of the canonical open-time snapshot; see {@link hashReviewQueueSnapshot}. */
+        readonly snapshotHash: string;
+        /** Sorted, unique names of every ReviewItem the binding covers. Never empty. */
+        readonly itemNames: readonly string[];
+        /** ISO timestamp of when the binding was taken. Informational, not trusted. */
+        readonly boundAt: string;
+    };
+}
+export type ReviewQueueBindingIssueCode = "binding-malformed" | "session-name-mismatch" | "empty-queue" | "ambiguous-item-identity" | "snapshot-hash-mismatch" | "item-removed" | "item-added";
+export interface ReviewQueueBindingIssue {
+    readonly code: ReviewQueueBindingIssueCode;
+    readonly message: string;
+    /** The ReviewItem name a set-membership issue is about, when there is one. */
+    readonly itemName?: string;
+}
+export declare class UnattestedReviewQueueError extends Error {
+    readonly name = "UnattestedReviewQueueError";
+    readonly issues: readonly ReviewQueueBindingIssue[];
+    constructor(issues: readonly ReviewQueueBindingIssue[]);
+}
+export interface BindReviewQueueOptions {
+    readonly sessionName: string;
+    /** Defaults to now. Informational only; nothing validates against it. */
+    readonly boundAt?: Date | string;
+}
+export interface ValidateReviewQueueBindingOptions {
+    /** When set, the binding must name this session. */
+    readonly sessionName?: string;
+}
+/**
+ * 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 declare function hashReviewQueueSnapshot(snapshot: ReviewQueueSessionState): string;
+/**
+ * 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 declare function bindReviewQueue(snapshot: ReviewQueueSessionState, options: BindReviewQueueOptions): ReviewQueueBinding;
+/**
+ * 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 declare function validateReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): ReviewQueueBindingIssue[];
+export declare function assertReviewQueueBinding(binding: ReviewQueueBinding, snapshot: ReviewQueueSessionState, options?: ValidateReviewQueueBindingOptions): void;
+export type ReviewQueueExtractionIssueCode = "import-not-grounded" | "empty-queue" | "item-missing-from-queue" | "item-not-in-extraction" | "item-diverges-from-extraction";
+export interface ReviewQueueExtractionIssue {
+    readonly code: ReviewQueueExtractionIssueCode;
+    readonly message: string;
+    readonly itemName?: string;
+}
+export declare class UnattestedExtractionQueueError extends Error {
+    readonly name = "UnattestedExtractionQueueError";
+    readonly issues: readonly ReviewQueueExtractionIssue[];
+    constructor(issues: readonly ReviewQueueExtractionIssue[]);
+}
+/**
+ * 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 declare function validateReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): ReviewQueueExtractionIssue[];
+export declare function assertReviewQueueAgainstExtractionImport(items: readonly ReviewItem[], importResult: ExtractionEnvelopeImportResult): void;