@kontourai/survey 1.19.0 → 2.1.0

package/README.md

@@ -103,7 +103,7 @@ 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.
+Model-backed producers implement `MappingProposer` or `UtteranceClaimExtractor` in the product that owns the prompt, parsing, runtime policy, and domain mapping. Survey accepts their normalized proposals through the same framework-neutral interfaces and review path; it does not acquire credentials or depend on an AI runtime.
 
 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.
 

package/dist/src/agent-utterance.js

@@ -22,17 +22,16 @@ import { projectProposalsToCandidateSet } from "./producer-profile.js";
 /**
  * The Candidate Conflict comparison key for an utterance-proposed value.
  *
- * Neither extractor (the reference extractor below, nor the Anthropic-backed
- * one in `./anthropic.js`) normalizes `value` before it reaches
+ * Extractors do not normalize `value` before it reaches
  * `ExtractedStatement` — case and internal formatting are preserved
  * verbatim. String values are the only case where "representation noise"
  * (leading/trailing whitespace from excerpt boundaries, incidental case
- * differences like "Healthy" vs "healthy") is plausible given the two
- * extractors' actual output, so this key trims + lowercases STRING values
+ * differences like "Healthy" vs "healthy") is plausible in producer output,
+ * so this key trims + lowercases STRING values
  * in the COMPARISON KEY ONLY — the stored `Candidate.value`/`Extraction.value`
  * stay byte-for-byte verbatim; this function only feeds `equivalenceKey`,
  * never `value`. Non-string values (number, boolean, null — the other types
- * the Anthropic tool schema permits) compare via exact canonical
+ * supported by the portable record contract) compare via exact canonical
  * `JSON.stringify`, so there is no cross-type coercion that could silently
  * equate e.g. "5" and 5, or lose a genuine numeric disagreement (5 vs 6 is
  * never noise). This mirrors the Producer Profile core's established

package/dist/src/canonical-reviewed-trust-input.d.ts

@@ -0,0 +1,31 @@
+import type { SurveyInput } from "./types.js";
+import type { ReviewItem } from "./review-resource.js";
+import type { ReviewWorkbenchResult } from "./review-workbench/review-workbench.js";
+export interface BuildCanonicalReviewedTrustInputOptions {
+    /** Producer identity for the resulting SurveyInput batch. */
+    readonly source: string;
+    /** Server-controlled projection time. */
+    readonly generatedAt: string;
+    /** Stable producer-owned identity for this review projection. */
+    readonly projectionContextId: string;
+    /** Canonical ReviewItems from the server-owned pre-decision snapshot. */
+    readonly items: readonly ReviewItem[];
+    /** Results derived by Survey's server apply boundary from snapshot + events. */
+    readonly results: readonly ReviewWorkbenchResult[];
+}
+export interface CanonicalReviewedTrustInput {
+    readonly surveyInput: SurveyInput;
+    /** Pass unchanged to buildSurveyTrustBundle's projectionContextId option. */
+    readonly projectionContextId: string;
+}
+/**
+ * Projects server-applied review records into the complete SurveyInput consumed
+ * by buildSurveyTrustBundle. The ReviewItem and ReviewWorkbenchResult are the
+ * authority: callers cannot override status, value, identity, or provenance.
+ *
+ * The helper deliberately returns the projection context beside SurveyInput
+ * because repeated append-only projections need that context at the Surface
+ * projection boundary, while SurveyInput's existing byte shape remains
+ * unchanged for compatibility.
+ */
+export declare function buildCanonicalReviewedTrustInput(options: BuildCanonicalReviewedTrustInputOptions): CanonicalReviewedTrustInput;

package/dist/src/canonical-reviewed-trust-input.js

