@kontourai/survey 2.0.0 → 2.2.0

package/README.md

@@ -212,7 +212,9 @@ The [Consumer Integration Guide](docs/consumer-integration-guide.md) covers the
 Portable extraction imports can also attach a source-linked, read-only inspector
 to the same workbench. It verifies resolved artifact identity before showing
 exact highlights, keeps unresolved material visibly non-grounded, and exports
-with source text and excerpts redacted by default. See
+with source text and excerpts redacted by default. Review queues and inspector
+candidates use bounded, searchable paging so large validated result sets remain
+navigable without changing canonical review events or exports. See
 [Extraction Envelope Import](docs/extraction-envelope-import.md#source-linked-inspection).
 
 

package/dist/src/extraction-envelope.d.ts

@@ -1,5 +1,6 @@
 import type { RawSource } from "./types.js";
 import type { ClaimTargetHint, ReviewItem, ReviewValueType } from "./review-resource.js";
+import { type PortablePdfLayout } from "./pdf-layout.js";
 /** The upstream-owned portable extraction-result wire identifiers accepted by this adapter. */
 export declare const portableExtractionResultFormat = "traverse-extraction-result";
 export declare const portableExtractionResultVersion = 1;
@@ -96,6 +97,7 @@ export interface PortableExtractionResultEnvelope {
         taskDigest?: string;
         exampleDigests?: string[];
         pdfPageOffsets?: number[];
+        pdfLayout?: PortablePdfLayout;
         ocrDerived?: true;
         preparedArtifact?: {
             format: "traverse-prepared-artifact";

package/dist/src/extraction-envelope.js

@@ -1,6 +1,7 @@
 import { sha256Hex } from "./sha256.js";
 import { reviewResourceApiVersion } from "./review-resource.js";
 import { canonicalJson } from "./review-workbench/canonical.js";
+import { validatePortablePdfLayout } from "./pdf-layout.js";
 /** The upstream-owned portable extraction-result wire identifiers accepted by this adapter. */
 export const portableExtractionResultFormat = "traverse-extraction-result";
 export const portableExtractionResultVersion = 1;
@@ -119,12 +120,14 @@ function buildReviewItem(record, proposal, index) {
 }
 function identityInputs(record, proposal, index) {
     return { producerNamespace: record.metadata.producerNamespace, importName: record.metadata.name, source: record.spec.envelope.source,
-        preparedArtifact: record.spec.envelope.result.preparedArtifact, runId: record.spec.envelope.result.runId,
+        preparedArtifact: record.spec.envelope.result.preparedArtifact, pdfLayout: record.spec.envelope.result.pdfLayout,
+        runId: record.spec.envelope.result.runId,
         proposalIndex: index, proposal, claimTarget: record.spec.claimTargets[index] };
 }
 function evidenceInputs(record, proposal) {
     return { producerNamespace: record.metadata.producerNamespace, importName: record.metadata.name, source: record.spec.envelope.source,
         sourceKind: record.spec.sourceKind, preparedArtifact: record.spec.envelope.result.preparedArtifact,
+        pdfLayout: record.spec.envelope.result.pdfLayout,
         extractedAt: record.spec.envelope.result.extractedAt,
         provenance: proposal.provenance };
 }
@@ -182,7 +185,7 @@ function validateEnvelope(input) {
     if (source.snapshotRef !== undefined)
         safeReference(source.snapshotRef, "source.snapshotRef");
     const r = obj(e.result, "result");
-    exact(r, ["proposals", "provider", "runId", "raw", "outcome", "extractedAt", "providerCalls", "totalTokensUsed"], "result", ["model", "warningClassifications", "partial", "providerFailures", "taskDigest", "exampleDigests", "pdfPageOffsets", "ocrDerived", "preparedArtifact", "preparedArtifactState"]);
+    exact(r, ["proposals", "provider", "runId", "raw", "outcome", "extractedAt", "providerCalls", "totalTokensUsed"], "result", ["model", "warningClassifications", "partial", "providerFailures", "taskDigest", "exampleDigests", "pdfPageOffsets", "pdfLayout", "ocrDerived", "preparedArtifact", "preparedArtifactState"]);
     stableIdentity(r.provider, "result.provider");
     if (r.model !== undefined)
         stableIdentity(r.model, "result.model");
@@ -212,11 +215,16 @@ function validateEnvelope(input) {
     if (r.ocrDerived !== undefined && r.ocrDerived !== true)
         throw new Error("result.ocrDerived must be true.");
     const artifact = r.preparedArtifact === undefined ? undefined : validateArtifact(r.preparedArtifact);
+    const pdfLayout = r.pdfLayout === undefined
+        ? undefined
+        : artifact === undefined
+            ? (() => { throw new Error("result.pdfLayout requires result.preparedArtifact."); })()
+            : validatePortablePdfLayout(r.pdfLayout, artifact.contentLength);
     const state = r.preparedArtifactState === undefined ? undefined : validateArtifactState(r.preparedArtifactState, artifact);
     if (source.snapshotRef !== undefined && artifact?.sourceSnapshotRef !== undefined && source.snapshotRef !== artifact.sourceSnapshotRef)
         throw new Error("Source snapshot identity mismatch.");
     const proposals = array(r.proposals, "result.proposals").map((p, i) => validateProposal(p, i, artifact?.contentLength));
-    return cloneJson({ ...e, source, result: { ...r, proposals, ...(artifact ? { preparedArtifact: artifact } : {}), ...(state ? { preparedArtifactState: state } : {}) } });
+    return cloneJson({ ...e, source, result: { ...r, proposals, ...(pdfLayout ? { pdfLayout } : {}), ...(artifact ? { preparedArtifact: artifact } : {}), ...(state ? { preparedArtifactState: state } : {}) } });
 }
 function validateProposal(input, index, contentLength) {
     const p = obj(input, `proposal[${index}]`);

package/dist/src/index.d.ts

@@ -3,6 +3,8 @@ export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeResolutionIdentity, exportExtractionEnvelopeImport, extractionEnvelopeImportApiVersion, importExtractionEnvelope, portableExtractionResultFormat, portableExtractionResultVersion, reimportExtractionEnvelope, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
+export { resolvePortablePdfRegion } from "./pdf-layout.js";
+export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry, PortablePdfRegionContext, PortablePdfTable, PortablePdfTableCell, PortablePdfTextElement, PortablePdfTextRange, } from "./pdf-layout.js";
 export type { ExtractionAlignmentState, ArtifactUnavailableCode, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
 export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionOccurrence, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.js";
 export type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";

package/dist/src/index.js

@@ -2,6 +2,7 @@ export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeResolutionIdentity, exportExtractionEnvelopeImport, extractionEnvelopeImportApiVersion, importExtractionEnvelope, portableExtractionResultFormat, portableExtractionResultVersion, reimportExtractionEnvelope, validateExtractionEnvelopeImport, } from "./extraction-envelope.js";
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
+export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";

package/dist/src/pdf-layout.d.ts

@@ -0,0 +1,53 @@
+export interface PortablePdfTextRange {
+    start: number;
+    end: number;
+}
+export interface PortablePdfBoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PortablePdfPageGeometry {
+    pageNumber: number;
+    width: number;
+    height: number;
+    unit: "points" | "pixels" | "normalized";
+    rotation?: 0 | 90 | 180 | 270;
+}
+export interface PortablePdfTextElement {
+    kind: "heading" | "paragraph" | "list" | "table" | "table-cell" | "figure" | "other";
+    providerType?: string;
+    pageNumber: number;
+    range: PortablePdfTextRange;
+    bounds?: PortablePdfBoundingBox;
+}
+export interface PortablePdfTableCell {
+    rowIndex: number;
+    columnIndex: number;
+    rowSpan?: number;
+    columnSpan?: number;
+    range: PortablePdfTextRange;
+    bounds?: PortablePdfBoundingBox;
+}
+export interface PortablePdfTable {
+    pageNumber: number;
+    bounds?: PortablePdfBoundingBox;
+    cells: PortablePdfTableCell[];
+}
+export interface PortablePdfLayout {
+    pages?: PortablePdfPageGeometry[];
+    elements: PortablePdfTextElement[];
+    tables?: PortablePdfTable[];
+}
+export interface PortablePdfRegionContext {
+    pages: number[];
+    elements: PortablePdfTextElement[];
+    tableCells: Array<{
+        pageNumber: number;
+        tableIndex: number;
+        cell: PortablePdfTableCell;
+    }>;
+}
+export declare function validatePortablePdfLayout(value: unknown, textLength: number): PortablePdfLayout;
+export declare function resolvePortablePdfRegion(layout: PortablePdfLayout, locator: string): PortablePdfRegionContext | undefined;

package/dist/src/pdf-layout.js

@@ -0,0 +1,201 @@
+const MAX_LAYOUT_ITEMS = 10_000;
+const COORDINATE_UNITS = new Set(["points", "pixels", "normalized"]);
+const ROTATIONS = new Set([0, 90, 180, 270]);
+const ELEMENT_KINDS = new Set(["heading", "paragraph", "list", "table", "table-cell", "figure", "other"]);
+export function validatePortablePdfLayout(value, textLength) {
+    if (!Number.isSafeInteger(textLength) || textLength < 0)
+        throw new Error("PDF layout text length is invalid.");
+    const layout = record(value, "result.pdfLayout");
+    exact(layout, ["elements"], ["pages", "tables"], "result.pdfLayout");
+    const rawPages = optionalArray(layout.pages, "result.pdfLayout.pages");
+    const rawElements = boundedArray(layout.elements, "result.pdfLayout.elements");
+    const rawTables = optionalArray(layout.tables, "result.pdfLayout.tables");
+    const pages = rawPages?.map((value, index) => validatePage(value, `result.pdfLayout.pages[${index}]`));
+    const pageByNumber = new Map();
+    for (const page of pages ?? []) {
+        if (pageByNumber.has(page.pageNumber))
+            throw new Error("PDF layout page numbers must be unique.");
+        pageByNumber.set(page.pageNumber, page);
+    }
+    const pageExists = (pageNumber) => pageByNumber.size === 0 || pageByNumber.has(pageNumber);
+    const elements = rawElements.map((value, index) => validateElement(value, `result.pdfLayout.elements[${index}]`, textLength, pageByNumber, pageExists));
+    const tables = rawTables?.map((value, index) => validateTable(value, `result.pdfLayout.tables[${index}]`, textLength, pageByNumber, pageExists));
+    pages?.sort((left, right) => left.pageNumber - right.pageNumber);
+    elements.sort((left, right) => left.range.start - right.range.start ||
+        left.range.end - right.range.end ||
+        left.pageNumber - right.pageNumber ||
+        left.kind.localeCompare(right.kind));
+    tables?.sort((left, right) => left.pageNumber - right.pageNumber ||
+        (left.cells[0]?.range.start ?? 0) - (right.cells[0]?.range.start ?? 0));
+    return {
+        ...(pages ? { pages } : {}),
+        elements,
+        ...(tables ? { tables } : {}),
+    };
+}
+export function resolvePortablePdfRegion(layout, locator) {
+    const match = /^chars:(0|[1-9]\d*)-(0|[1-9]\d*)$/.exec(locator);
+    if (!match)
+        return undefined;
+    const span = { start: Number(match[1]), end: Number(match[2]) };
+    if (!Number.isSafeInteger(span.start) || !Number.isSafeInteger(span.end) || span.end <= span.start)
+        return undefined;
+    const elements = layout.elements.filter((element) => overlaps(element.range, span));
+    const tableCells = (layout.tables ?? []).flatMap((table, tableIndex) => table.cells
+        .filter((cell) => overlaps(cell.range, span))
+        .map((cell) => ({ pageNumber: table.pageNumber, tableIndex, cell })));
+    const pages = [...new Set([
+            ...elements.map((element) => element.pageNumber),
+            ...tableCells.map((entry) => entry.pageNumber),
+        ])].sort((left, right) => left - right);
+    return { pages, elements, tableCells };
+}
+function validatePage(value, subject) {
+    const page = record(value, subject);
+    exact(page, ["pageNumber", "width", "height", "unit"], ["rotation"], subject);
+    positiveInteger(page.pageNumber, `${subject}.pageNumber`);
+    positiveFinite(page.width, `${subject}.width`);
+    positiveFinite(page.height, `${subject}.height`);
+    if (!COORDINATE_UNITS.has(page.unit))
+        throw new Error(`${subject}.unit is invalid.`);
+    if (page.rotation !== undefined && !ROTATIONS.has(page.rotation))
+        throw new Error(`${subject}.rotation is invalid.`);
+    return {
+        pageNumber: page.pageNumber,
+        width: page.width,
+        height: page.height,
+        unit: page.unit,
+        ...(page.rotation === undefined ? {} : { rotation: page.rotation }),
+    };
+}
+function validateElement(value, subject, textLength, pages, pageExists) {
+    const element = record(value, subject);
+    exact(element, ["kind", "pageNumber", "range"], ["providerType", "bounds"], subject);
+    if (!ELEMENT_KINDS.has(element.kind))
+        throw new Error(`${subject}.kind is invalid.`);
+    positiveInteger(element.pageNumber, `${subject}.pageNumber`);
+    if (!pageExists(element.pageNumber))
+        throw new Error(`${subject}.pageNumber is not declared.`);
+    if (element.providerType !== undefined && typeof element.providerType !== "string")
+        throw new Error(`${subject}.providerType is invalid.`);
+    return {
+        kind: element.kind,
+        ...(element.providerType === undefined ? {} : { providerType: element.providerType }),
+        pageNumber: element.pageNumber,
+        range: validateRange(element.range, `${subject}.range`, textLength),
+        ...(element.bounds === undefined ? {} : {
+            bounds: validateBounds(element.bounds, `${subject}.bounds`, pages.get(element.pageNumber)),
+        }),
+    };
+}
+function validateTable(value, subject, textLength, pages, pageExists) {
+    const table = record(value, subject);
+    exact(table, ["pageNumber", "cells"], ["bounds"], subject);
+    positiveInteger(table.pageNumber, `${subject}.pageNumber`);
+    if (!pageExists(table.pageNumber))
+        throw new Error(`${subject}.pageNumber is not declared.`);
+    const occupied = new Set();
+    const cells = boundedArray(table.cells, `${subject}.cells`).map((value, index) => {
+        const cellSubject = `${subject}.cells[${index}]`;
+        const cell = record(value, cellSubject);
+        exact(cell, ["rowIndex", "columnIndex", "range"], ["rowSpan", "columnSpan", "bounds"], cellSubject);
+        nonnegativeInteger(cell.rowIndex, `${cellSubject}.rowIndex`);
+        nonnegativeInteger(cell.columnIndex, `${cellSubject}.columnIndex`);
+        if (cell.rowSpan !== undefined)
+            positiveInteger(cell.rowSpan, `${cellSubject}.rowSpan`);
+        if (cell.columnSpan !== undefined)
+            positiveInteger(cell.columnSpan, `${cellSubject}.columnSpan`);
+        const key = `${cell.rowIndex}:${cell.columnIndex}`;
+        if (occupied.has(key))
+            throw new Error(`${subject} contains duplicate table coordinates.`);
+        occupied.add(key);
+        return {
+            rowIndex: cell.rowIndex,
+            columnIndex: cell.columnIndex,
+            ...(cell.rowSpan === undefined ? {} : { rowSpan: cell.rowSpan }),
+            ...(cell.columnSpan === undefined ? {} : { columnSpan: cell.columnSpan }),
+            range: validateRange(cell.range, `${cellSubject}.range`, textLength),
+            ...(cell.bounds === undefined ? {} : {
+                bounds: validateBounds(cell.bounds, `${cellSubject}.bounds`, pages.get(table.pageNumber)),
+            }),
+        };
+    });
+    cells.sort((left, right) => left.rowIndex - right.rowIndex ||
+        left.columnIndex - right.columnIndex ||
+        left.range.start - right.range.start);
+    return {
+        pageNumber: table.pageNumber,
+        ...(table.bounds === undefined ? {} : {
+            bounds: validateBounds(table.bounds, `${subject}.bounds`, pages.get(table.pageNumber)),
+        }),
+        cells,
+    };
+}
+function validateRange(value, subject, textLength) {
+    const range = record(value, subject);
+    exact(range, ["start", "end"], [], subject);
+    nonnegativeInteger(range.start, `${subject}.start`);
+    nonnegativeInteger(range.end, `${subject}.end`);
+    if (range.end <= range.start || range.end > textLength) {
+        throw new Error(`${subject} is outside the prepared text.`);
+    }
+    return { start: range.start, end: range.end };
+}
+function validateBounds(value, subject, page) {
+    const bounds = record(value, subject);
+    exact(bounds, ["x", "y", "width", "height"], [], subject);
+    nonnegativeFinite(bounds.x, `${subject}.x`);
+    nonnegativeFinite(bounds.y, `${subject}.y`);
+    positiveFinite(bounds.width, `${subject}.width`);
+    positiveFinite(bounds.height, `${subject}.height`);
+    const result = {
+        x: bounds.x,
+        y: bounds.y,
+        width: bounds.width,
+        height: bounds.height,
+    };
+    if (page && (result.x + result.width > page.width || result.y + result.height > page.height)) {
+        throw new Error(`${subject} exceeds its page geometry.`);
+    }
+    return result;
+}
+function boundedArray(value, subject) {
+    if (!Array.isArray(value) || value.length > MAX_LAYOUT_ITEMS)
+        throw new Error(`${subject} must be a bounded array.`);
+    return value;
+}
+function optionalArray(value, subject) {
+    return value === undefined ? undefined : boundedArray(value, subject);
+}
+function record(value, subject) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${subject} must be an object.`);
+    return value;
+}
+function exact(value, required, optional, subject) {
+    for (const key of required)
+        if (!Object.hasOwn(value, key))
+            throw new Error(`${subject}.${key} is required.`);
+    for (const key of Object.keys(value))
+        if (![...required, ...optional].includes(key))
+            throw new Error(`${subject}.${key} is unexpected.`);
+}
+function nonnegativeInteger(value, subject) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${subject} must be a non-negative safe integer.`);
+}
+function positiveInteger(value, subject) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${subject} must be a positive safe integer.`);
+}
+function nonnegativeFinite(value, subject) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        throw new Error(`${subject} must be a non-negative finite number.`);
+}
+function positiveFinite(value, subject) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        throw new Error(`${subject} must be a positive finite number.`);
+}
+function overlaps(left, right) {
+    return left.start < right.end && right.start < left.end;
+}

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

@@ -1,4 +1,5 @@
 import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
+import { type PortablePdfRegionContext } from "../pdf-layout.js";
 export type ExtractionAlignmentState = "aligned" | "excerpt-mismatch" | "artifact-unavailable" | "digest-mismatch";
 export type ArtifactUnavailableCode = "not-found" | "storage-error" | "access-denied" | "invalid-artifact" | "unknown";
 export type ResolvedExtractionArtifact = {
@@ -38,6 +39,8 @@ export interface ExtractionInspectorCandidate {
     end: number;
     excerpt: string;
     alignment: ExtractionAlignmentState;
+    pdfRegion?: PortablePdfRegionContext;
+    ocrDerived?: true;
 }
 export interface ExtractionInspectorSource {
     key: string;
@@ -46,6 +49,7 @@ export interface ExtractionInspectorSource {
     expectedDigest?: string;
     actualDigest?: string;
     artifactText?: string;
+    ocrDerived?: true;
     alignment: ExtractionAlignmentState;
     message: string;
 }
@@ -61,11 +65,16 @@ export interface ExtractionInspectorFilters {
     pass?: string;
     inferenceType?: "explicit" | "inferred";
     alignment?: ExtractionAlignmentState;
+    query?: string;
 }
 export interface ExtractionInspectorExportOptions {
     includePreparedText?: boolean;
     includeExcerpts?: boolean;
 }
+export interface ExtractionInspectorMountOptions {
+    /** Maximum candidate rows and source highlights mounted at once. Defaults to 100 and is capped at 500. */
+    pageSize?: number;
+}
 /**
  * Build a read-only view from one or more results already produced by Survey's
  * public import boundary. The function rechecks the result/ReviewItem binding
@@ -74,4 +83,4 @@ export interface ExtractionInspectorExportOptions {
 export declare function buildExtractionInspectorModel(input: ExtractionInspectorInput): ExtractionInspectorModel;
 export declare function filterExtractionInspectorCandidates(model: ExtractionInspectorModel, filters: ExtractionInspectorFilters): ExtractionInspectorCandidate[];
 export declare function exportExtractionInspector(model: ExtractionInspectorModel, options?: ExtractionInspectorExportOptions): string;
-export declare function mountExtractionInspector(container: HTMLElement, model: ExtractionInspectorModel): () => void;
+export declare function mountExtractionInspector(container: HTMLElement, model: ExtractionInspectorModel, options?: ExtractionInspectorMountOptions): () => void;

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

@@ -1,6 +1,7 @@
 import { buildReviewItemsFromExtractionEnvelopeImport, validateExtractionEnvelopeImport } from "../extraction-envelope.js";
 import { canonicalJson } from "./canonical.js";
 import { sha256Hex } from "../sha256.js";
+import { resolvePortablePdfRegion, } from "../pdf-layout.js";
 /**
  * Build a read-only view from one or more results already produced by Survey's
  * public import boundary. The function rechecks the result/ReviewItem binding
@@ -25,14 +26,14 @@ export function buildExtractionInspectorModel(input) {
         if (sourceKeys.has(sourceKey))
             throw new Error("Extraction inspector source identity collision.");
         sourceKeys.add(sourceKey);
-        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.state, entry.artifact);
+        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.state, entry.artifact, envelope.result.ocrDerived);
         sources.push(source);
         const candidateStart = candidates.length;
         envelope.result.proposals.forEach((proposal, proposalIndex) => {
             const item = entry.importResult.reviewItems[proposalIndex];
             if (!item)
                 return; // unresolved imports legitimately produce no ReviewItems
-            candidates.push(candidateModel(source, item.metadata.name, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass));
+            candidates.push(candidateModel(source, item.metadata.name, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass, envelope.result.pdfPageOffsets, envelope.result.pdfLayout, envelope.result.ocrDerived));
         });
         if (source.alignment === "excerpt-mismatch") {
             delete source.artifactText;
@@ -88,7 +89,7 @@ function assertImportedResult(result, record) {
         }
     });
 }
-function sourceModel(key, importName, prepared, state, artifact) {
+function sourceModel(key, importName, prepared, state, artifact, ocrDerived) {
     let alignment;
     let message;
     if (state !== "grounded" || artifact.status === "unavailable") {
@@ -106,11 +107,11 @@ function sourceModel(key, importName, prepared, state, artifact) {
     }
     else {
         alignment = "aligned";
-        message = "Prepared artifact identity verified. Exact source spans are available.";
+        message = `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
     }
-    return { key, importName, ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), alignment, message };
+    return { key, importName, ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), ...(ocrDerived ? { ocrDerived: true } : {}), alignment, message };
 }
