@kontourai/survey 2.0.0 → 2.1.0

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;
 }

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,11 +123,31 @@ 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));
 }
@@ -148,7 +169,7 @@ export function mountExtractionInspector(container, model) {
     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>";
+        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>";
         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("");
     };
@@ -193,6 +214,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "2.0.0",
+  "version": "2.1.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",