@kontourai/survey 1.16.0 → 1.18.0

package/README.md

@@ -103,6 +103,8 @@ One observation, one chain: the page it came from, what the extractor read, who
 
 Keep producer operational state outside Survey. Queue status, reviewer form state, retries, source caches, and product policy decisions belong in the producer's own data model. Survey carries only the portable evidence chain records needed by Surface.
 
+Need Anthropic-backed `MappingProposer`/`UtteranceClaimExtractor` implementations for step 1? `@kontourai/survey/anthropic` ships production adapters as proposers-only — every output still goes through the normal review path. It's a separate subpath (not re-exported from the package root) so consumers without `@anthropic-ai/sdk` installed pay nothing.
+
 When you build an `authorized-action` authorizing block outside the workbench, pair `buildAuthorizedActionAuthorizing` with `buildPromptRef({ module, component, version?, scheme? })` — `buildPromptRef` formats a well-formed, versioned `promptRef` (bare `"review-workbench/decision-card@v1"` or scheme-prefixed `"survey://<module>/<component>@v1"`) that `buildAuthorizedActionAuthorizing` accepts directly, instead of hand-formatting the string.
 
 ## Review lifecycle
@@ -201,12 +203,18 @@ npx survey-review-mcp --session path/to/session.json
 
 Three tools: `survey_review_queue` (queue state), `survey_review_item` (item detail), and `survey_review_decide` (record a decision). Each queue and item call includes an embedded, fully self-contained review card with Accept / Hold / Reject / Could not confirm actions. See [docs/review-mcp.md](docs/review-mcp.md).
 
-At viewports ≤ 980 px, the queue panel becomes a slide-in drawer with a compact progress bar. At narrow container widths, `cqi`-based type scaling keeps candidate values from overflowing at 360 px. CSS custom properties (`--k-*`) inherit through the shadow boundary so the host can theme either mode without forking styles.
+The embedded card is a fixed-size resource (a preferred frame of 420×560) that follows the host's light/dark `prefers-color-scheme`; it does not resize its layout at other breakpoints. For a card that adapts its layout to available width — stacking the current → proposed diff vertically and growing tap targets via CSS container queries below 620px/480px, with a viewport `@media` fallback — embed the [Review Workbench](#review-workbench-embed) directly instead.
 
 Server code persisting browser-submitted review events should use `persistReviewSessionEvents`, then `deriveReviewSessionApplyResultForSnapshot` (or the composed `deriveServerReviewSessionApplyResult` from `@kontourai/survey/review-workbench/server-review-session`) before applying product policy — write results derive from pre-decision snapshots plus persisted events, never from browser-computed decisions.
 
 The [Consumer Integration Guide](docs/consumer-integration-guide.md) covers the full path from `ReviewItem` construction through persisted review events, exported results, Surface projection, and the full `--k-*` theming token list. Test-covered examples are under [`examples/review-workbench/`](examples/review-workbench/). To run the standalone demo locally, see [Review Workbench Prototype](docs/review-workbench-prototype.md).
 