-function candidateModel(source, reviewItemName, proposal, index, provider, model, attempt, pass) {
+function candidateModel(source, reviewItemName, proposal, index, provider, model, attempt, pass, pdfPageOffsets, pdfLayout, ocrDerived) {
     const match = /^chars:(\d+)-(\d+)$/.exec(proposal.provenance.locator);
     if (!match)
         throw new Error(`Extraction proposal ${index} has an invalid text span.`);
@@ -122,13 +123,42 @@ function candidateModel(source, reviewItemName, proposal, index, provider, model
         source.alignment = alignment;
         source.message = "One or more source spans do not match their recorded excerpts. Affected candidates are not grounded.";
     }
-    return { id: `${source.key}:proposal:${index}`, sourceKey: source.key, reviewItemName, proposalIndex: index, field: proposal.fieldPath, provider, ...(model ? { model } : {}), attempt, ...(pass ? { pass } : {}), valueType: proposal.valueType ?? inferValueType(proposal.candidateValue), inferenceType: proposal.inferenceType ?? "inferred", start, end, excerpt: proposal.provenance.excerpt, alignment };
+    let pdfRegion = pdfLayout ? resolvePortablePdfRegion(pdfLayout, proposal.provenance.locator) : undefined;
+    const page = resolvePdfPage(pdfPageOffsets, start);
+    if (page !== undefined) {
+        pdfRegion = {
+            pages: [...new Set([...(pdfRegion?.pages ?? []), page])].sort((left, right) => left - right),
+            elements: pdfRegion?.elements ?? [],
+            tableCells: pdfRegion?.tableCells ?? [],
+        };
+    }
+    return { id: `${source.key}:proposal:${index}`, sourceKey: source.key, reviewItemName, proposalIndex: index, field: proposal.fieldPath, provider, ...(model ? { model } : {}), attempt, ...(pass ? { pass } : {}), valueType: proposal.valueType ?? inferValueType(proposal.candidateValue), inferenceType: proposal.inferenceType ?? "inferred", start, end, excerpt: proposal.provenance.excerpt, alignment, ...(pdfRegion ? { pdfRegion } : {}), ...(ocrDerived ? { ocrDerived: true } : {}) };
 }
 function inferValueType(value) { if (Array.isArray(value))
     return "array"; if (value !== null && typeof value === "object")
     return "object"; return typeof value === "number" ? "number" : typeof value === "boolean" ? "boolean" : "string"; }
+function resolvePdfPage(offsets, start) {
+    if (!offsets || offsets.length === 0)
+        return undefined;
+    let page;
+    for (let index = 0; index < offsets.length; index += 1) {
+        if (offsets[index] > start)
+            break;
+        page = index + 1;
+    }
+    return page;
+}
 export function filterExtractionInspectorCandidates(model, filters) {
-    return model.candidates.filter((c) => (!filters.field || c.field === filters.field) && (!filters.provider || c.provider === filters.provider) && (!filters.model || c.model === filters.model) && (!filters.attempt || c.attempt === filters.attempt) && (!filters.pass || c.pass === filters.pass) && (!filters.inferenceType || c.inferenceType === filters.inferenceType) && (!filters.alignment || c.alignment === filters.alignment));
+    const query = filters.query?.trim().toLocaleLowerCase();
+    return model.candidates.filter((c) => (!filters.field || c.field === filters.field)
+        && (!filters.provider || c.provider === filters.provider)
+        && (!filters.model || c.model === filters.model)
+        && (!filters.attempt || c.attempt === filters.attempt)
+        && (!filters.pass || c.pass === filters.pass)
+        && (!filters.inferenceType || c.inferenceType === filters.inferenceType)
+        && (!filters.alignment || c.alignment === filters.alignment)
+        && (!query || [c.field, c.excerpt, c.reviewItemName, c.provider, c.model ?? "", c.pass ?? ""]
+            .some(value => value.toLocaleLowerCase().includes(query))));
 }
 export function exportExtractionInspector(model, options = {}) {
     return canonicalJson({ apiVersion: "survey.kontourai.io/v1alpha1", kind: "ExtractionInspectorExport", spec: {
@@ -137,25 +167,45 @@ export function exportExtractionInspector(model, options = {}) {
             candidates: model.candidates.map((candidate) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
         } });
 }
-export function mountExtractionInspector(container, model) {
+export function mountExtractionInspector(container, model, options = {}) {
+    const pageSize = Number.isSafeInteger(options.pageSize) && Number(options.pageSize) > 0
+        ? Math.min(Number(options.pageSize), 500)
+        : 100;
+    let page = 0;
     const root = document.createElement("section");
     root.className = "extraction-inspector";
     root.setAttribute("aria-label", "Source-linked extraction inspector");
-    const options = (values) => [...new Set(values.filter((v) => Boolean(v)))].map((v) => `<option value="${escapeHtml(v)}">${escapeHtml(v)}</option>`).join("");
-    root.innerHTML = `<div class="inspector-heading"><div><p class="eyebrow">Source inspector</p><h2>Extraction evidence</h2></div><div class="inspector-postures" aria-live="polite"></div></div><div class="inspector-filters" aria-label="Extraction filters">${filterSelect("field", "Field", options(model.candidates.map(c => c.field)))}${filterSelect("provider", "Provider", options(model.candidates.map(c => c.provider)))}${filterSelect("model", "Model", options(model.candidates.map(c => c.model)))}${filterSelect("attempt", "Attempt", options(model.candidates.map(c => c.attempt)))}${filterSelect("pass", "Pass", options(model.candidates.map(c => c.pass)))}${filterSelect("inferenceType", "Type origin", '<option value="explicit">explicit</option><option value="inferred">inferred</option>')}${filterSelect("alignment", "Alignment", options(model.candidates.map(c => c.alignment)))}</div><div class="inspector-layout"><ol class="inspector-candidates" aria-label="Extraction candidates"></ol><div class="inspector-sources"></div></div>`;
+    const choiceOptions = (values) => [...new Set(values.filter((v) => Boolean(v)))].map((v) => `<option value="${escapeHtml(v)}">${escapeHtml(v)}</option>`).join("");
+    root.innerHTML = `<div class="inspector-heading"><div><p class="eyebrow">Source inspector</p><h2>Extraction evidence</h2></div><div class="inspector-postures" aria-live="polite"></div></div><div class="inspector-filters" aria-label="Extraction filters"><label>Find candidates<input type="search" data-filter="query" placeholder="Field or excerpt"></label>${filterSelect("field", "Field", choiceOptions(model.candidates.map(c => c.field)))}${filterSelect("provider", "Provider", choiceOptions(model.candidates.map(c => c.provider)))}${filterSelect("model", "Model", choiceOptions(model.candidates.map(c => c.model)))}${filterSelect("attempt", "Attempt", choiceOptions(model.candidates.map(c => c.attempt)))}${filterSelect("pass", "Pass", choiceOptions(model.candidates.map(c => c.pass)))}${filterSelect("inferenceType", "Type origin", '<option value="explicit">explicit</option><option value="inferred">inferred</option>')}${filterSelect("alignment", "Alignment", choiceOptions(model.candidates.map(c => c.alignment)))}</div><nav class="inspector-pager" aria-label="Extraction candidate navigation"><span class="inspector-result-count" aria-live="polite"></span><button type="button" data-page="previous">Previous</button><span class="inspector-page"></span><button type="button" data-page="next">Next</button></nav><div class="inspector-layout"><ol class="inspector-candidates" aria-label="Extraction candidates"></ol><div class="inspector-sources"></div></div>`;
     container.appendChild(root);
     const list = root.querySelector("ol"), sourcesRoot = root.querySelector(".inspector-sources"), postures = root.querySelector(".inspector-postures");
+    const resultCount = root.querySelector(".inspector-result-count"), pageLabel = root.querySelector(".inspector-page");
+    const previous = root.querySelector('[data-page="previous"]'), next = root.querySelector('[data-page="next"]');
     const filters = {};
     const render = () => {
-        const visible = filterExtractionInspectorCandidates(model, filters);
-        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></button></li>`).join("") || "<li>No candidates match these filters.</li>";
+        const matching = filterExtractionInspectorCandidates(model, filters);
+        const pageCount = Math.max(1, Math.ceil(matching.length / pageSize));
+        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>";
+        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}`;
+        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("");
     };
     root.querySelectorAll("select").forEach(select => select.addEventListener("change", event => { event.stopPropagation(); const key = select.dataset.filter; if (select.value)
         filters[key] = select.value;
     else
-        delete filters[key]; render(); }));
+        delete filters[key]; page = 0; render(); }));
+    root.querySelector('input[data-filter="query"]')?.addEventListener("input", event => { event.stopPropagation(); const input = event.currentTarget; if (input.value)
+        filters.query = input.value;
+    else
+        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) {
@@ -168,10 +218,17 @@ export function mountExtractionInspector(container, model) {
         event.stopPropagation();
         root.querySelector(`#candidate-${CSS.escape(safeId(highlight.dataset.highlightCandidateId))}`)?.focus();
     } });
-    root.addEventListener("keydown", event => { const button = event.target.closest("button[data-candidate-id]"); if (button && (event.key === "Enter" || event.key === " ")) {
+    root.addEventListener("keydown", event => { const button = event.target.closest("button[data-candidate-id]"); if (!button)
+        return; if (event.key === "Enter" || event.key === " ") {
         event.preventDefault();
         event.stopPropagation();
         activateCandidate(button.dataset.candidateId);
+        return;
+    } if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        const buttons = [...list.querySelectorAll("button[data-candidate-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();
@@ -193,6 +250,20 @@ function renderSource(text, candidates) {
     }
     return html;
 }
+function formatContext(candidate) {
+    const context = [];
+    if (candidate.pdfRegion) {
+        if (candidate.pdfRegion.pages.length > 0)
+            context.push(`PDF page${candidate.pdfRegion.pages.length === 1 ? "" : "s"} ${candidate.pdfRegion.pages.join(", ")}`);
+        if (candidate.pdfRegion.elements.length > 0)
+            context.push(`${candidate.pdfRegion.elements.length} layout element${candidate.pdfRegion.elements.length === 1 ? "" : "s"}`);
+        if (candidate.pdfRegion.tableCells.length > 0)
+            context.push(`${candidate.pdfRegion.tableCells.length} table cell${candidate.pdfRegion.tableCells.length === 1 ? "" : "s"}`);
+    }
+    if (candidate.ocrDerived)
+        context.push("OCR-derived");
+    return context.length > 0 ? `<span class="inspector-format-context">${escapeHtml(context.join(" · "))}</span>` : "";
+}
 function filterSelect(key, label, choices) { return `<label>${escapeHtml(label)}<select data-filter="${key}"><option value="">All</option>${choices}</select></label>`; }
 function safeId(value) { return value.replace(/[^a-zA-Z0-9_-]/g, "-"); }
 function escapeHtml(text) { return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;"); }

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

@@ -195,7 +195,11 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .inspector-posture.digest-mismatch, .survey-workbench-embed .inspector-posture.artifact-unavailable, .survey-workbench-embed .inspector-posture.excerpt-mismatch{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
 .survey-workbench-embed .inspector-filters{ display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .survey-workbench-embed .inspector-filters label{ display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
-.survey-workbench-embed .inspector-filters select{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.survey-workbench-embed .inspector-filters select, .survey-workbench-embed .inspector-filters input{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.survey-workbench-embed .inspector-pager, .survey-workbench-embed .queue-controls, .survey-workbench-embed .queue-pager{ display: flex; align-items: end; flex-wrap: wrap; gap: .6rem; }
+.survey-workbench-embed .inspector-pager{ justify-content: flex-end; margin: 0 0 .75rem; }
+.survey-workbench-embed .inspector-pager button, .survey-workbench-embed .queue-pager button{ color: var(--k-text); background: var(--k-raised); border: 1px solid var(--k-line-strong); border-radius: var(--k-radius-sm); padding: .45rem .7rem; }
+.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; }
@@ -206,6 +210,12 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .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; } }
 
+.survey-workbench-embed .queue-controls{ padding: 1rem; border-bottom: 1px solid var(--k-line); background: var(--k-panel); }
+.survey-workbench-embed .queue-controls label{ display: grid; gap: .25rem; color: var(--k-muted); font-size: .75rem; }
+.survey-workbench-embed .queue-controls input, .survey-workbench-embed .queue-controls select{ min-height: 2.25rem; color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); border-radius: var(--k-radius-sm); padding: .4rem .55rem; }
+.survey-workbench-embed .queue-result-count{ margin-left: auto; color: var(--k-muted); }
+.survey-workbench-embed .queue-empty{ padding: 2rem; color: var(--k-muted); text-align: center; }
+
 /* Re-assert the base structural tokens for light mode. themes.css's \`.theme-*\`
    preset classes hardcode a dark --k-bg/--k-panel/etc (so the preset "just
    works" without requiring [data-theme] to be set), and a bare class selector

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

@@ -192,7 +192,11 @@
 .survey-workbench-embed .inspector-posture.digest-mismatch, .survey-workbench-embed .inspector-posture.artifact-unavailable, .survey-workbench-embed .inspector-posture.excerpt-mismatch{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
 .survey-workbench-embed .inspector-filters{ display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .survey-workbench-embed .inspector-filters label{ display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
-.survey-workbench-embed .inspector-filters select{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.survey-workbench-embed .inspector-filters select, .survey-workbench-embed .inspector-filters input{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.survey-workbench-embed .inspector-pager, .survey-workbench-embed .queue-controls, .survey-workbench-embed .queue-pager{ display: flex; align-items: end; flex-wrap: wrap; gap: .6rem; }
+.survey-workbench-embed .inspector-pager{ justify-content: flex-end; margin: 0 0 .75rem; }
+.survey-workbench-embed .inspector-pager button, .survey-workbench-embed .queue-pager button{ color: var(--k-text); background: var(--k-raised); border: 1px solid var(--k-line-strong); border-radius: var(--k-radius-sm); padding: .45rem .7rem; }
+.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; }
@@ -203,6 +207,12 @@
 .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; } }
 
+.survey-workbench-embed .queue-controls{ padding: 1rem; border-bottom: 1px solid var(--k-line); background: var(--k-panel); }
+.survey-workbench-embed .queue-controls label{ display: grid; gap: .25rem; color: var(--k-muted); font-size: .75rem; }
+.survey-workbench-embed .queue-controls input, .survey-workbench-embed .queue-controls select{ min-height: 2.25rem; color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); border-radius: var(--k-radius-sm); padding: .4rem .55rem; }
+.survey-workbench-embed .queue-result-count{ margin-left: auto; color: var(--k-muted); }
+.survey-workbench-embed .queue-empty{ padding: 2rem; color: var(--k-muted); text-align: center; }
+
 /* Re-assert the base structural tokens for light mode. themes.css's `.theme-*`
    preset classes hardcode a dark --k-bg/--k-panel/etc (so the preset "just
    works" without requiring [data-theme] to be set), and a bare class selector

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

@@ -2,7 +2,7 @@ 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 ExtractionInspectorModel, type ExtractionInspectorSource, type ResolvedExtractionArtifact, } from "./extraction-inspector.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 { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, 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";
@@ -83,6 +83,23 @@ export interface PersistentReviewSessionEventStoreOptions {
 export interface MountReviewWorkbenchOptions {
     readonly eventStore?: ReviewSessionEventStore;
     readonly presentationAdapter?: ReviewPresentationAdapter;
+    /** Maximum review cards mounted at once. Defaults to 50 and is capped at 250. */
+    readonly pageSize?: number;
+}
+export type ReviewQueueDisposition = "all" | "unresolved" | "accepted" | "kept" | "rejected" | "could-not-confirm";
+export interface ReviewQueueView {
+    readonly query: string;
+    readonly disposition: ReviewQueueDisposition;
+    readonly page: number;
+    readonly pageSize: number;
+}
+export interface ReviewQueueWindow {
+    readonly items: readonly ReviewItem[];
+    readonly totalMatching: number;
+    readonly page: number;
+    readonly pageCount: number;
+    readonly start: number;
+    readonly end: number;
 }
 export interface BrowserReviewWorkbenchConfig {
     readonly startState?: ReviewQueueSessionState | ReviewWorkbenchState;
@@ -179,7 +196,9 @@ export declare function createPersistentReviewSessionEventStore(options: Persist
 };
 export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, _events?: readonly ReviewSessionEvent[], options?: {
     readonly presentationAdapter?: ReviewPresentationAdapter;
+    readonly queueView?: Partial<ReviewQueueView>;
 }): string;
+export declare function buildReviewQueueWindow(session: ReviewQueueSessionState, view?: Partial<ReviewQueueView>): ReviewQueueWindow;
 /**
  * Validates a reviewer's raw (string) edit of a proposed value against the
  * field's neutral {@link ReviewValueDescriptor}, returning a human-readable

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

@@ -455,7 +455,7 @@ export function createPersistentReviewSessionEventStore(options) {
 }
 export function renderReviewWorkbenchHtml(state, _events, options = {}) {
     const session = queueSessionFromStartState(state);
-    return renderReviewQueueSessionHtml(session, options.presentationAdapter);
+    return renderReviewQueueSessionHtml(session, options.presentationAdapter, normalizeReviewQueueView(options.queueView));
 }
 /**
  * The visual/decision state of a field card, derived from the reviewer's local
@@ -484,12 +484,56 @@ function chipLabel(state) {
         default: return "Needs review";
     }
 }
+const DEFAULT_REVIEW_QUEUE_PAGE_SIZE = 50;
+function normalizeReviewQueueView(view) {
+    const pageSize = Number.isSafeInteger(view?.pageSize) && Number(view?.pageSize) > 0
+        ? Math.min(Number(view?.pageSize), 250)
+        : DEFAULT_REVIEW_QUEUE_PAGE_SIZE;
+    return {
+        query: view?.query?.trim() ?? "",
+        disposition: view?.disposition ?? "all",
+        page: Number.isSafeInteger(view?.page) && Number(view?.page) >= 0 ? Number(view?.page) : 0,
+        pageSize,
+    };
+}
+export function buildReviewQueueWindow(session, view = {}) {
+    const normalized = normalizeReviewQueueView(view);
+    const query = normalized.query.toLocaleLowerCase();
+    const matching = session.items.filter((item) => {
+        const state = fieldCardState(item, session.decisionsByItemName[item.metadata.name]);
+        const dispositionMatches = normalized.disposition === "all"
+            || (normalized.disposition === "unresolved" ? state === "review" : state === normalized.disposition);
+        if (!dispositionMatches)
+            return false;
+        if (!query)
+            return true;
+        const producerDisplayName = item.metadata.producer?.displayName;
+        return [
+            item.metadata.name,
+            item.spec.target,
+            typeof producerDisplayName === "string" ? producerDisplayName : "",
+            ...item.spec.candidates.map((candidate) => formatValue(candidate.value)),
+        ].some((value) => value.toLocaleLowerCase().includes(query));
+    });
+    const pageCount = Math.max(1, Math.ceil(matching.length / normalized.pageSize));
+    const page = Math.min(normalized.page, pageCount - 1);
+    const start = page * normalized.pageSize;
+    const end = Math.min(start + normalized.pageSize, matching.length);
+    return {
+        items: matching.slice(start, end),
+        totalMatching: matching.length,
+        page,
+        pageCount,
+        start,
+        end,
+    };
+}
 function isEmptyValue(value) {
     return value === undefined || value === null || value === "";
 }
 const ARROW_SVG = "<svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><path d=\"M5 12h14M13 6l6 6-6 6\"/></svg>";
 const WARNING_SVG = "<svg width=\"15\" height=\"15\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" aria-hidden=\"true\"><path d=\"M12 9v4M12 17h.01\"/><path d=\"M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z\"/></svg>";
-function renderReviewQueueSessionHtml(session, presentationAdapter) {
+function renderReviewQueueSessionHtml(session, presentationAdapter, queueView) {
     const totalCount = session.items.length;
     const decidedCount = session.items.filter((item) => session.decisionsByItemName[item.metadata.name] !== undefined
         || item.spec.candidateSetStatus === "resolved").length;
@@ -497,6 +541,7 @@ function renderReviewQueueSessionHtml(session, presentationAdapter) {
     const headerItem = session.items[0];
     const producerName = headerItem?.metadata.producer?.displayName;
     const headerTitle = typeof producerName === "string" && producerName.length > 0 ? producerName : "Review queue";
+    const window = buildReviewQueueWindow(session, queueView);
     return `
     <section class="workbench-shell review" data-testid="review-workbench-shell" aria-label="Survey review workbench">
       <header class="rhead">
@@ -515,13 +560,43 @@ function renderReviewQueueSessionHtml(session, presentationAdapter) {
           <button class="apply" type="button" data-testid="apply-button"${decidedCount === 0 ? " disabled" : ""}>Apply ${decidedCount} decision${decidedCount === 1 ? "" : "s"}</button>
         </div>
       </header>
+      <nav class="queue-controls" aria-label="Review queue navigation">
+        <label>
+          <span>Find fields</span>
+          <input type="search" data-testid="queue-search" value="${escapeHtml(queueView.query)}" placeholder="Field or value">
+        </label>
+        <label>
+          <span>Disposition</span>
+          <select data-testid="queue-disposition">${queueDispositionOptions(queueView.disposition)}</select>
+        </label>
+        <span class="queue-result-count" aria-live="polite">
+          ${window.totalMatching === 0 ? "No matching fields" : `${window.start + 1}–${window.end} of ${window.totalMatching}`}
+        </span>
+        <div class="queue-pager">
+          <button type="button" data-testid="queue-previous"${window.page === 0 ? " disabled" : ""}>Previous</button>
+          <span>Page ${window.page + 1} of ${window.pageCount}</span>
+          <button type="button" data-testid="queue-next"${window.page >= window.pageCount - 1 ? " disabled" : ""}>Next</button>
+        </div>
+      </nav>
       <div class="fields" data-testid="review-fields">
-        ${session.items.map((item) => renderFieldCard(item, session, presentationAdapter)).join("")}
+        ${window.items.map((item) => renderFieldCard(item, session, presentationAdapter)).join("")
+        || '<p class="queue-empty">No review fields match the current search and disposition.</p>'}
       </div>
       ${renderFooterTally(session)}
     </section>
   `;
 }
+function queueDispositionOptions(selected) {
+    const options = [
+        ["all", "All fields"],
+        ["unresolved", "Needs review"],
+        ["accepted", "Accepted"],
+        ["kept", "Kept current"],
+        ["rejected", "Flagged wrong"],
+        ["could-not-confirm", "Could not confirm"],
+    ];
+    return options.map(([value, label]) => `<option value="${value}"${selected === value ? " selected" : ""}>${label}</option>`).join("");
+}
 function renderFieldCard(item, session, presentationAdapter) {
     const decision = session.decisionsByItemName[item.metadata.name];
     const state = fieldCardState(item, decision);
@@ -991,6 +1066,7 @@ function createReviewWorkbenchController(root, startState, options) {
     const eventStore = options.eventStore ?? browserReviewSessionEventStore();
     let events = eventStore?.load(baseSession) ?? [];
     let session = events.length > 0 ? replayReviewSessionEvents(baseSession, events) : baseSession;
+    let queueView = normalizeReviewQueueView({ pageSize: options.pageSize });
     const persistEvents = () => {
         eventStore?.save(session, events);
     };
@@ -1094,10 +1170,13 @@ function createReviewWorkbenchController(root, startState, options) {
     const controller = {
         currentSession: () => session,
         currentSessionExport: () => buildReviewWorkbenchSessionExport(session, events),
-        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter),
+        renderCurrentState: () => renderCurrentState(root, session, controller, options.presentationAdapter, queueView),
         setDecision,
         clearDecision,
         updateReviewerNote,
+        updateQueueView: (update) => {
+            queueView = normalizeReviewQueueView({ ...queueView, ...update });
+        },
     };
     return controller;
 }
@@ -1111,12 +1190,39 @@ function reviewSessionStorageKey(session, keyPrefix) {
     const itemNames = buildReviewSessionResource(session).spec.reviewItemNames.join(",");
     return `${keyPrefix}:${itemNames}`;
 }
-function renderCurrentState(root, session, controller, presentationAdapter) {
-    root.innerHTML = renderReviewWorkbenchHtml(session, undefined, { presentationAdapter });
+function renderCurrentState(root, session, controller, presentationAdapter, queueView) {
+    root.innerHTML = renderReviewWorkbenchHtml(session, undefined, { presentationAdapter, queueView });
     bindFieldCardInteractions(root, controller);
     bindApplyButton(root, controller);
     bindClampToggles(root);
     bindHistoryExpanders(root);
+    bindQueueControls(root, controller, queueView ?? normalizeReviewQueueView(undefined));
+}
+function bindQueueControls(root, controller, queueView) {
+    const search = root.querySelector('[data-testid="queue-search"]');
+    search?.addEventListener("input", () => {
+        const query = search.value;
+        controller.updateQueueView({ query, page: 0 });
+        controller.renderCurrentState();
+        const nextSearch = root.querySelector('[data-testid="queue-search"]');
+        nextSearch?.focus();
+        nextSearch?.setSelectionRange(query.length, query.length);
+    });
+    root.querySelector('[data-testid="queue-disposition"]')?.addEventListener("change", (event) => {
+        controller.updateQueueView({
+            disposition: event.currentTarget.value,
+            page: 0,
+        });
+        controller.renderCurrentState();
+    });
+    root.querySelector('[data-testid="queue-previous"]')?.addEventListener("click", () => {
+        controller.updateQueueView({ page: Math.max(0, queueView.page - 1) });
+        controller.renderCurrentState();
+    });
+    root.querySelector('[data-testid="queue-next"]')?.addEventListener("click", () => {
+        controller.updateQueueView({ page: queueView.page + 1 });
+        controller.renderCurrentState();
+    });
 }
 function queueSessionFromStartState(startState) {
     if ("items" in startState) {

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

@@ -41,7 +41,11 @@
 .inspector-posture.digest-mismatch, .inspector-posture.artifact-unavailable, .inspector-posture.excerpt-mismatch { background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
 .inspector-filters { display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .inspector-filters label { display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
-.inspector-filters select { color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.inspector-filters select, .inspector-filters input { color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }
+.inspector-pager, .queue-controls, .queue-pager { display: flex; align-items: end; flex-wrap: wrap; gap: .6rem; }
+.inspector-pager { justify-content: flex-end; margin: 0 0 .75rem; }
+.inspector-pager button, .queue-pager button { color: var(--k-text); background: var(--k-raised); border: 1px solid var(--k-line-strong); border-radius: var(--k-radius-sm); padding: .45rem .7rem; }
+.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; }
@@ -52,6 +56,12 @@
 .source-unavailable { color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
+.queue-controls { padding: 1rem; border-bottom: 1px solid var(--k-line); background: var(--k-panel); }
+.queue-controls label { display: grid; gap: .25rem; color: var(--k-muted); font-size: .75rem; }
+.queue-controls input, .queue-controls select { min-height: 2.25rem; color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); border-radius: var(--k-radius-sm); padding: .4rem .55rem; }
+.queue-result-count { margin-left: auto; color: var(--k-muted); }
+.queue-empty { padding: 2rem; color: var(--k-muted); text-align: center; }
+
 /* Re-assert the base structural tokens for light mode. themes.css's `.theme-*`
    preset classes hardcode a dark --k-bg/--k-panel/etc (so the preset "just
    works" without requiring [data-theme] to be set), and a bare class selector

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,8 +52,8 @@
     "test": "npm run build && node --test dist/tests/*.test.js",
     "test:browser": "playwright test",
     "test:browser:concurrent": "npm run build && node scripts/test-playwright-concurrency.mjs",
-    "verify": "node scripts/check-content-boundary.cjs && 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 scripts/check-content-boundary.cjs",
+    "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",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
     "freeze:adrs": "node scripts/freeze-adrs.mjs",
@@ -79,7 +79,7 @@
     }
   },
   "devDependencies": {
-    "@kontourai/traverse": "^0.19.0",
+    "@kontourai/traverse": "^0.22.0",
     "@kontourai/ui": "^1.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.6.0",