@kontourai/survey 1.18.1 → 2.0.0

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

@@ -0,0 +1,396 @@
+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);
+    const lineage = projectValidatedLineage(input);
+    const review = projectValidatedReview(input, diagnosis, lineage.proposalId);
+    const outcome = exactlyOne(input.survey.reviewOutcomes, ({ id }) => id === input.reviewOutcomeId, "review outcome");
+    lineage.recordDigests.reviewOutcome = recordDigest("ReviewOutcome", outcome);
+    const payload = {
+        kind: "survey.extraction-improvement-proposal",
+        schemaVersion: 1,
+        state: "draft",
+        createdAt: canonicalTimestamp(input.createdAt, "createdAt"),
+        lineage,
+        diagnosis,
+        review,
+    };
+    return freeze({ id: digest("survey.extraction-improvement-proposal/v1", payload), ...payload });
+}
+/** Emits a reversible activation request, never an activation. */
+export function approveExtractionImprovementProposal(input) {
+    assertDraftIntegrity(input.draft);
+    if (input.draft.diagnosis.kind === "insufficient-source-evidence") {
+        throw new Error("insufficient-source-evidence proposals cannot request a task-spec change");
+    }
+    const approval = normalizeApproval(input.approval);
+    const nextTaskSpec = normalizeTaskSpecReference(input.nextTaskSpec, "nextTaskSpec");
+    const rollbackTaskSpec = normalizeTaskSpecReference(input.rollbackTaskSpec, "rollbackTaskSpec");
+    if (nextTaskSpec.version === input.draft.lineage.taskSpec.version || nextTaskSpec.digest === input.draft.lineage.taskSpec.digest) {
+        throw new Error("nextTaskSpec must be a new version with a new digest");
+    }
+    if (canonicalJson(rollbackTaskSpec) !== canonicalJson(input.draft.lineage.taskSpec)) {
+        throw new Error("rollbackTaskSpec must exactly identify the draft's prior task spec");
+    }
+    const changes = input.draft.diagnosis.requestedTaskChanges;
+    const addsExample = changes.includes("example-addition") || changes.includes("grounded-positive-example");
+    const changesGuidance = changes.includes("guidance-update") || changes.includes("guidance-affirmation");
+    assertExampleDigestChange(input.draft.lineage.taskSpec.exampleDigests, nextTaskSpec.exampleDigests, addsExample);
+    const guidanceChangeProofDigest = input.guidanceChangeProofDigest === undefined
+        ? undefined
+        : sha256Digest(input.guidanceChangeProofDigest, "guidanceChangeProofDigest");
+    if (changesGuidance && guidanceChangeProofDigest === undefined) {
+        throw new Error("guidance changes require guidanceChangeProofDigest");
+    }
+    if (!changesGuidance && guidanceChangeProofDigest !== undefined) {
+        throw new Error("guidanceChangeProofDigest is not allowed without a guidance remedy");
+    }
+    const dispositionKey = dispositionKeyFor(input.draft.id);
+    const payload = {
+        dispositionKey,
+        kind: "survey.extraction-improvement-activation-request",
+        schemaVersion: 1,
+        state: "approved",
+        draftId: input.draft.id,
+        approval,
+        nextTaskSpec,
+        rollbackTaskSpec,
+        ...(guidanceChangeProofDigest ? { guidanceChangeProofDigest } : {}),
+    };
+    return freeze({ id: digest("survey.extraction-improvement-activation-request/v1", payload), ...payload });
+}
+/** Emits an idempotent terminal rejection with the same disposition key as approval. */
+export function rejectExtractionImprovementProposal(input) {
+    assertDraftIntegrity(input.draft);
+    const rejection = normalizeRejection(input.rejection);
+    const payload = {
+        dispositionKey: dispositionKeyFor(input.draft.id),
+        kind: "survey.extraction-improvement-rejection",
+        schemaVersion: 1,
+        state: "rejected",
+        draftId: input.draft.id,
+        rejection,
+    };
+    return freeze({ id: digest("survey.extraction-improvement-rejection/v1", payload), ...payload });
+}
+function projectValidatedLineage(input) {
+    const canonicalItems = buildReviewItemsFromExtractionEnvelopeImport(input.extractionImport);
+    if (!Number.isSafeInteger(input.proposalIndex) || input.proposalIndex < 0 || input.proposalIndex >= canonicalItems.length) {
+        throw new Error("proposalIndex does not identify a grounded extraction proposal");
+    }
+    const canonicalItem = canonicalItems[input.proposalIndex];
+    if (canonicalJson(canonicalItem) !== canonicalJson(input.reviewItem)) {
+        throw new Error("reviewItem is not the canonical projection of extractionImport and proposalIndex");
+    }
+    const envelope = input.extractionImport.spec.envelope;
+    const proposal = envelope.result.proposals[input.proposalIndex];
+    const artifact = envelope.result.preparedArtifact;
+    if (!envelope.result.taskDigest || !artifact || !envelope.source.snapshotRef) {
+        throw new Error("extraction improvement requires task, prepared-artifact, and source-snapshot grounding");
+    }
+    const candidate = exactlyOne(input.reviewItem.spec.candidates, () => true, "review candidate");
+    if (!candidate.extraction.extractionId)
+        throw new Error("canonical review candidate requires an extraction id");
+    return {
+        taskSpec: normalizeTaskSpecReference({
+            version: nonEmpty(input.priorTaskSpecVersion, "priorTaskSpecVersion"),
+            digest: envelope.result.taskDigest,
+            exampleDigests: envelope.result.exampleDigests ?? [],
+        }, "lineage.taskSpec"),
+        extractionImportName: input.extractionImport.metadata.name,
+        extractionId: candidate.extraction.extractionId,
+        proposalId: candidate.id,
+        reviewItemName: input.reviewItem.metadata.name,
+        reviewDecisionName: validateReviewDecision(input.reviewDecision, input.reviewItem),
+        reviewOutcomeId: nonEmpty(input.reviewOutcomeId, "reviewOutcomeId"),
+        sourceSnapshotRef: envelope.source.snapshotRef,
+        preparedArtifact: { ref: artifact.ref, digest: rawSha256Digest(artifact.digest, "preparedArtifact.digest") },
+        excerptLocator: nonEmpty(proposal.provenance.locator, "proposal.provenance.locator"),
+        recordDigests: {
+            extractionImport: recordDigest("ExtractionEnvelopeImport", input.extractionImport),
+            reviewItem: recordDigest("ReviewItem", input.reviewItem),
+            reviewDecision: recordDigest("ReviewDecision", input.reviewDecision),
+            reviewOutcome: "",
+        },
+    };
+}
+function projectValidatedReview(input, diagnosis, proposalId) {
+    const outcome = exactlyOne(input.survey.reviewOutcomes, ({ id }) => id === input.reviewOutcomeId, "review outcome");
+    const decision = input.reviewDecision;
+    const projection = decision.spec.projection;
+    if (!projection || projection.reviewOutcomeId !== outcome.id || projection.candidateSetId !== outcome.candidateSetId) {
+        throw new Error("reviewDecision projection must identify the concrete Survey review outcome and candidate set");
+    }
+    if (decision.spec.candidateId !== outcome.candidateId || projection.candidateId !== outcome.candidateId) {
+        throw new Error("reviewDecision and reviewOutcome candidate lineage do not match");
+    }
+    if (outcome.candidateId !== undefined && outcome.candidateId !== proposalId) {
+        throw new Error("any identified review candidate must be the canonical imported proposal");
+    }
+    assertDecisionOutcomeField(decision.spec.status, outcome.status, "status");
+    assertDecisionOutcomeField(decision.spec.resolution, outcome.resolution, "resolution");
+    assertDecisionOutcomeField(decision.spec.resolutionReason, outcome.resolutionReason, "resolutionReason");
+    assertDecisionOutcomeField(decision.spec.actor?.id, outcome.actor, "actor");
+    assertDecisionOutcomeField(decision.spec.reviewedAt, outcome.reviewedAt, "reviewedAt");
+    assertDecisionOutcomeField(decision.spec.rationale, outcome.rationale, "rationale");
+    assertSetEqual(decision.spec.evidenceIds ?? [], outcome.evidenceIds ?? [], "evidenceIds");
+    assertSetEqual(decision.spec.attemptEvidenceIds ?? [], outcome.attemptEvidenceIds ?? [], "attemptEvidenceIds");
+    assertDiagnosisReview(diagnosis, outcome);
+    const review = {
+        resolution: outcome.resolution,
+        status: outcome.status,
+        reviewedAt: canonicalTimestamp(outcome.reviewedAt, "reviewOutcome.reviewedAt"),
+        rationale: nonEmpty(outcome.rationale ?? outcome.resolutionReason, "review rationale"),
+        evidenceIds: sortedUnique(outcome.evidenceIds ?? [], "review.evidenceIds", nonEmpty),
+        attemptEvidenceIds: sortedUnique(outcome.attemptEvidenceIds ?? [], "review.attemptEvidenceIds", nonEmpty),
+    };
+    return review;
+}
+function validateReviewDecision(decision, item) {
+    if (!decision || decision.apiVersion !== reviewResourceApiVersion || decision.kind !== "ReviewDecision") {
+        throw new Error("reviewDecision must be a canonical ReviewDecision resource");
+    }
+    if (decision.spec.reviewItemName !== item.metadata.name)
+        throw new Error("reviewDecision does not join to reviewItem");
+    return nonEmpty(decision.metadata.name, "reviewDecision.metadata.name");
+}
+function assertDiagnosisReview(diagnosis, outcome) {
+    if (diagnosis.kind === "accepted-extraction") {
+        if (outcome.resolution !== "accepted" || (outcome.status !== "verified" && outcome.status !== "assumed")) {
+            throw new Error("accepted-extraction requires an accepted verified or assumed review outcome");
+        }
+    }
+    else if (diagnosis.kind === "bad-extraction") {
+        if (outcome.resolution !== "rejected" || outcome.status !== "rejected") {
+            throw new Error("bad-extraction requires an explicit rejected review outcome");
+        }
+    }
+    else if (outcome.resolution !== "could_not_confirm") {
+        throw new Error("insufficient-source-evidence requires an explicit could_not_confirm review outcome");
+    }
+}
+function normalizeDiagnosis(value) {
+    const diagnosis = requiredObject(value, "diagnosis");
+    if (diagnosis.kind === "bad-extraction") {
+        const requestedTaskChanges = normalizeChanges(diagnosis.requestedTaskChanges, "diagnosis.requestedTaskChanges", ["example-addition", "guidance-update"]);
+        return { kind: "bad-extraction", requestedTaskChanges };
+    }
+    if (diagnosis.kind === "accepted-extraction") {
+        const requestedTaskChanges = normalizeChanges(diagnosis.requestedTaskChanges, "diagnosis.requestedTaskChanges", ["grounded-positive-example", "guidance-affirmation"]);
+        return { kind: "accepted-extraction", requestedTaskChanges };
+    }
+    if (diagnosis.kind === "insufficient-source-evidence") {
+        const sourceRemediation = diagnosis.sourceRemediation;
+        if (sourceRemediation !== "obtain-authoritative-source" && sourceRemediation !== "refresh-source-snapshot" && sourceRemediation !== "expand-source-scope") {
+            throw new Error("insufficient-source-evidence requires an explicit source remediation");
+        }
+        return { kind: "insufficient-source-evidence", sourceRemediation };
+    }
+    throw new Error("diagnosis.kind must be explicit");
+}
+function normalizeChanges(value, label, allowed) {
+    const changes = sortedUnique(value, label, (change, field) => {
+        if (typeof change !== "string" || !allowed.includes(change))
+            throw new Error(`${field} contains an unsupported task change`);
+        return change;
+    });
+    if (changes.length === 0)
+        throw new Error(`${label} requires at least one explicit task change`);
+    return changes;
+}
+function assertExampleDigestChange(prior, next, addsExample) {
+    const priorSet = new Set(prior);
+    const nextSet = new Set(next);
+    const strictSuperset = prior.every((value) => nextSet.has(value)) && next.length > prior.length;
+    if (addsExample && !strictSuperset)
+        throw new Error("example remedy requires next example digests to be a strict superset");
+    if (!addsExample && canonicalJson(prior) !== canonicalJson(next))
+        throw new Error("next example digests changed without an example remedy");
+}
+function assertDraftIntegrity(draft) {
+    if (!draft || draft.kind !== "survey.extraction-improvement-proposal" || draft.schemaVersion !== 1 || draft.state !== "draft") {
+        throw new Error("disposition requires a draft extraction improvement proposal");
+    }
+    const normalizedDiagnosis = normalizeDiagnosis(draft.diagnosis);
+    if (canonicalJson(normalizedDiagnosis) !== canonicalJson(draft.diagnosis))
+        throw new Error("draft diagnosis is not canonical");
+    const normalizedTask = normalizeTaskSpecReference(draft.lineage.taskSpec, "draft.lineage.taskSpec");
+    if (canonicalJson(normalizedTask) !== canonicalJson(draft.lineage.taskSpec))
+        throw new Error("draft task reference is not canonical");
+    for (const [field, value] of Object.entries(draft.lineage.recordDigests))
+        sha256Digest(value, `draft.lineage.recordDigests.${field}`);
+    rawSha256Digest(draft.lineage.preparedArtifact.digest, "draft.lineage.preparedArtifact.digest");
+    nonEmpty(draft.lineage.preparedArtifact.ref, "draft.lineage.preparedArtifact.ref");
+    for (const [field, value] of Object.entries({
+        extractionImportName: draft.lineage.extractionImportName,
+        extractionId: draft.lineage.extractionId,
+        proposalId: draft.lineage.proposalId,
+        reviewItemName: draft.lineage.reviewItemName,
+        reviewDecisionName: draft.lineage.reviewDecisionName,
+        reviewOutcomeId: draft.lineage.reviewOutcomeId,
+        sourceSnapshotRef: draft.lineage.sourceSnapshotRef,
+        excerptLocator: draft.lineage.excerptLocator,
+    }))
+        nonEmpty(value, `draft.lineage.${field}`);
+    canonicalTimestamp(draft.createdAt, "draft.createdAt");
+    canonicalTimestamp(draft.review.reviewedAt, "draft.review.reviewedAt");
+    nonEmpty(draft.review.rationale, "draft.review.rationale");
+    const evidenceIds = sortedUnique(draft.review.evidenceIds, "draft.review.evidenceIds", nonEmpty);
+    const attemptEvidenceIds = sortedUnique(draft.review.attemptEvidenceIds, "draft.review.attemptEvidenceIds", nonEmpty);
+    if (canonicalJson(evidenceIds) !== canonicalJson(draft.review.evidenceIds)
+        || canonicalJson(attemptEvidenceIds) !== canonicalJson(draft.review.attemptEvidenceIds)) {
+        throw new Error("draft review evidence is not canonical");
+    }
+    assertDraftDiagnosisReview(draft.diagnosis, draft.review);
+    const { id, ...payload } = draft;
+    if (id !== digest("survey.extraction-improvement-proposal/v1", payload)) {
+        throw new Error("extraction improvement draft does not match its immutable identity");
+    }
+}
+function assertDraftDiagnosisReview(diagnosis, review) {
+    if (diagnosis.kind === "accepted-extraction") {
+        if (review.resolution !== "accepted" || (review.status !== "verified" && review.status !== "assumed")) {
+            throw new Error("draft accepted-extraction review is inconsistent");
+        }
+    }
+    else if (diagnosis.kind === "bad-extraction") {
+        if (review.resolution !== "rejected" || review.status !== "rejected")
+            throw new Error("draft bad-extraction review is inconsistent");
+    }
+    else if (review.resolution !== "could_not_confirm") {
+        throw new Error("draft insufficient-source-evidence review is inconsistent");
+    }
+}
+function normalizeTaskSpecReference(value, label) {
+    const task = requiredObject(value, label);
+    return {
+        version: nonEmpty(task.version, `${label}.version`),
+        digest: sha256Digest(task.digest, `${label}.digest`),
+        exampleDigests: sortedUnique(task.exampleDigests, `${label}.exampleDigests`, sha256Digest),
+    };
+}
+function normalizeApproval(value) {
+    const approval = requiredObject(value, "approval");
+    return {
+        id: nonEmpty(approval.id, "approval.id"), actor: nonEmpty(approval.actor, "approval.actor"),
+        approvedAt: canonicalTimestamp(approval.approvedAt, "approval.approvedAt"),
+        rationale: nonEmpty(approval.rationale, "approval.rationale"),
+        evidenceIds: sortedUnique(approval.evidenceIds, "approval.evidenceIds", nonEmpty),
+    };
+}
+function normalizeRejection(value) {
+    const rejection = requiredObject(value, "rejection");
+    return {
+        id: nonEmpty(rejection.id, "rejection.id"), actor: nonEmpty(rejection.actor, "rejection.actor"),
+        rejectedAt: canonicalTimestamp(rejection.rejectedAt, "rejection.rejectedAt"),
+        rationale: nonEmpty(rejection.rationale, "rejection.rationale"),
+        evidenceIds: sortedUnique(rejection.evidenceIds, "rejection.evidenceIds", nonEmpty),
+    };
+}
+function dispositionKeyFor(draftId) {
+    return digest("survey.extraction-improvement-disposition/v1", { draftId });
+}
+function recordDigest(kind, value) {
+    return digest("survey.extraction-improvement-record/v1", { kind, value });
+}
+function assertDecisionOutcomeField(left, right, label) {
+    if (canonicalJson(left ?? null) !== canonicalJson(right ?? null))
+        throw new Error(`reviewDecision and reviewOutcome ${label} do not match`);
+}
+function assertSetEqual(left, right, label) {
+    const a = sortedUnique(left, `reviewDecision.${label}`, nonEmpty);
+    const b = sortedUnique(right, `reviewOutcome.${label}`, nonEmpty);
+    if (canonicalJson(a) !== canonicalJson(b))
+        throw new Error(`reviewDecision and reviewOutcome ${label} do not match`);
+}
+function exactlyOne(records, predicate, label) {
+    const matches = records.filter(predicate);
+    if (matches.length !== 1)
+        throw new Error(`extraction improvement requires exactly one ${label}; found ${matches.length}`);
+    return matches[0];
+}
+function requiredObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} must be a non-empty string`);
+    return value;
+}
+function sha256Digest(value, label) {
+    const digestValue = nonEmpty(value, label);
+    if (!/^sha256:[a-f0-9]{64}$/.test(digestValue))
+        throw new Error(`${label} must be a sha256 digest`);
+    return digestValue;
+}
+function rawSha256Digest(value, label) {
+    const digestValue = nonEmpty(value, label);
+    if (!/^[a-f0-9]{64}$/.test(digestValue))
+        throw new Error(`${label} must be an unprefixed sha256 digest`);
+    return digestValue;
+}
+function canonicalTimestamp(value, label) {
+    const timestamp = nonEmpty(value, label);
+    const parsed = new Date(timestamp);
+    if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== timestamp)
+        throw new Error(`${label} must be a canonical ISO timestamp`);
+    return timestamp;
+}
+function sortedUnique(values, label, normalize) {
+    if (!Array.isArray(values))
+        throw new Error(`${label} must be an array`);
+    const keyed = values.map((value, index) => normalize(value, `${label}[${index}]`))
+        .map((value) => [canonicalJson(value), value]).sort(([left], [right]) => left.localeCompare(right));
+    if (keyed.some(([value], index) => index > 0 && keyed[index - 1][0] === value))
+        throw new Error(`${label} must not contain duplicate values`);
+    return keyed.map(([, value]) => value);
+}
+function digest(domain, payload) {
+    return `sha256:${createHash("sha256").update(canonicalJson({ domain, payload })).digest("hex")}`;
+}
+function freeze(value) {
+    if (value && typeof value === "object") {
+        for (const nested of Object.values(value))
+            freeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/src/index.d.ts

@@ -14,10 +14,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, 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

@@ -6,8 +6,10 @@ export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from
 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, 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/to-surface.d.ts

@@ -18,6 +18,17 @@ export interface SurveyCalibrationOptions {
 }
 export interface BuildSurveyTrustBundleOptions {
     reviewProofs?: boolean;
+    /**
+     * Caller-owned identity for one projection or resolution context, such as a
+     * review-session, proposal, or append-only persistence record id. When set,
+     * Survey folds it into generated Evidence and VerificationEvent ids so
+     * repeated projections of the same Claim cannot collide. Claim ids and all
+     * legacy output remain unchanged when omitted.
+     *
+     * Use a portable resource-name fragment: ASCII letters, digits, `.`, `_`,
+     * `:`, or `-`, beginning with a letter or digit.
+     */
+    projectionContextId?: string;
     /**
      * Populate `conclusionConfidence.value` from empirical review calibration —
      * "how often this extractor's proposals at this confidence were affirmed by a

package/dist/src/to-surface.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { buildReviewProofAnchor } from "./review-proof.js";
 import { assertReviewOutcomeDiscipline } from "./producer-discipline.js";
 import { deriveCalibration } from "./calibration.js";
@@ -5,6 +6,7 @@ import { deriveCalibration } from "./calibration.js";
  *  accuracy is emitted as a `conclusionConfidence.value`. */
 const DEFAULT_CALIBRATION_MIN_SAMPLES = 20;
 export function buildSurveyTrustBundle(input, options = {}) {
+    const projectionContextId = validateProjectionContextId(options.projectionContextId);
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
     const candidateSets = indexById(input.candidateSets, "candidate set");
@@ -37,7 +39,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
         const claimValue = projection.value ?? candidate.value;
         const createdAt = projection.createdAt ?? extraction.extractedAt;
         const updatedAt = projection.updatedAt ?? projectionReview?.reviewedAt ?? input.generatedAt;
-        const evidenceId = `${projection.id}.evidence.source`;
+        const evidenceId = projectionRecordId(projection.id, projectionContextId, "claim-evidence", "evidence.source");
         const claim = {
             id: projection.id,
             subjectType: projection.subjectType,
@@ -147,7 +149,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
         });
         const rationale = projectionReview?.rationale ?? candidateSet.rationale;
         events.push({
-            id: `${projection.id}.event.${status}`,
+            id: projectionRecordId(projection.id, projectionContextId, "claim-event", `event.${status}`),
             claimId: projection.id,
             status,
             actor: projection.actor ?? projectionReview?.actor ?? projection.collectedBy,
@@ -158,7 +160,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
             notes: rationale,
         });
     }
-    projectInterpretations({ input, rawSources, claims, evidence, events });
+    projectInterpretations({ input, rawSources, claims, evidence, events, projectionContextId });
     if (input.escalations) {
         const claimIds = new Set(claims.map((c) => c.id));
         for (const escalation of input.escalations) {
@@ -170,7 +172,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
                 throw new Error(`Escalation ${escalation.id} references unknown claim ${escalation.attachToClaimId}`);
             }
             events.push({
-                id: `${escalation.id}.event`,
+                id: projectionRecordId(escalation.id, projectionContextId, "escalation-event", "event"),
                 claimId: escalation.attachToClaimId,
                 status: "disputed",
                 actor: escalation.raisedBy,
@@ -190,6 +192,22 @@ export function buildSurveyTrustBundle(input, options = {}) {
         events,
     };
 }
+function validateProjectionContextId(contextId) {
+    if (contextId === undefined)
+        return undefined;
+    if (typeof contextId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(contextId)) {
+        throw new Error("projectionContextId must be a non-empty portable resource-name fragment");
+    }
+    return contextId;
+}
+function projectionRecordId(ownerId, contextId, recordKind, legacySuffix) {
+    if (!contextId)
+        return `${ownerId}.${legacySuffix}`;
+    const digest = createHash("sha256")
+        .update(JSON.stringify(["survey-projection-context-v1", recordKind, ownerId, contextId]))
+        .digest("hex");
+    return `survey.projection.v1.${digest}.${legacySuffix}`;
+}
 function projectInterpretations(input) {
     const interpretations = input.input.interpretations
         ? [...indexById(input.input.interpretations, "interpretation").values()]
@@ -204,6 +222,7 @@ function projectInterpretations(input) {
             claims: input.claims,
             claimsById,
             input: input.input,
+            projectionContextId: input.projectionContextId,
         });
         input.evidence.push(projection.evidence);
         input.events.push(projection.event);
@@ -227,6 +246,7 @@ function buildInterpretationProjection(input) {
         claim,
         anchorSource,
         policyStandard,
+        projectionContextId: input.projectionContextId,
     });
     return {
         claim,
@@ -236,6 +256,7 @@ function buildInterpretationProjection(input) {
             interpretation: input.interpretation,
             claim,
             evidenceId: evidence.id,
+            projectionContextId: input.projectionContextId,
         }),
     };
 }
@@ -248,7 +269,7 @@ function requirePolicyStandardAnchor(interpretation, rawSources) {
 }
 function createInterpretationAnchorEvidence(input) {
     return {
-        id: `${input.interpretation.id}.evidence.anchor`,
+        id: projectionRecordId(input.interpretation.id, input.projectionContextId, "interpretation-evidence", "evidence.anchor"),
         claimId: input.claim.id,
         evidenceType: "policy_rule",
         method: "anchoring",
@@ -271,7 +292,7 @@ function createInterpretationAnchorEvidence(input) {
 }
 function createInterpretationEvent(input) {
     return {
-        id: `${input.interpretation.id}.event`,
+        id: projectionRecordId(input.interpretation.id, input.projectionContextId, "interpretation-event", "event"),
         claimId: input.claim.id,
         status: input.claim.status ?? "proposed",
         actor: input.interpretation.actor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.18.1",
+  "version": "2.0.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,10 +18,6 @@
   },
   "exports": {
     ".": "./dist/src/index.js",
-    "./anthropic": {
-      "types": "./dist/src/anthropic.d.ts",
-      "default": "./dist/src/anthropic.js"
-    },
     "./review-workbench": {
       "types": "./dist/src/review-workbench/review-workbench.d.ts",
       "default": "./dist/src/review-workbench/review-workbench.js"
@@ -55,7 +51,8 @@
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
     "test:browser": "playwright test",
-    "verify": "node scripts/check-content-boundary.cjs && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser",
+    "test:browser:concurrent": "npm run build && node scripts/test-playwright-concurrency.mjs",
+    "verify": "node scripts/check-content-boundary.cjs && npm run check:decisions && npm run typecheck && npm test && npm run check:review-workbench-assets && npm run check:review-workbench && npm run test:browser && npm run test:browser:concurrent",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
     "check:decisions": "node scripts/check-decisions.cjs check",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
@@ -74,19 +71,14 @@
     "@kontourai/surface": "^2.9.0"
   },
   "peerDependencies": {
-    "@anthropic-ai/sdk": ">=0.20.0",
     "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
-    "@anthropic-ai/sdk": {
-      "optional": true
-    },
     "typescript": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.54.0",
     "@kontourai/traverse": "^0.19.0",
     "@kontourai/ui": "^1.1.0",
     "@playwright/test": "^1.60.0",