+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
+[Extraction Envelope Import](docs/extraction-envelope-import.md#source-linked-inspection).
+
 
 ## Standalone review console
 

package/dist/src/console/review-console-server.js

@@ -309,7 +309,7 @@ body {
     </button>
   </div>
 </header>
-<main id="review-workbench" class="workbench" data-testid="review-workbench"></main>
+<main id="review-workbench" class="workbench survey-workbench-embed" data-testid="review-workbench"></main>
 <script type="module">
 import { mountReviewWorkbench, replayReviewSessionEvents, defaultReviewSessionName, buildReviewSessionEvents } from "${workbenchJsPath}";
 

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

@@ -0,0 +1,166 @@
+import type { RawSource } from "./types.js";
+import type { ClaimTargetHint, ReviewItem, ReviewValueType } from "./review-resource.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;
+export declare const extractionEnvelopeImportApiVersion = "survey.kontourai.io/v1alpha1";
+export interface PortableExtractionOccurrence {
+    resolverVersion: "exact-occurrence-v1";
+    count: number;
+    selected: {
+        index: number;
+        start: number;
+        end: number;
+    };
+    selection: "source-order" | "occurrence-hint";
+    hintUsed: boolean;
+    ambiguous: boolean;
+}
+export interface PortableExtractionProposal {
+    fieldPath: string;
+    candidateValue: unknown;
+    confidence: number;
+    provenance: {
+        excerpt: string;
+        locator: string;
+        occurrence: PortableExtractionOccurrence;
+    };
+    extractor: string;
+    pathIndices?: number[];
+    inferenceType?: "explicit" | "inferred";
+    valueType?: ReviewValueType;
+    enumValues?: string[];
+}
+export type PortablePreparedArtifactState = {
+    status: "available" | "unavailable" | "storage-error";
+    requestedRef: string;
+    canonicalRef: string;
+} | {
+    status: "identity-mismatch";
+    requestedRef: string;
+    canonicalRef: string;
+} | {
+    status: "invalid-artifact";
+    reason: string;
+    canonicalRef: string;
+} | {
+    status: "digest-mismatch";
+    requestedRef: string;
+    canonicalRef: string;
+    actualDigest: string;
+    actualContentLength: number;
+};
+export interface PortableExtractionResultEnvelope {
+    format: typeof portableExtractionResultFormat;
+    version: typeof portableExtractionResultVersion;
+    source: {
+        ref: string;
+        snapshotRef?: string;
+    };
+    result: {
+        proposals: PortableExtractionProposal[];
+        provider: string;
+        model?: string;
+        runId: string;
+        raw: {
+            tokensUsed?: number;
+        };
+        outcome: {
+            status: "success";
+        } | {
+            status: "partial";
+            reason: "cancelled" | "max-provider-calls" | "max-total-tokens";
+        } | {
+            status: "failure";
+            category: "invalid-config" | "invalid-task" | "preparation" | "provider" | "unexpected";
+            code: string;
+        };
+        warningClassifications?: Array<{
+            category: "provider" | "normalization" | "preparation" | "limit" | "storage" | "content" | "other";
+            code: string;
+        }>;
+        extractedAt: string;
+        providerCalls: number;
+        totalTokensUsed: number;
+        partial?: {
+            reason: "cancelled" | "max-provider-calls" | "max-total-tokens";
+            completedChunks: number;
+            remainingChunks: number;
+            tokenOvershoot?: number;
+        };
+        providerFailures?: Array<{
+            provider: string;
+            kind: "authentication" | "rate-limit" | "timeout" | "invalid-request" | "unavailable" | "unknown";
+            retryable: boolean;
+        }>;
+        taskDigest?: string;
+        exampleDigests?: string[];
+        pdfPageOffsets?: number[];
+        ocrDerived?: true;
+        preparedArtifact?: {
+            format: "traverse-prepared-artifact";
+            version: 1;
+            digest: string;
+            ref: string;
+            preparationMode: string;
+            preparationVersion: string;
+            contentLength: number;
+            sourceSnapshotRef?: string;
+        };
+        preparedArtifactState?: PortablePreparedArtifactState;
+    };
+}
+export interface ExtractionEnvelopeImportOptions {
+    /** Stable Survey import identity. Defaults to the upstream run id. */
+    importName?: string;
+    /** Producer namespace used to avoid cross-producer identity collisions. */
+    producerNamespace?: string;
+    sourceKind: RawSource["kind"];
+    /** Survey meaning is supplied at the boundary; it is not added to the upstream wire contract. */
+    claimTarget: (proposal: PortableExtractionProposal, index: number) => ClaimTargetHint;
+}
+export type ExtractionEnvelopeImportDiagnostic = {
+    kind: "artifact-unavailable";
+    status: "unavailable" | "storage-error" | "identity-mismatch" | "invalid-artifact";
+    artifactRef?: string;
+    message: string;
+} | {
+    kind: "digest-mismatch";
+    artifactRef: string;
+    expectedDigest: string;
+    actualDigest: string;
+    message: string;
+};
+export interface ExtractionEnvelopeImport {
+    apiVersion: typeof extractionEnvelopeImportApiVersion;
+    kind: "ExtractionEnvelopeImport";
+    metadata: {
+        name: string;
+        producerNamespace: string;
+    };
+    spec: {
+        envelope: PortableExtractionResultEnvelope;
+        sourceKind: RawSource["kind"];
+        claimTargets: ClaimTargetHint[];
+    };
+    status: {
+        state: "grounded" | "unresolved";
+        diagnostics: ExtractionEnvelopeImportDiagnostic[];
+    };
+}
+export interface ExtractionEnvelopeImportResult {
+    record: ExtractionEnvelopeImport;
+    reviewItems: ReviewItem[];
+}
+export interface ExtractionEnvelopeResolutionIdentity {
+    evidenceId: string;
+    eventId: string;
+}
+/** Parse an untrusted upstream document and create Survey's durable import projection. */
+export declare function importExtractionEnvelope(serialized: string | PortableExtractionResultEnvelope, options: ExtractionEnvelopeImportOptions): ExtractionEnvelopeImportResult;
+export declare function buildReviewItemsFromExtractionEnvelopeImport(record: ExtractionEnvelopeImport): ReviewItem[];
+export declare function exportExtractionEnvelopeImport(record: ExtractionEnvelopeImport): string;
+export declare function reimportExtractionEnvelope(serialized: string): ExtractionEnvelopeImport;
+export declare function createExtractionEnvelopeResolutionIdentity(record: ExtractionEnvelopeImport, proposalIndex: number): ExtractionEnvelopeResolutionIdentity;
+/** Validate and defensively clone a persisted or browser-delivered import. */
+export declare function validateExtractionEnvelopeImport(value: unknown): ExtractionEnvelopeImport;

package/dist/src/extraction-envelope.js

@@ -0,0 +1,432 @@
+import { sha256Hex } from "./sha256.js";
+import { reviewResourceApiVersion } from "./review-resource.js";
+import { canonicalJson } from "./review-workbench/canonical.js";
+/** The upstream-owned portable extraction-result wire identifiers accepted by this adapter. */
+export const portableExtractionResultFormat = "traverse-extraction-result";
+export const portableExtractionResultVersion = 1;
+export const extractionEnvelopeImportApiVersion = "survey.kontourai.io/v1alpha1";
+/** Parse an untrusted upstream document and create Survey's durable import projection. */
+export function importExtractionEnvelope(serialized, options) {
+    let parsed;
+    if (typeof serialized === "string") {
+        try {
+            parsed = JSON.parse(serialized);
+        }
+        catch {
+            throw new Error("Portable extraction envelope is not valid JSON.");
+        }
+    }
+    else
+        parsed = serialized;
+    const envelope = validateEnvelope(parsed);
+    const claimTargets = envelope.result.proposals.map(options.claimTarget);
+    claimTargets.forEach(validateClaimTarget);
+    const name = options.importName ?? envelope.result.runId;
+    const producerNamespace = options.producerNamespace ?? envelope.result.provider;
+    nonEmpty(name, "Extraction envelope import name");
+    nonEmpty(producerNamespace, "Extraction envelope producer namespace");
+    const diagnostics = diagnosticsFor(envelope);
+    const record = {
+        apiVersion: extractionEnvelopeImportApiVersion,
+        kind: "ExtractionEnvelopeImport",
+        metadata: { name, producerNamespace },
+        spec: { envelope, sourceKind: options.sourceKind, claimTargets: cloneJson(claimTargets) },
+        status: { state: diagnostics.length ? "unresolved" : "grounded", diagnostics },
+    };
+    return { record, reviewItems: buildReviewItemsFromExtractionEnvelopeImport(record) };
+}
+export function buildReviewItemsFromExtractionEnvelopeImport(record) {
+    validateImport(record);
+    if (record.status.state !== "grounded")
+        return [];
+    return record.spec.envelope.result.proposals.map((proposal, index) => buildReviewItem(record, proposal, index));
+}
+export function exportExtractionEnvelopeImport(record) {
+    validateImport(record);
+    return canonicalJson(record);
+}
+export function reimportExtractionEnvelope(serialized) {
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        throw new Error("Extraction envelope import is not valid JSON.");
+    }
+    validateImport(parsed);
+    return cloneJson(parsed);
+}
+export function createExtractionEnvelopeResolutionIdentity(record, proposalIndex) {
+    validateImport(record);
+    if (!Number.isSafeInteger(proposalIndex) || proposalIndex < 0 || proposalIndex >= record.spec.envelope.result.proposals.length) {
+        throw new Error(`Extraction envelope import ${record.metadata.name} has no proposal at index ${proposalIndex}.`);
+    }
+    const base = identityHash(identityInputs(record, record.spec.envelope.result.proposals[proposalIndex], proposalIndex));
+    const nonce = globalThis.crypto.randomUUID();
+    return { evidenceId: `survey.extraction.${base}.resolution-evidence.${nonce}`, eventId: `survey.extraction.${base}.resolution-event.${nonce}` };
+}
+function buildReviewItem(record, proposal, index) {
+    const envelope = record.spec.envelope;
+    const identity = identityHash(identityInputs(record, proposal, index));
+    const evidence = identityHash(evidenceInputs(record, proposal));
+    const target = record.spec.claimTargets[index];
+    const valueType = proposal.valueType ?? inferValueType(proposal.candidateValue);
+    const candidate = {
+        id: `extraction-envelope.${identity}.proposed`, role: "proposed", value: proposal.candidateValue,
+        confidence: proposal.confidence,
+        source: {
+            sourceRef: envelope.source.ref,
+            sourceId: envelope.source.snapshotRef ?? envelope.source.ref,
+            kind: record.spec.sourceKind,
+            observedAt: envelope.result.extractedAt,
+            ...(envelope.result.preparedArtifact?.digest ? { checksum: envelope.result.preparedArtifact.digest } : {}),
+            locatorScheme: "text-span",
+        },
+        locator: { scheme: "text-span", locator: proposal.provenance.locator, excerpt: proposal.provenance.excerpt },
+        extraction: {
+            extractionId: `extraction-envelope.${identity}`,
+            target: proposal.fieldPath,
+            confidence: proposal.confidence,
+            extractor: proposal.extractor,
+            ...(envelope.result.model ? { model: envelope.result.model } : {}),
+        },
+        claimTarget: target,
+        producer: { "survey.kontourai.io/extraction-envelope": {
+                importName: record.metadata.name, proposalIndex: index,
+                evidenceId: `survey.extraction.${evidence}.source-evidence`,
+                runId: envelope.result.runId, provider: envelope.result.provider,
+                ...(envelope.result.model ? { model: envelope.result.model } : {}),
+                ...(envelope.result.taskDigest ? { taskDigest: envelope.result.taskDigest } : {}),
+                ...(envelope.result.exampleDigests ? { exampleDigests: envelope.result.exampleDigests } : {}),
+                valueType: { type: valueType, origin: proposal.inferenceType ?? "inferred" },
+                occurrence: proposal.provenance.occurrence,
+                attempt: { id: envelope.result.runId, providerCalls: envelope.result.providerCalls },
+                ...(envelope.result.warningClassifications ? { warnings: envelope.result.warningClassifications } : {}),
+                outcome: envelope.result.outcome,
+            } },
+    };
+    return {
+        apiVersion: reviewResourceApiVersion, kind: "ReviewItem",
+        metadata: { name: `extraction-envelope.${identity}`, producer: { "survey.kontourai.io/extraction-envelope": {
+                    importName: record.metadata.name,
+                    evidenceId: `survey.extraction.${evidence}.source-evidence`,
+                    source: envelope.source,
+                    ...(envelope.result.preparedArtifact ? { preparedArtifact: envelope.result.preparedArtifact } : {}),
+                } } },
+        spec: { target: proposal.fieldPath, candidates: [candidate], candidateSetStatus: "needs-review", valueDescriptor: { type: valueType }, editable: false },
+        status: { observedCandidateCount: 1 },
+    };
+}
+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,
+        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,
+        extractedAt: record.spec.envelope.result.extractedAt,
+        provenance: proposal.provenance };
+}
+function diagnosticsFor(envelope) {
+    const state = envelope.result.preparedArtifactState;
+    if (!state || state.status === "available")
+        return [];
+    if (state.status === "digest-mismatch")
+        return [{ kind: "digest-mismatch", artifactRef: state.canonicalRef,
+                expectedDigest: envelope.result.preparedArtifact.digest, actualDigest: state.actualDigest,
+                message: "Prepared artifact digest does not match the expected extraction artifact." }];
+    return [{ kind: "artifact-unavailable", status: state.status,
+            ...(state.status === "invalid-artifact" ? { artifactRef: state.canonicalRef } : { artifactRef: state.requestedRef }),
+            message: `Prepared artifact resolution is ${state.status}.` }];
+}
+function validateImport(value) {
+    jsonSafe(value, "Extraction envelope import");
+    const record = obj(value, "Extraction envelope import");
+    exact(record, ["apiVersion", "kind", "metadata", "spec", "status"], "Extraction envelope import");
+    if (record.apiVersion !== extractionEnvelopeImportApiVersion || record.kind !== "ExtractionEnvelopeImport")
+        throw new Error("Invalid extraction envelope import resource identity.");
+    const metadata = obj(record.metadata, "metadata");
+    exact(metadata, ["name", "producerNamespace"], "metadata");
+    nonEmpty(metadata.name, "metadata.name");
+    nonEmpty(metadata.producerNamespace, "metadata.producerNamespace");
+    const spec = obj(record.spec, "spec");
+    exact(spec, ["envelope", "sourceKind", "claimTargets"], "spec");
+    const envelope = validateEnvelope(spec.envelope);
+    if (!RAW_SOURCE_KINDS.has(spec.sourceKind))
+        throw new Error("spec.sourceKind is invalid.");
+    const targets = array(spec.claimTargets, "spec.claimTargets");
+    targets.forEach(validateClaimTarget);
+    if (targets.length !== envelope.result.proposals.length)
+        throw new Error("spec.claimTargets must align with proposals.");
+    const status = obj(record.status, "status");
+    exact(status, ["state", "diagnostics"], "status");
+    const expected = diagnosticsFor(envelope);
+    if (canonicalJson(status.diagnostics) !== canonicalJson(expected) || status.state !== (expected.length ? "unresolved" : "grounded"))
+        throw new Error("Import status does not match envelope state.");
+}
+/** Validate and defensively clone a persisted or browser-delivered import. */
+export function validateExtractionEnvelopeImport(value) {
+    validateImport(value);
+    return cloneJson(value);
+}
+function validateEnvelope(input) {
+    jsonSafe(input, "Portable extraction envelope");
+    const e = obj(input, "envelope");
+    exact(e, ["format", "version", "source", "result"], "envelope");
+    if (e.format !== portableExtractionResultFormat || e.version !== portableExtractionResultVersion)
+        throw new Error("Unsupported portable extraction envelope format or version.");
+    const source = obj(e.source, "source");
+    exact(source, ["ref"], "source", ["snapshotRef"]);
+    safeReference(source.ref, "source.ref");
+    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"]);
+    stableIdentity(r.provider, "result.provider");
+    if (r.model !== undefined)
+        stableIdentity(r.model, "result.model");
+    if (typeof r.runId !== "string" || !RUN_ID.test(r.runId))
+        throw new Error("result.runId is invalid.");
+    wireNonEmpty(r.extractedAt, "result.extractedAt");
+    integer(r.providerCalls, "result.providerCalls");
+    integer(r.totalTokensUsed, "result.totalTokensUsed");
+    const raw = obj(r.raw, "result.raw");
+    exact(raw, [], "result.raw", ["tokensUsed"]);
+    if (raw.tokensUsed !== undefined)
+        integer(raw.tokensUsed, "result.raw.tokensUsed");
+    validateOutcome(r.outcome, r.partial);
+    if (r.warningClassifications !== undefined)
+        array(r.warningClassifications, "warnings").forEach(validateWarning);
+    if (r.providerFailures !== undefined)
+        array(r.providerFailures, "providerFailures").forEach(validateFailure);
+    optionalDigest(r.taskDigest, "result.taskDigest");
+    if (r.exampleDigests !== undefined)
+        array(r.exampleDigests, "exampleDigests").forEach((v) => digest(v, "exampleDigest"));
+    if (r.pdfPageOffsets !== undefined) {
+        const offsets = array(r.pdfPageOffsets, "pdfPageOffsets");
+        offsets.forEach((v) => integer(v, "pageOffset"));
+        if (offsets.some((v, i) => i > 0 && v <= offsets[i - 1]))
+            throw new Error("pdfPageOffsets must ascend strictly.");
+    }
+    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 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 } : {}) } });
+}
+function validateProposal(input, index, contentLength) {
+    const p = obj(input, `proposal[${index}]`);
+    exact(p, ["fieldPath", "candidateValue", "confidence", "provenance", "extractor"], `proposal[${index}]`, ["pathIndices", "inferenceType", "valueType", "enumValues"]);
+    wireNonEmpty(p.fieldPath, "proposal.fieldPath");
+    stableIdentity(p.extractor, "proposal.extractor");
+    finite(p.confidence, "proposal.confidence", 0, 1);
+    const provenance = obj(p.provenance, "proposal.provenance");
+    exact(provenance, ["excerpt", "locator", "occurrence"], "proposal.provenance");
+    wireNonEmpty(provenance.excerpt, "proposal.provenance.excerpt");
+    if (typeof provenance.locator !== "string")
+        throw new Error("proposal locator must be chars:start-end.");
+    const match = /^chars:(0|[1-9]\d*)-(0|[1-9]\d*)$/.exec(provenance.locator);
+    if (!match)
+        throw new Error("proposal locator must be chars:start-end.");
+    const start = Number(match[1]), end = Number(match[2]);
+    if (end < start || end - start !== provenance.excerpt.length || (contentLength !== undefined && end > contentLength))
+        throw new Error("proposal locator/excerpt span is incoherent.");
+    validateOccurrence(provenance.occurrence, start, end);
+    if (p.pathIndices !== undefined)
+        array(p.pathIndices, "pathIndices").forEach((v) => integer(v, "pathIndex"));
+    if (p.inferenceType !== undefined && p.inferenceType !== "explicit" && p.inferenceType !== "inferred")
+        throw new Error("proposal inferenceType is invalid.");
+    if (p.valueType !== undefined && !VALUE_TYPES.has(p.valueType))
+        throw new Error("proposal valueType is invalid.");
+    if (p.enumValues !== undefined)
+        array(p.enumValues, "enumValues").forEach((v) => wellFormedString(v, "enumValue"));
+    return cloneJson(p);
+}
+function validateOccurrence(input, start, end) { const o = obj(input, "occurrence"); exact(o, ["resolverVersion", "count", "selected", "selection", "hintUsed", "ambiguous"], "occurrence"); if (o.resolverVersion !== "exact-occurrence-v1")
+    throw new Error("occurrence resolver version is invalid."); integer(o.count, "occurrence.count"); const s = obj(o.selected, "occurrence.selected"); exact(s, ["index", "start", "end"], "occurrence.selected"); integer(s.index, "selected.index"); integer(s.start, "selected.start"); integer(s.end, "selected.end"); if (s.start !== start || s.end !== end || s.index >= o.count || o.count < 1)
+    throw new Error("occurrence selection is incoherent."); if (o.selection !== "source-order" && o.selection !== "occurrence-hint")
+    throw new Error("occurrence selection is invalid."); if (typeof o.hintUsed !== "boolean" || typeof o.ambiguous !== "boolean")
+    throw new Error("occurrence flags must be booleans."); if (o.hintUsed !== (o.selection === "occurrence-hint"))
+    throw new Error("occurrence hintUsed does not match selection."); if (o.ambiguous !== (o.count > 1))
+    throw new Error("occurrence ambiguous does not match count."); }
+function validateArtifact(input) { const a = obj(input, "preparedArtifact"); exact(a, ["format", "version", "digest", "ref", "preparationMode", "preparationVersion", "contentLength"], "preparedArtifact", ["sourceSnapshotRef"]); if (a.format !== "traverse-prepared-artifact" || a.version !== 1)
+    throw new Error("prepared artifact format is invalid."); digest(a.digest, "artifact.digest", false); if (!PREPARATION_MODES.has(a.preparationMode))
+    throw new Error("artifact.preparationMode is invalid."); nonEmpty(a.preparationVersion, "artifact.preparationVersion"); integer(a.contentLength, "artifact.contentLength"); if (a.sourceSnapshotRef !== undefined)
+    wireNonEmpty(a.sourceSnapshotRef, "artifact.sourceSnapshotRef"); const binding = JSON.stringify({ format: a.format, version: a.version, digest: a.digest, preparationMode: a.preparationMode, preparationVersion: a.preparationVersion, contentLength: a.contentLength, sourceSnapshotRef: a.sourceSnapshotRef ?? null }); const expectedRef = `traverse-prepared-artifact:v1:sha256:${sha256Hex(binding)}`; if (a.ref !== expectedRef)
+    throw new Error("prepared artifact ref does not match its identity binding."); return cloneJson(a); }
+function validateArtifactState(input, artifact) { if (!artifact)
+    throw new Error("prepared artifact state requires prepared artifact."); const s = obj(input, "preparedArtifactState"); const status = s.status; if (status === "digest-mismatch") {
+    exact(s, ["status", "requestedRef", "canonicalRef", "actualDigest", "actualContentLength"], "preparedArtifactState");
+    digest(s.actualDigest, "actualDigest", false);
+    integer(s.actualContentLength, "actualContentLength");
+}
+else if (status === "invalid-artifact") {
+    exact(s, ["status", "reason", "canonicalRef"], "preparedArtifactState");
+    if (!ARTIFACT_INVALID_REASONS.has(s.reason))
+        throw new Error("prepared artifact invalid reason is invalid.");
+}
+else if (["available", "unavailable", "storage-error", "identity-mismatch"].includes(status))
+    exact(s, ["status", "requestedRef", "canonicalRef"], "preparedArtifactState");
+else
+    throw new Error("prepared artifact state is invalid."); preparedReference(s.canonicalRef, "canonicalRef"); if (s.canonicalRef !== artifact.ref)
+    throw new Error("prepared artifact canonical ref mismatch."); if (s.requestedRef !== undefined) {
+    safeReference(s.requestedRef, "requestedRef");
+    if (status !== "identity-mismatch")
+        preparedReference(s.requestedRef, "requestedRef");
+    if (status === "identity-mismatch" ? s.requestedRef === s.canonicalRef : s.requestedRef !== s.canonicalRef)
+        throw new Error(`prepared artifact ${status} requestedRef relationship is invalid.`);
+} return cloneJson(s); }
+function validateOutcome(input, partial) { const o = obj(input, "outcome"); if (o.status === "success")
+    exact(o, ["status"], "outcome");
+else if (o.status === "partial") {
+    exact(o, ["status", "reason"], "outcome");
+    if (!PARTIAL.has(o.reason))
+        throw new Error("partial reason is invalid.");
+    const p = obj(partial, "partial");
+    exact(p, ["reason", "completedChunks", "remainingChunks"], "partial", ["tokenOvershoot"]);
+    if (p.reason !== o.reason)
+        throw new Error("partial reason mismatch.");
+    integer(p.completedChunks, "completedChunks");
+    integer(p.remainingChunks, "remainingChunks");
+    if (p.tokenOvershoot !== undefined) {
+        integer(p.tokenOvershoot, "tokenOvershoot");
+        if (p.tokenOvershoot === 0)
+            throw new Error("tokenOvershoot must be positive.");
+    }
+}
+else if (o.status === "failure") {
+    exact(o, ["status", "category", "code"], "outcome");
+    if (!FAILURE_CATEGORIES.has(o.category))
+        throw new Error("failure category is invalid.");
+    stableIdentity(o.code, "failure code");
+}
+else
+    throw new Error("outcome status is invalid."); if (o.status !== "partial" && partial !== undefined)
+    throw new Error("partial requires partial outcome."); }
+function validateWarning(v) { const w = obj(v, "warning"); exact(w, ["category", "code"], "warning"); if (!WARNING_CATEGORIES.has(w.category))
+    throw new Error("warning category invalid."); stableIdentity(w.code, "warning.code"); }
+function validateFailure(v) { const f = obj(v, "providerFailure"); exact(f, ["provider", "kind", "retryable"], "providerFailure"); stableIdentity(f.provider, "failure.provider"); if (!FAILURE_KINDS.has(f.kind) || typeof f.retryable !== "boolean")
+    throw new Error("provider failure invalid."); }
+function validateClaimTarget(v) { const t = obj(v, "claimTarget"); exact(t, ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior", "impactLevel"], "claimTarget", ["claimId", "evidenceType", "evidenceMethod", "collectedBy", "derivedFrom"]); for (const key of ["subjectType", "subjectId", "facet", "claimType", "fieldOrBehavior"])
+    nonEmpty(t[key], `claimTarget.${key}`); if (!["low", "medium", "high", "critical"].includes(t.impactLevel))
+    throw new Error("claimTarget.impactLevel invalid."); for (const key of ["claimId", "evidenceType", "evidenceMethod", "collectedBy"])
+    optionalString(t[key], `claimTarget.${key}`); if (t.derivedFrom !== undefined)
+    array(t.derivedFrom, "claimTarget.derivedFrom").forEach((entry) => nonEmpty(entry, "claimTarget.derivedFrom entry")); }
+function inferValueType(v) { if (Array.isArray(v))
+    return "array"; if (v === null || typeof v === "object")
+    return "object"; if (["string", "number", "boolean"].includes(typeof v))
+    return typeof v; return "string"; }
+function obj(v, subject) { if (!v || typeof v !== "object" || Array.isArray(v))
+    throw new Error(`${subject} must be an object.`); return v; }
+function array(v, subject) { if (!Array.isArray(v))
+    throw new Error(`${subject} must be an array.`); return v; }
+function exact(v, required, subject, optional = []) { for (const k of required)
+    if (!Object.hasOwn(v, k))
+        throw new Error(`${subject}.${k} is required.`); for (const k of Object.keys(v))
+    if (![...required, ...optional].includes(k))
+        throw new Error(`${subject}.${k} is unexpected.`); }
+function nonEmpty(v, subject) { if (typeof v !== "string" || !v.trim())
+    throw new Error(`${subject} must be a non-empty string.`); }
+function wireNonEmpty(v, subject) { wellFormedString(v, subject); if (v.length === 0)
+    throw new Error(`${subject} must be non-empty.`); }
+function wellFormedString(v, subject) { if (typeof v !== "string" || !isWellFormedUnicode(v))
+    throw new Error(`${subject} must be a well-formed string.`); }
+function optionalString(v, subject) { if (v !== undefined)
+    nonEmpty(v, subject); }
+function finite(v, subject, min, max) { if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max)
+    throw new Error(`${subject} is invalid.`); }
+function integer(v, subject) { if (!Number.isSafeInteger(v) || v < 0)
+    throw new Error(`${subject} must be a non-negative safe integer.`); }
+function digest(v, subject, prefixed = true) { if (typeof v !== "string" || !(prefixed ? /^sha256:[a-f0-9]{64}$/ : /^[a-f0-9]{64}$/).test(v))
+    throw new Error(`${subject} is invalid.`); }
+function optionalDigest(v, subject) { if (v !== undefined)
+    digest(v, subject); }
+function safeReference(v, subject) { wireNonEmpty(v, subject); if (referenceContainsAuthorization(v))
+    throw new Error(`${subject} contains authorization material.`); }
+function referenceContainsAuthorization(value, depth = 0) { if (depth > 2 || /authorization\s*[:=]|bearer\s+[a-z0-9._~-]+/i.test(value))
+    return true; let parsed; try {
+    parsed = new URL(value);
+}
+catch {
+    return false;
+} if (parsed.username || parsed.password)
+    return true; for (const [key, nested] of parsed.searchParams) {
+    if (/(?:^|[-_])(token|secret|password|passwd|api[-_]?key|authorization|signature|credential)(?:$|[-_])/i.test(key) || referenceContainsAuthorization(nested, depth + 1))
+        return true;
+} return false; }
+function stableIdentity(v, subject) { wireNonEmpty(v, subject); if (!STABLE_IDENTITY.test(v) || CREDENTIAL_IDENTITY.test(v) || referenceContainsAuthorization(v))
+    throw new Error(`${subject} must be a credential-free stable identity.`); }
+function preparedReference(v, subject) { safeReference(v, subject); if (!/^traverse-prepared-artifact:v1:sha256:[a-f0-9]{64}$/.test(v))
+    throw new Error(`${subject} must be a prepared-artifact reference.`); }
+function cloneJson(v) { return JSON.parse(JSON.stringify(v)); }
+function identityHash(v) { return sha256Hex(canonicalJson(v)).slice(0, 20); }
+function jsonSafe(v, subject, seen = new Set()) { if (v === null || typeof v === "boolean")
+    return; if (typeof v === "string") {
+    if (!isWellFormedUnicode(v))
+        throw new Error(`${subject} contains ill-formed Unicode.`);
+    return;
+} if (typeof v === "number") {
+    if (!Number.isFinite(v) || Object.is(v, -0))
+        throw new Error(`${subject} contains a non-lossless number.`);
+    return;
+} if (Array.isArray(v)) {
+    if (seen.has(v))
+        throw new Error(`${subject} contains a cycle.`);
+    const keys = Reflect.ownKeys(v);
+    const expected = new Set(["length", ...Array.from({ length: v.length }, (_, index) => String(index))]);
+    for (const key of keys) {
+        if (typeof key === "symbol" || !expected.has(key))
+            throw new Error(`${subject} is sparse or has unexpected array properties.`);
+        const descriptor = Object.getOwnPropertyDescriptor(v, key);
+        if (!descriptor || !("value" in descriptor))
+            throw new Error(`${subject} has an array accessor property.`);
+        if (key !== "length" && !descriptor.enumerable)
+            throw new Error(`${subject} has a non-enumerable array item.`);
+    }
+    if (keys.length !== expected.size)
+        throw new Error(`${subject} contains a sparse array slot.`);
+    seen.add(v);
+    for (let i = 0; i < v.length; i++) {
+        const descriptor = Object.getOwnPropertyDescriptor(v, String(i));
+        jsonSafe(descriptor.value, `${subject}[${i}]`, seen);
+    }
+    seen.delete(v);
+    return;
+} if (typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype)
+    throw new Error(`${subject} contains a non-JSON value.`); if (seen.has(v))
+    throw new Error(`${subject} contains a cycle.`); seen.add(v); for (const key of Reflect.ownKeys(v)) {
+    if (typeof key !== "string")
+        throw new Error(`${subject} contains a symbol key.`);
+    const d = Object.getOwnPropertyDescriptor(v, key);
+    if (!d?.enumerable || !("value" in d) || !isWellFormedUnicode(key))
+        throw new Error(`${subject}.${key} is not a lossless JSON property.`);
+    jsonSafe(d.value, `${subject}.${key}`, seen);
+} seen.delete(v); }
+function isWellFormedUnicode(value) { for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+        if (index + 1 >= value.length)
+            return false;
+        const next = value.charCodeAt(index + 1);
+        if (next < 0xdc00 || next > 0xdfff)
+            return false;
+        index += 1;
+    }
+    else if (unit >= 0xdc00 && unit <= 0xdfff)
+        return false;
+} return true; }
+const RAW_SOURCE_KINDS = new Set(["uploaded-document", "web-page", "api-record", "manual-entry", "policy-standard", "inquiry-question", "agent-utterance", "system-schema"]);
+const VALUE_TYPES = new Set(["string", "number", "boolean", "date", "enum", "array", "object"]);
+const PARTIAL = new Set(["cancelled", "max-provider-calls", "max-total-tokens"]);
+const FAILURE_CATEGORIES = new Set(["invalid-config", "invalid-task", "preparation", "provider", "unexpected"]);
+const WARNING_CATEGORIES = new Set(["provider", "normalization", "preparation", "limit", "storage", "content", "other"]);
+const FAILURE_KINDS = new Set(["authentication", "rate-limit", "timeout", "invalid-request", "unavailable", "unknown"]);
+const PREPARATION_MODES = new Set(["text", "markdown", "transcript", "pdf-text", "image-ocr"]);
+const ARTIFACT_INVALID_REASONS = new Set(["not-an-object", "invalid-format", "invalid-version", "invalid-digest", "invalid-ref", "invalid-preparation-mode", "invalid-preparation-version", "invalid-content-length", "invalid-source-snapshot-ref", "ill-formed-unicode", "invalid-resolved-text"]);
+const STABLE_IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._:@/+~-]{0,255}$/;
+const CREDENTIAL_IDENTITY = /^(?:gh[pousr]_|sk-[A-Za-z0-9]|AKIA[A-Z0-9]|ASIA[A-Z0-9]|eyJ[A-Za-z0-9_-]+\.eyJ)/;
+const RUN_ID = /^traverse-extraction-run:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;