@@ -0,0 +1,265 @@
+import { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
+import { canonicalJson } from "./review-workbench/canonical.js";
+import { workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
+/**
+ * Projects server-applied review records into the complete SurveyInput consumed
+ * by buildSurveyTrustBundle. The ReviewItem and ReviewWorkbenchResult are the
+ * authority: callers cannot override status, value, identity, or provenance.
+ *
+ * The helper deliberately returns the projection context beside SurveyInput
+ * because repeated append-only projections need that context at the Surface
+ * projection boundary, while SurveyInput's existing byte shape remains
+ * unchanged for compatibility.
+ */
+export function buildCanonicalReviewedTrustInput(options) {
+    requireNonEmpty(options.source, "source");
+    requireTimestamp(options.generatedAt, "generatedAt");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(options.projectionContextId)) {
+        throw new Error("projectionContextId must be a non-empty portable resource-name fragment.");
+    }
+    const itemsByName = uniqueBy(options.items, (item) => item.metadata.name, "ReviewItem");
+    const resultsByName = uniqueBy(options.results, (result) => result.reviewItemName, "ReviewWorkbenchResult");
+    if (itemsByName.size !== resultsByName.size) {
+        throw new Error("Canonical review projection requires exactly one resolved result for every ReviewItem.");
+    }
+    const rawSources = new Map();
+    const extractions = new Map();
+    const candidateSets = new Map();
+    const reviewOutcomes = new Map();
+    const claims = new Map();
+    for (const item of options.items) {
+        const result = resultsByName.get(item.metadata.name);
+        if (!result) {
+            throw new Error(`ReviewItem ${item.metadata.name} has no canonical server-applied result.`);
+        }
+        assertCanonicalResult(item, result);
+        const candidates = item.spec.candidates.map((candidate) => {
+            const records = projectCandidate(item, candidate);
+            addConsistent(rawSources, records.rawSource, "raw source");
+            addConsistent(extractions, records.extraction, "extraction");
+            return records.candidate;
+        });
+        const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+        const selectedRecordId = selected.projection?.candidateId ?? selected.id;
+        const candidateSetId = selected.projection?.candidateSetId
+            ?? item.spec.projection?.candidateSetId
+            ?? `${item.metadata.name}.candidates`;
+        if (candidates.some((candidate) => candidate.metadata?.candidateSetId !== candidateSetId)) {
+            throw new Error(`ReviewItem ${item.metadata.name} carries conflicting candidate-set projection ids.`);
+        }
+        const candidateSet = {
+            id: candidateSetId,
+            target: item.spec.target,
+            candidates: candidates.map(({ metadata, ...candidate }) => ({
+                ...candidate,
+                ...(metadata && Object.keys(metadata).length > 1
+                    ? { metadata: Object.fromEntries(Object.entries(metadata).filter(([key]) => key !== "candidateSetId")) }
+                    : {}),
+            })),
+            selectedCandidateId: selectedRecordId,
+            status: result.decision === "could-not-confirm"
+                ? (item.spec.candidateSetStatus ?? "needs-review")
+                : "resolved",
+            ...(result.rationale ?? item.spec.rationale
+                ? { rationale: result.rationale ?? item.spec.rationale }
+                : {}),
+        };
+        addConsistent(candidateSets, candidateSet, "candidate set");
+        const decision = result.reviewDecision.spec;
+        const reviewOutcomeId = decision.projection?.reviewOutcomeId
+            ?? selected.projection?.reviewOutcomeId
+            ?? `${item.metadata.name}.${result.decision}.review-outcome`;
+        const reviewOutcome = {
+            id: reviewOutcomeId,
+            candidateSetId,
+            candidateId: selectedRecordId,
+            status: result.status,
+            ...(decision.resolution ? { resolution: decision.resolution } : {}),
+            ...(decision.resolutionReason ? { resolutionReason: decision.resolutionReason } : {}),
+            ...(decision.attemptEvidenceIds?.length ? { attemptEvidenceIds: [...decision.attemptEvidenceIds] } : {}),
+            ...(decision.actor?.id ? { actor: decision.actor.id } : {}),
+            ...(decision.reviewedAt ? { reviewedAt: decision.reviewedAt } : {}),
+            ...(decision.rationale ? { rationale: decision.rationale } : {}),
+            ...(decision.evidenceIds?.length ? { evidenceIds: [...decision.evidenceIds] } : {}),
+            ...(decision.withinComfortZone !== undefined ? { withinComfortZone: decision.withinComfortZone } : {}),
+            ...(decision.comfortZoneNote ? { comfortZoneNote: decision.comfortZoneNote } : {}),
+            ...(decision.authorizing ? { authorizing: decision.authorizing } : {}),
+            metadata: {
+                workbenchDecision: result.decision,
+                ...(result.editedValue !== undefined ? { editedValue: result.editedValue } : {}),
+            },
+        };
+        addConsistent(reviewOutcomes, reviewOutcome, "review outcome");
+        const hint = selected.claimTarget;
+        assertSingleProjectionId("claim", item.metadata.name, [
+            decision.projection?.claimId,
+            item.spec.projection?.claimId,
+            ...item.spec.candidates.flatMap((candidate) => [candidate.projection?.claimId, candidate.claimTarget.claimId]),
+        ]);
+        const claimId = decision.projection?.claimId
+            ?? selected.projection?.claimId
+            ?? item.spec.projection?.claimId
+            ?? hint.claimId
+            ?? `${item.metadata.name}.claim`;
+        const claim = {
+            id: claimId,
+            candidateSetId,
+            candidateId: selectedRecordId,
+            subjectType: hint.subjectType,
+            subjectId: hint.subjectId,
+            facet: hint.facet,
+            claimType: hint.claimType,
+            fieldOrBehavior: hint.fieldOrBehavior,
+            value: result.effectiveValue,
+            status: result.status,
+            impactLevel: hint.impactLevel,
+            updatedAt: decision.reviewedAt ?? options.generatedAt,
+            ...(hint.evidenceType ? { evidenceType: hint.evidenceType } : {}),
+            ...(hint.evidenceMethod ? { evidenceMethod: hint.evidenceMethod } : {}),
+            ...(hint.derivedFrom ? { derivedFrom: [...hint.derivedFrom] } : {}),
+            collectedBy: hint.collectedBy ?? selected.extraction.extractor ?? options.source,
+            ...(decision.actor?.id ? { actor: decision.actor.id } : {}),
+        };
+        addConsistent(claims, claim, "claim target");
+    }
+    return {
+        projectionContextId: options.projectionContextId,
+        surveyInput: {
+            contractVersion: SURVEY_INPUT_CONTRACT_VERSION,
+            source: options.source,
+            generatedAt: options.generatedAt,
+            rawSources: [...rawSources.values()],
+            extractions: [...extractions.values()],
+            candidateSets: [...candidateSets.values()],
+            reviewOutcomes: [...reviewOutcomes.values()],
+            claims: [...claims.values()],
+        },
+    };
+}
+function assertCanonicalResult(item, result) {
+    const selected = item.spec.candidates.find((candidate) => candidate.id === result.selectedCandidateId);
+    if (!selected) {
+        throw new Error(`Review result ${result.reviewItemName} selects an unknown candidate.`);
+    }
+    if (canonicalJson(selected) !== canonicalJson(result.selectedCandidate)) {
+        throw new Error(`Review result ${result.reviewItemName} selected candidate does not match its canonical ReviewItem.`);
+    }
+    const unselected = item.spec.candidates.filter((candidate) => candidate.id !== selected.id);
+    if (canonicalJson(unselected) !== canonicalJson(result.unselectedCandidates)) {
+        throw new Error(`Review result ${result.reviewItemName} unselected candidates do not match its canonical ReviewItem.`);
+    }
+    if (result.selectedCandidateRole !== selected.role || canonicalJson(result.selectedValue) !== canonicalJson(selected.value)) {
+        throw new Error(`Review result ${result.reviewItemName} selected identity does not match its canonical ReviewItem.`);
+    }
+    const decision = result.reviewDecision.spec;
+    const definition = workbenchDecisionDefinitions[result.decision];
+    if (decision.reviewItemName !== item.metadata.name
+        || decision.candidateId !== result.selectedCandidateId
+        || decision.status !== result.status
+        || decision.status !== definition.status
+        || decision.rationale !== result.rationale
+        || canonicalJson(decision.editedValue) !== canonicalJson(result.editedValue)) {
+        throw new Error(`Review result ${result.reviewItemName} contradicts its canonical ReviewDecision.`);
+    }
+    if ((result.decision === "could-not-confirm") !== (decision.resolution === "could_not_confirm")) {
+        throw new Error(`Review result ${result.reviewItemName} contradicts its canonical review resolution.`);
+    }
+    const expectedEffective = result.editedValue !== undefined && result.decision === "accept-proposed"
+        ? result.editedValue
+        : selected.value;
+    if (canonicalJson(expectedEffective) !== canonicalJson(result.effectiveValue)) {
+        throw new Error(`Review result ${result.reviewItemName} effective value is not canonical.`);
+    }
+    for (const candidate of item.spec.candidates) {
+        if (canonicalJson(claimTargetIdentity(candidate.claimTarget)) !== canonicalJson(claimTargetIdentity(selected.claimTarget))) {
+            throw new Error(`ReviewItem ${item.metadata.name} candidates carry conflicting claim targets.`);
+        }
+    }
+}
+function claimTargetIdentity(target) {
+    const { claimId: _claimId, ...identity } = target;
+    return identity;
+}
+function projectCandidate(item, input) {
+    const rawSourceId = input.projection?.rawSourceId ?? input.source.sourceId ?? `${item.metadata.name}.${input.id}.source`;
+    const extractionId = input.projection?.extractionId ?? input.extraction.extractionId ?? `${item.metadata.name}.${input.id}.extraction`;
+    const candidateSetId = input.projection?.candidateSetId ?? item.spec.projection?.candidateSetId ?? `${item.metadata.name}.candidates`;
+    const sourceKind = input.source.kind;
+    const observedAt = input.source.observedAt;
+    const locatorScheme = input.source.locatorScheme ?? input.locator?.scheme;
+    const extractor = input.extraction.extractor;
+    const extractedAt = input.extraction.extractedAt;
+    if (!sourceKind || !observedAt || !locatorScheme || !extractor || !extractedAt) {
+        throw new Error(`ReviewCandidate ${input.id} lacks source or extraction provenance required for TrustInput projection.`);
+    }
+    const rawSource = {
+        id: rawSourceId,
+        kind: sourceKind,
+        sourceRef: input.source.sourceRef,
+        observedAt,
+        ...(input.source.fetchedAt ? { fetchedAt: input.source.fetchedAt } : {}),
+        ...(input.source.checksum ? { checksum: input.source.checksum } : {}),
+        locatorScheme,
+    };
+    const extraction = {
+        id: extractionId,
+        sourceId: rawSourceId,
+        target: input.extraction.target,
+        value: input.value,
+        ...(input.extraction.confidence ?? input.confidence) !== undefined
+            ? { confidence: input.extraction.confidence ?? input.confidence }
+            : {},
+        ...(input.locator?.locator ? { locator: input.locator.locator } : {}),
+        ...(input.locator?.excerpt ? { excerpt: input.locator.excerpt } : {}),
+        extractor,
+        extractedAt,
+        ...(input.extraction.model ? { metadata: { model: input.extraction.model } } : {}),
+    };
+    const candidate = {
+        id: input.projection?.candidateId ?? input.id,
+        extractionId,
+        value: input.value,
+        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),
+        ...(input.sourceRank !== undefined ? { sourceRank: input.sourceRank } : {}),
+        ...(input.rejectionReason ? { rejectionReason: input.rejectionReason } : {}),
+        metadata: {
+            candidateSetId,
+            ...(input.role ? { role: input.role } : {}),
+            ...(input.producer ? { producer: input.producer } : {}),
+        },
+    };
+    return { rawSource, extraction, candidate };
+}
+function uniqueBy(values, id, label) {
+    const output = new Map();
+    for (const value of values) {
+        const key = requireNonEmpty(id(value), `${label} identity`);
+        if (output.has(key)) {
+            throw new Error(`Canonical review projection received duplicate ${label} ${key}.`);
+        }
+        output.set(key, value);
+    }
+    return output;
+}
+function addConsistent(records, value, label) {
+    const existing = records.get(value.id);
+    if (existing && canonicalJson(existing) !== canonicalJson(value)) {
+        throw new Error(`Canonical review projection found conflicting ${label} ${value.id}.`);
+    }
+    records.set(value.id, value);
+}
+function requireNonEmpty(value, label) {
+    if (!value.trim())
+        throw new Error(`${label} must be non-empty.`);
+    return value;
+}
+function requireTimestamp(value, label) {
+    if (!value.trim() || Number.isNaN(Date.parse(value)))
+        throw new Error(`${label} must be an ISO timestamp.`);
+}
+function assertSingleProjectionId(label, itemName, values) {
+    const ids = new Set(values.filter((value) => value !== undefined));
+    if (ids.size > 1) {
+        throw new Error(`ReviewItem ${itemName} carries conflicting ${label} projection ids.`);
+    }
+}

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/extraction-improvement-proposal.d.ts

