@kontourai/survey 1.18.1 → 2.0.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-improvement-proposal.d.ts

@@ -0,0 +1,148 @@
+import { type ExtractionEnvelopeImport } from "./extraction-envelope.js";
+import { type ReviewDecision, type ReviewItem } from "./review-resource.js";
+import type { ReviewOutcome, SurveyInput } from "./types.js";
+/** Portable reference to a producer-owned task. Survey never copies its executable schema. */
+export interface ExtractionTaskSpecReference {
+    version: string;
+    digest: string;
+    exampleDigests: string[];
+}
+export interface ExtractionImprovementRecordDigests {
+    extractionImport: string;
+    reviewItem: string;
+    reviewDecision: string;
+    reviewOutcome: string;
+}
+/** Canonical projection derived from validated Survey records and their joins. */
+export interface ExtractionImprovementLineage {
+    taskSpec: ExtractionTaskSpecReference;
+    extractionImportName: string;
+    extractionId: string;
+    proposalId: string;
+    reviewItemName: string;
+    reviewDecisionName: string;
+    reviewOutcomeId: string;
+    sourceSnapshotRef: string;
+    preparedArtifact: {
+        ref: string;
+        digest: string;
+    };
+    excerptLocator: string;
+    recordDigests: ExtractionImprovementRecordDigests;
+}
+export interface BadExtractionDiagnosis {
+    kind: "bad-extraction";
+    requestedTaskChanges: Array<"example-addition" | "guidance-update">;
+}
+export interface AcceptedExtractionDiagnosis {
+    kind: "accepted-extraction";
+    requestedTaskChanges: Array<"grounded-positive-example" | "guidance-affirmation">;
+}
+export interface InsufficientSourceEvidenceDiagnosis {
+    kind: "insufficient-source-evidence";
+    sourceRemediation: "obtain-authoritative-source" | "refresh-source-snapshot" | "expand-source-scope";
+}
+/** Caller-supplied diagnosis; Survey never infers it from rationale prose. */
+export type ExtractionImprovementDiagnosis = BadExtractionDiagnosis | AcceptedExtractionDiagnosis | InsufficientSourceEvidenceDiagnosis;
+export interface ExtractionImprovementReview {
+    resolution: "accepted" | "rejected" | "could_not_confirm";
+    status: ReviewOutcome["status"];
+    reviewedAt: string;
+    rationale: string;
+    evidenceIds: string[];
+    attemptEvidenceIds: string[];
+}
+export interface ExtractionImprovementDraft {
+    id: string;
+    kind: "survey.extraction-improvement-proposal";
+    schemaVersion: 1;
+    state: "draft";
+    createdAt: string;
+    lineage: ExtractionImprovementLineage;
+    diagnosis: ExtractionImprovementDiagnosis;
+    review: ExtractionImprovementReview;
+}
+export interface BuildExtractionImprovementProposalInput {
+    createdAt: string;
+    /** Version label paired with the task digest carried by the canonical import. */
+    priorTaskSpecVersion: string;
+    extractionImport: ExtractionEnvelopeImport;
+    proposalIndex: number;
+    reviewItem: ReviewItem;
+    reviewDecision: ReviewDecision;
+    survey: SurveyInput;
+    reviewOutcomeId: string;
+    diagnosis: ExtractionImprovementDiagnosis;
+}
+export interface ProducerApproval {
+    id: string;
+    actor: string;
+    approvedAt: string;
+    rationale: string;
+    evidenceIds: string[];
+}
+/** Data-only request; the task owner must validate, store, and activate it. */
+export interface ExtractionImprovementActivationRequest {
+    id: string;
+    dispositionKey: string;
+    kind: "survey.extraction-improvement-activation-request";
+    schemaVersion: 1;
+    state: "approved";
+    draftId: string;
+    approval: ProducerApproval;
+    nextTaskSpec: ExtractionTaskSpecReference;
+    rollbackTaskSpec: ExtractionTaskSpecReference;
+    guidanceChangeProofDigest?: string;
+}
+export interface ApproveExtractionImprovementProposalInput {
+    draft: ExtractionImprovementDraft;
+    approval: ProducerApproval;
+    nextTaskSpec: ExtractionTaskSpecReference;
+    rollbackTaskSpec: ExtractionTaskSpecReference;
+    /** Required when the explicit remedy updates or affirms guidance. */
+    guidanceChangeProofDigest?: string;
+}
+export interface ExtractionImprovementRejection {
+    id: string;
+    dispositionKey: string;
+    kind: "survey.extraction-improvement-rejection";
+    schemaVersion: 1;
+    state: "rejected";
+    draftId: string;
+    rejection: {
+        id: string;
+        actor: string;
+        rejectedAt: string;
+        rationale: string;
+        evidenceIds: string[];
+    };
+}
+export interface RejectExtractionImprovementProposalInput {
+    draft: ExtractionImprovementDraft;
+    rejection: ExtractionImprovementRejection["rejection"];
+}
+/** 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. */
+export declare function approveExtractionImprovementProposal(input: ApproveExtractionImprovementProposalInput): ExtractionImprovementActivationRequest;
+/** Emits an idempotent terminal rejection with the same disposition key as approval. */
+export declare function rejectExtractionImprovementProposal(input: RejectExtractionImprovementProposalInput): ExtractionImprovementRejection;