package/dist/src/index.d.ts

@@ -1,6 +1,10 @@
 export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
 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 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";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";

package/dist/src/index.js

@@ -1,5 +1,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 { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";

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

@@ -0,0 +1,77 @@
+import { type ExtractionEnvelopeImportResult } from "../extraction-envelope.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 = {
+    status: "available";
+    text: string;
+    actualDigest: string;
+} | {
+    status: "unavailable";
+    code: ArtifactUnavailableCode;
+} | {
+    status: "digest-mismatch";
+    actualDigest: string;
+};
+export interface ExtractionInspectorEntry {
+    /** Result returned by importExtractionEnvelope; includes authoritative ReviewItem identities. */
+    importResult: ExtractionEnvelopeImportResult;
+    artifact: ResolvedExtractionArtifact;
+    /** Optional producer-declared pass label, kept outside the upstream envelope. */
+    pass?: string;
+}
+export type ExtractionInspectorInput = ExtractionInspectorEntry | {
+    imports: ExtractionInspectorEntry[];
+};
+export interface ExtractionInspectorCandidate {
+    id: string;
+    sourceKey: string;
+    reviewItemName: string;
+    proposalIndex: number;
+    field: string;
+    provider: string;
+    model?: string;
+    attempt: string;
+    pass?: string;
+    valueType: string;
+    inferenceType: "explicit" | "inferred";
+    start: number;
+    end: number;
+    excerpt: string;
+    alignment: ExtractionAlignmentState;
+}
+export interface ExtractionInspectorSource {
+    key: string;
+    importName: string;
+    artifactRef?: string;
+    expectedDigest?: string;
+    actualDigest?: string;
+    artifactText?: string;
+    alignment: ExtractionAlignmentState;
+    message: string;
+}
+export interface ExtractionInspectorModel {
+    sources: ExtractionInspectorSource[];
+    candidates: ExtractionInspectorCandidate[];
+}
+export interface ExtractionInspectorFilters {
+    field?: string;
+    provider?: string;
+    model?: string;
+    attempt?: string;
+    pass?: string;
+    inferenceType?: "explicit" | "inferred";
+    alignment?: ExtractionAlignmentState;
+}
+export interface ExtractionInspectorExportOptions {
+    includePreparedText?: boolean;
+    includeExcerpts?: boolean;
+}
+/**
+ * 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
+ * and fails closed if mutable caller data has drifted since import.
+ */
+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;

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