@@ -123,6 +123,23 @@ export interface RejectExtractionImprovementProposalInput {
 }
 /** One producer/store disposition is allowed for each shared dispositionKey. */
 export type ExtractionImprovementDisposition = ExtractionImprovementActivationRequest | ExtractionImprovementRejection;
+export interface ExtractionImprovementDispositionConflict {
+    kind: "survey.extraction-improvement-disposition-conflict";
+    dispositionKey: string;
+    /** Canonically ordered distinct records. The fold never selects a winner. */
+    dispositions: readonly ExtractionImprovementDisposition[];
+}
+export interface FoldExtractionImprovementDispositionsResult {
+    /** One canonically ordered record for each uncontested disposition key. */
+    dispositions: readonly ExtractionImprovementDisposition[];
+    /** Canonically ordered conflicts for keys with more than one distinct record. */
+    conflicts: readonly ExtractionImprovementDispositionConflict[];
+}
+/**
+ * Folds producer-owned disposition records without performing I/O or selecting
+ * between conflicting decisions. Byte-equivalent replay is idempotent.
+ */
+export declare function foldExtractionImprovementDispositions(input: readonly ExtractionImprovementDisposition[]): FoldExtractionImprovementDispositionsResult;
 /** Builds a frozen draft from validated canonical records. Performs no I/O. */
 export declare function buildExtractionImprovementProposal(input: BuildExtractionImprovementProposalInput): ExtractionImprovementDraft;
 /** Emits a reversible activation request, never an activation. */

package/dist/src/extraction-improvement-proposal.js

@@ -2,6 +2,39 @@ import { createHash } from "node:crypto";
 import { buildReviewItemsFromExtractionEnvelopeImport } from "./extraction-envelope.js";
 import { reviewResourceApiVersion } from "./review-resource.js";
 import { canonicalJson } from "./review-workbench/canonical.js";
+/**
+ * Folds producer-owned disposition records without performing I/O or selecting
+ * between conflicting decisions. Byte-equivalent replay is idempotent.
+ */
+export function foldExtractionImprovementDispositions(input) {
+    const byKey = new Map();
+    for (const disposition of input) {
+        const records = byKey.get(disposition.dispositionKey) ?? new Map();
+        records.set(canonicalJson(disposition), disposition);
+        byKey.set(disposition.dispositionKey, records);
+    }
+    const dispositions = [];
+    const conflicts = [];
+    for (const dispositionKey of [...byKey.keys()].sort()) {
+        const records = [...byKey.get(dispositionKey).entries()]
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([, disposition]) => disposition);
+        if (records.length === 1) {
+            dispositions.push(records[0]);
+        }
+        else {
+            conflicts.push(Object.freeze({
+                kind: "survey.extraction-improvement-disposition-conflict",
+                dispositionKey,
+                dispositions: Object.freeze(records),
+            }));
+        }
+    }
+    return Object.freeze({
+        dispositions: Object.freeze(dispositions),
+        conflicts: Object.freeze(conflicts),
+    });
+}
 /** Builds a frozen draft from validated canonical records. Performs no I/O. */
 export function buildExtractionImprovementProposal(input) {
     const diagnosis = normalizeDiagnosis(input.diagnosis);

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";
@@ -14,12 +16,14 @@ export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-r
 export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-resolution.js";
 export { buildSurveyTrustBundle } from "./to-surface.js";
 export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
+export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
+export type { BuildCanonicalReviewedTrustInputOptions, CanonicalReviewedTrustInput, } from "./canonical-reviewed-trust-input.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export type { LearningProjection, LearningProjectionKind, LearningProjectionSeverity, LearningProjectionSignal, } from "./learning-projections.js";
 export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
 export type { LearningUpdateEvidenceReference, LearningUpdateProposal, OpaqueEvidenceReference, ProvenanceReference, ReviewedLearningUpdateProposalInput, ReviewProofReference, } from "./learning-update-proposal.js";
-export { approveExtractionImprovementProposal, buildExtractionImprovementProposal, rejectExtractionImprovementProposal, } from "./extraction-improvement-proposal.js";
-export type { ApproveExtractionImprovementProposalInput, AcceptedExtractionDiagnosis, BadExtractionDiagnosis, BuildExtractionImprovementProposalInput, ExtractionImprovementActivationRequest, ExtractionImprovementDiagnosis, ExtractionImprovementDisposition, ExtractionImprovementDraft, ExtractionImprovementLineage, ExtractionImprovementRejection, ExtractionImprovementRecordDigests, ExtractionImprovementReview, ExtractionTaskSpecReference, InsufficientSourceEvidenceDiagnosis, ProducerApproval, RejectExtractionImprovementProposalInput, } from "./extraction-improvement-proposal.js";
+export { approveExtractionImprovementProposal, buildExtractionImprovementProposal, foldExtractionImprovementDispositions, rejectExtractionImprovementProposal, } from "./extraction-improvement-proposal.js";
+export type { ApproveExtractionImprovementProposalInput, AcceptedExtractionDiagnosis, BadExtractionDiagnosis, BuildExtractionImprovementProposalInput, ExtractionImprovementActivationRequest, ExtractionImprovementDiagnosis, ExtractionImprovementDisposition, ExtractionImprovementDispositionConflict, ExtractionImprovementDraft, ExtractionImprovementLineage, ExtractionImprovementRejection, ExtractionImprovementRecordDigests, ExtractionImprovementReview, ExtractionTaskSpecReference, FoldExtractionImprovementDispositionsResult, InsufficientSourceEvidenceDiagnosis, ProducerApproval, RejectExtractionImprovementProposalInput, } from "./extraction-improvement-proposal.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
 export type { CanonicalReviewProofPayload, CanonicalReviewProofPayloadV1, CanonicalReviewProofPayloadV2, ReviewProofInput, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";

package/dist/src/index.js

@@ -2,13 +2,15 @@ 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";
 export { buildSurveyTrustBundle } from "./to-surface.js";
+export { buildCanonicalReviewedTrustInput } from "./canonical-reviewed-trust-input.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export { buildReviewedLearningUpdateProposal } from "./learning-update-proposal.js";
-export { approveExtractionImprovementProposal, buildExtractionImprovementProposal, rejectExtractionImprovementProposal, } from "./extraction-improvement-proposal.js";
+export { approveExtractionImprovementProposal, buildExtractionImprovementProposal, foldExtractionImprovementDispositions, rejectExtractionImprovementProposal, } from "./extraction-improvement-proposal.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.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;