@@ -0,0 +1,198 @@
+import { buildReviewItemsFromExtractionEnvelopeImport, validateExtractionEnvelopeImport } from "../extraction-envelope.js";
+import { canonicalJson } from "./canonical.js";
+import { sha256Hex } from "../sha256.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
+ * and fails closed if mutable caller data has drifted since import.
+ */
+export function buildExtractionInspectorModel(input) {
+    const entries = "imports" in input ? input.imports : [input];
+    if (!Array.isArray(entries) || entries.length === 0)
+        throw new Error("Extraction inspector requires at least one validated import result.");
+    const sources = [];
+    const candidates = [];
+    const sourceKeys = new Set();
+    for (const [entryIndex, entry] of entries.entries()) {
+        if (!entry.importResult || typeof entry.importResult !== "object")
+            throw new Error("Invalid extraction import result.");
+        const record = validateExtractionEnvelopeImport(entry.importResult.record);
+        assertImportedResult(entry.importResult, record);
+        assertResolvedArtifact(entry.artifact);
+        const envelope = record.spec.envelope;
+        const prepared = envelope.result.preparedArtifact;
+        const sourceKey = `${record.metadata.producerNamespace}:${record.metadata.name}:${entryIndex}`;
+        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);
+        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));
+        });
+        if (source.alignment === "excerpt-mismatch") {
+            delete source.artifactText;
+            for (let index = candidateStart; index < candidates.length; index += 1)
+                candidates[index].alignment = "excerpt-mismatch";
+        }
+    }
+    return { sources, candidates };
+}
+function assertResolvedArtifact(artifact) {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
+        throw new Error("Invalid resolved extraction artifact.");
+    const keys = Object.keys(artifact).sort();
+    if (artifact.status === "available") {
+        if (keys.join(",") !== "actualDigest,status,text" || typeof artifact.text !== "string" || !/^[a-f0-9]{64}$/.test(artifact.actualDigest))
+            throw new Error("Invalid available extraction artifact.");
+    }
+    else if (artifact.status === "digest-mismatch") {
+        if (keys.join(",") !== "actualDigest,status" || !/^[a-f0-9]{64}$/.test(artifact.actualDigest))
+            throw new Error("Invalid digest-mismatch extraction artifact.");
+    }
+    else if (artifact.status === "unavailable") {
+        if (keys.join(",") !== "code,status" || !["not-found", "storage-error", "access-denied", "invalid-artifact", "unknown"].includes(artifact.code))
+            throw new Error("Invalid unavailable extraction artifact.");
+    }
+    else
+        throw new Error("Invalid resolved extraction artifact status.");
+}
+function assertImportedResult(result, record) {
+    if (!result || typeof result !== "object" || !result.record || !Array.isArray(result.reviewItems))
+        throw new Error("Invalid extraction import result.");
+    const { reviewItems } = result;
+    if (record.apiVersion !== "survey.kontourai.io/v1alpha1" || record.kind !== "ExtractionEnvelopeImport")
+        throw new Error("Invalid extraction import resource identity.");
+    if (!record.metadata?.name || !record.metadata.producerNamespace || !record.spec?.envelope?.result || !Array.isArray(record.spec.envelope.result.proposals))
+        throw new Error("Malformed extraction import result.");
+    const grounded = record.status?.state === "grounded";
+    if ((!grounded && reviewItems.length !== 0) || (grounded && reviewItems.length !== record.spec.envelope.result.proposals.length))
+        throw new Error("Extraction import ReviewItems do not match its grounding state.");
+    const canonicalItems = buildReviewItemsFromExtractionEnvelopeImport(record);
+    if (canonicalJson(reviewItems) !== canonicalJson(canonicalItems))
+        throw new Error("Extraction import ReviewItems do not match their canonical identities and bindings.");
+    reviewItems.forEach((item, index) => {
+        const proposal = record.spec.envelope.result.proposals[index];
+        const metadata = item.metadata?.producer?.["survey.kontourai.io/extraction-envelope"];
+        const candidate = item.spec?.candidates?.[0];
+        const binding = candidate?.producer?.["survey.kontourai.io/extraction-envelope"];
+        if (item.kind !== "ReviewItem" || !item.metadata.name || item.spec.candidates.length !== 1
+            || metadata?.importName !== record.metadata.name || binding?.importName !== record.metadata.name
+            || binding.proposalIndex !== index || binding.runId !== record.spec.envelope.result.runId || binding.provider !== record.spec.envelope.result.provider
+            || item.spec.target !== proposal.fieldPath || candidate?.locator?.locator !== proposal.provenance.locator || candidate.locator.excerpt !== proposal.provenance.excerpt) {
+            throw new Error(`Extraction import ReviewItem ${index} is inconsistent with its validated proposal.`);
+        }
+    });
+}
+function sourceModel(key, importName, prepared, state, artifact) {
+    let alignment;
+    let message;
+    if (state !== "grounded" || artifact.status === "unavailable") {
+        alignment = "artifact-unavailable";
+        message = `Prepared artifact unavailable (${artifact.status === "unavailable" ? artifact.code : "invalid-artifact"}). Candidates are not grounded.`;
+    }
+    else if (artifact.status === "digest-mismatch" || !prepared || artifact.actualDigest !== prepared.digest
+        || sha256Hex(artifact.text) !== artifact.actualDigest) {
+        alignment = "digest-mismatch";
+        message = "Prepared artifact digest does not match the extraction artifact. Candidates are not grounded.";
+    }
+    else if (artifact.text.length !== prepared.contentLength) {
+        alignment = "artifact-unavailable";
+        message = "Prepared artifact content has the wrong length. Candidates are not grounded.";
+    }
+    else {
+        alignment = "aligned";
+        message = "Prepared artifact identity verified. Exact source spans are available.";
+    }
+    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 };
+}
+function candidateModel(source, reviewItemName, proposal, index, provider, model, attempt, pass) {
+    const match = /^chars:(\d+)-(\d+)$/.exec(proposal.provenance.locator);
+    if (!match)
+        throw new Error(`Extraction proposal ${index} has an invalid text span.`);
+    const start = Number(match[1]), end = Number(match[2]);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start)
+        throw new Error(`Extraction proposal ${index} has an invalid text span.`);
+    const alignment = source.alignment === "aligned" && source.artifactText.slice(start, end) !== proposal.provenance.excerpt ? "excerpt-mismatch" : source.alignment;
+    if (alignment === "excerpt-mismatch") {
+        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 };
+}
+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"; }
+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));
+}
+export function exportExtractionInspector(model, options = {}) {
+    return canonicalJson({ apiVersion: "survey.kontourai.io/v1alpha1", kind: "ExtractionInspectorExport", spec: {
+            redaction: { preparedTextIncluded: options.includePreparedText === true, excerptsIncluded: options.includeExcerpts === true },
+            sources: model.sources.map(({ artifactText, message: _message, ...source }) => ({ ...source, preparedText: options.includePreparedText ? artifactText ?? null : "[redacted]" })),
+            candidates: model.candidates.map((candidate) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
+        } });
+}
+export function mountExtractionInspector(container, model) {
+    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>`;
+    container.appendChild(root);
+    const list = root.querySelector("ol"), sourcesRoot = root.querySelector(".inspector-sources"), postures = root.querySelector(".inspector-postures");
+    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>";
+        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(); }));
+    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) {
+        event.preventDefault();
+        event.stopPropagation();
+        activateCandidate(candidate.dataset.candidateId);
+        return;
+    } const highlight = event.target.closest("button[data-highlight-candidate-id]"); if (highlight) {
+        event.preventDefault();
+        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 === " ")) {
+        event.preventDefault();
+        event.stopPropagation();
+        activateCandidate(button.dataset.candidateId);
+    } });
+    render();
+    return () => root.remove();
+}
+function renderSource(text, candidates) {
+    const boundaries = new Set([0, text.length]);
+    candidates.forEach(c => { boundaries.add(c.start); boundaries.add(c.end); });
+    const points = [...boundaries].sort((a, b) => a - b);
+    let html = "";
+    const starts = new Map();
+    candidates.forEach(c => starts.set(c.start, [...(starts.get(c.start) ?? []), c]));
+    for (let i = 0; i < points.length - 1; i++) {
+        const start = points[i], end = points[i + 1];
+        for (const c of starts.get(start) ?? [])
+            html += `<button type="button" class="highlight-anchor" id="highlight-${safeId(c.id)}" data-highlight-candidate-id="${escapeHtml(c.id)}" aria-label="Source highlight for ${escapeHtml(c.field)}; activate to return to candidate"></button>`;
+        const segment = escapeHtml(text.slice(start, end));
+        const active = candidates.filter(c => c.start < end && c.end > start);
+        html += active.length ? `<mark aria-label="Highlighted for ${active.map(c => escapeHtml(c.field)).join(", ")}">${segment}</mark>` : segment;
+    }
+    return html;
+}
+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

@@ -187,6 +187,25 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   color: var(--k-text);
 }
 
+/* Read-only evidence pane attached to the existing ReviewItem queue. */
+.survey-workbench-embed .extraction-inspector{ container-type: inline-size; margin-top: 1rem; padding: 1rem; border: 1px solid var(--k-line); border-radius: var(--k-radius); background: var(--k-panel); color: var(--k-text); }
+.survey-workbench-embed .inspector-heading, .survey-workbench-embed .inspector-layout{ display: grid; grid-template-columns: minmax(15rem, .7fr) minmax(0, 1.3fr); gap: 1rem; }
+.survey-workbench-embed .inspector-heading h2{ margin: 0; }
+.survey-workbench-embed .inspector-posture{ display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
+.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-candidates{ margin: 0; padding-left: 1.5rem; }
+.survey-workbench-embed .inspector-candidate{ width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
+.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
+.survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
+.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
+.survey-workbench-embed .highlight-anchor:focus{ outline: 3px solid var(--k-active); }
+.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; } }
+
 /* 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-element.d.ts

@@ -34,6 +34,7 @@
  */
 import { type ReviewQueueSessionState, type ReviewWorkbenchState } from "./review-workbench.js";
 import type { ReviewPresentationAdapter } from "./review-presentation.js";
+import { type ExtractionInspectorInput } from "./extraction-inspector.js";
 export declare class SurveyReviewWorkbenchElement extends HTMLElement {
     #private;
     static readonly observedAttributes: string[];
@@ -44,6 +45,9 @@ export declare class SurveyReviewWorkbenchElement extends HTMLElement {
     /** Optional presentation adapter for custom labels, value summaries, and links. */
     get presentationAdapter(): ReviewPresentationAdapter | undefined;
     set presentationAdapter(value: ReviewPresentationAdapter | undefined);
+    /** Optional read-only source pane attached to this workbench's existing review lifecycle. */
+    get extractionInspector(): ExtractionInspectorInput | null;
+    set extractionInspector(value: ExtractionInspectorInput | null | undefined);
     connectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }

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

@@ -33,6 +33,7 @@
  *   src          — URL to fetch a JSON-serialised ReviewQueueSessionState
  */
 import { mountReviewWorkbench, } from "./review-workbench.js";
+import { buildExtractionInspectorModel, mountExtractionInspector, } from "./extraction-inspector.js";
 import { REVIEW_WORKBENCH_CSS } from "./review-workbench-css.generated.js";
 /** @internal Second adopted stylesheet: host token defaults + inheritance delegation.
  *
@@ -167,6 +168,8 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
     static observedAttributes = ["theme", "color-scheme", "src"];
     #session = null;
     #presentationAdapter = undefined;
+    #extractionInspector = null;
+    #unmountInspector;
     #root;
     #mountRoot;
     #mounted = false;
@@ -285,6 +288,18 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
         this.#mountRoot = document.createElement("div");
         this.#mountRoot.className = "workbench survey-workbench-embed";
         this.#root.appendChild(this.#mountRoot);
+        this.#mountRoot.addEventListener("survey-extraction-candidate-activate", (event) => {
+            if (!this.#session || !("items" in this.#session))
+                return;
+            const detail = event.detail;
+            const item = this.#session.items.find((candidate) => candidate.metadata.name === detail.reviewItemName);
+            if (!item)
+                return;
+            if (this.#session.activeItemName !== item.metadata.name)
+                this.#session = { ...this.#session, activeItemName: item.metadata.name };
+            this.#remount();
+            queueMicrotask(() => this.#root.querySelector(`#highlight-${CSS.escape(detail.candidateId.replace(/[^a-zA-Z0-9_-]/g, "-"))}`)?.focus());
+        });
     }
     /** The review queue session to display. Setting this property re-mounts the workbench. */
     get session() {
@@ -302,6 +317,21 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
         this.#presentationAdapter = value;
         this.#remount();
     }
+    /** Optional read-only source pane attached to this workbench's existing review lifecycle. */
+    get extractionInspector() { return this.#extractionInspector; }
+    set extractionInspector(value) {
+        const next = value ?? null;
+        try {
+            if (next)
+                buildExtractionInspectorModel(next);
+            this.#extractionInspector = next;
+            this.#remount();
+        }
+        catch {
+            this.#extractionInspector = null;
+            this.#renderError("Extraction inspector input is invalid and was not rendered.");
+        }
+    }
     connectedCallback() {
         // Rescue a `session` set before the element was upgraded so the property
         // assignment reaches the class accessor instead of being shadowed by an
@@ -375,6 +405,10 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
             : {};
         this.#applyThemeClasses();
         mountReviewWorkbench(this.#mountRoot, this.#session, options);
+        this.#unmountInspector?.();
+        this.#unmountInspector = this.#extractionInspector
+            ? mountExtractionInspector(this.#mountRoot, buildExtractionInspectorModel(this.#extractionInspector))
+            : undefined;
         this.#mounted = true;
     }
     #renderEmpty() {

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

@@ -184,6 +184,25 @@
   color: var(--k-text);
 }
 
+/* Read-only evidence pane attached to the existing ReviewItem queue. */
+.survey-workbench-embed .extraction-inspector{ container-type: inline-size; margin-top: 1rem; padding: 1rem; border: 1px solid var(--k-line); border-radius: var(--k-radius); background: var(--k-panel); color: var(--k-text); }
+.survey-workbench-embed .inspector-heading, .survey-workbench-embed .inspector-layout{ display: grid; grid-template-columns: minmax(15rem, .7fr) minmax(0, 1.3fr); gap: 1rem; }
+.survey-workbench-embed .inspector-heading h2{ margin: 0; }
+.survey-workbench-embed .inspector-posture{ display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
+.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-candidates{ margin: 0; padding-left: 1.5rem; }
+.survey-workbench-embed .inspector-candidate{ width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
+.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
+.survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
+.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
+.survey-workbench-embed .highlight-anchor:focus{ outline: 3px solid var(--k-active); }
+.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; } }
+
 /* 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,6 +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 { 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";

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

@@ -7,6 +7,7 @@ import { buildReviewCandidatePresentation, buildReviewItemPresentation, } from "
 import { reviewResourceApiVersion, } from "../review-resource.js";
 import { validateAuthorizing, buildAuthorizedActionAuthorizing } from "../review-authorizing.js";
 import { humanizeIdentifier } from "./review-presentation.js";
+export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, } from "./extraction-inspector.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
@@ -26,13 +27,14 @@ export function buildReviewDecision(state) {
         reviewOutcomeId: candidate.projection?.reviewOutcomeId
             ?? `${state.item.metadata.name}:${state.decision}:review-outcome`,
     };
+    const authorizing = buildDecisionCardAuthorizing(state);
     const reviewDecision = {
         apiVersion: reviewResourceApiVersion,
         kind: "ReviewDecision",
         metadata: {
             name: `${state.item.metadata.name}-${state.decision}`,
-            labels: state.item.metadata.labels,
-            producer: state.item.metadata.producer,
+            ...(state.item.metadata.labels ? { labels: state.item.metadata.labels } : {}),
+            ...(state.item.metadata.producer ? { producer: state.item.metadata.producer } : {}),
         },
         spec: {
             reviewItemName: state.item.metadata.name,
@@ -50,12 +52,14 @@ export function buildReviewDecision(state) {
             },
             reviewedAt: state.reviewedAt,
             rationale: state.note,
-            authorizing: buildDecisionCardAuthorizing(state),
-            projection,
-            editedValue: state.decision === "accept-proposed" ? state.editedValue : undefined,
+            ...(authorizing !== undefined ? { authorizing } : {}),
+            ...(projection !== undefined ? { projection } : {}),
+            ...(state.decision === "accept-proposed" && state.editedValue !== undefined
+                ? { editedValue: state.editedValue }
+                : {}),
         },
         status: {
-            appliedToClaimIds: candidate.projection?.claimId ? [candidate.projection.claimId] : undefined,
+            ...(candidate.projection?.claimId ? { appliedToClaimIds: [candidate.projection.claimId] } : {}),
         },
     };
     assertReviewResolutionConsistency(`ReviewDecision ${reviewDecision.metadata.name}`, {

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

@@ -33,6 +33,25 @@
   color: var(--k-text);
 }
 
+/* Read-only evidence pane attached to the existing ReviewItem queue. */
+.extraction-inspector { container-type: inline-size; margin-top: 1rem; padding: 1rem; border: 1px solid var(--k-line); border-radius: var(--k-radius); background: var(--k-panel); color: var(--k-text); }
+.inspector-heading, .inspector-layout { display: grid; grid-template-columns: minmax(15rem, .7fr) minmax(0, 1.3fr); gap: 1rem; }
+.inspector-heading h2 { margin: 0; }
+.inspector-posture { display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
+.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-candidates { margin: 0; padding-left: 1.5rem; }
+.inspector-candidate { width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
+.inspector-source pre { white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.inspector-source mark { background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
+.inspector-candidate:focus { outline: 3px solid var(--k-active); outline-offset: 2px; }
+.highlight-anchor { display: inline-block; width: 1px; height: 1em; }
+.highlight-anchor:focus { outline: 3px solid var(--k-active); }
+.source-unavailable { color: var(--k-negative); font-weight: 700; }
+@container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
+
 /* 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/sha256.d.ts

@@ -0,0 +1,2 @@
+/** Dependency-free synchronous SHA-256 for browser and Node parity. */
+export declare function sha256Hex(text: string): string;

package/dist/src/sha256.js

@@ -0,0 +1,40 @@
+/** Dependency-free synchronous SHA-256 for browser and Node parity. */
+export function sha256Hex(text) {
+    const bytes = new TextEncoder().encode(text), bitLength = bytes.length * 8, length = Math.ceil((bytes.length + 9) / 64) * 64, data = new Uint8Array(length);
+    data.set(bytes);
+    data[bytes.length] = 0x80;
+    const view = new DataView(data.buffer);
+    view.setUint32(length - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(length - 4, bitLength >>> 0);
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const k = new Uint32Array([0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2]), w = new Uint32Array(64), rotr = (v, n) => (v >>> n) | (v << (32 - n));
+    for (let offset = 0; offset < length; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const x = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3), y = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + x + w[i - 7] + y) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, z] = h;
+        for (let i = 0; i < 64; i++) {
+            const x = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25), ch = (e & f) ^ (~e & g), t1 = (z + x + ch + k[i] + w[i]) >>> 0, s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22), maj = (a & b) ^ (a & c) ^ (b & c), t2 = (s0 + maj) >>> 0;
+            z = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + z) >>> 0;
+    }
+    return [...h].map(v => v.toString(16).padStart(8, "0")).join("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -87,6 +87,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.54.0",
+    "@kontourai/traverse": "^0.19.0",
     "@kontourai/ui": "^1.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.6.0",