@kontourai/survey 0.4.24 → 0.5.0

package/dist/src/anthropic.js

@@ -0,0 +1,383 @@
+/**
+ * Anthropic production adapters for Survey's pluggable interfaces.
+ *
+ * ADR 0003 §4 compliance: these implementations are PROPOSERS only. Every
+ * output is a proposal (MappingProposal / ExtractedStatement) that goes
+ * through the existing review/auto-accept machinery before counting.
+ * Nothing here bypasses review.
+ *
+ * Subpath export: import from "@kontourai/survey/anthropic" — this module is
+ * NOT re-exported from the main index.ts so consumers without @anthropic-ai/sdk
+ * pay nothing.
+ *
+ * Injected client: both factories accept an optional pre-built client so tests
+ * can inject a fake without hitting the network. If no client is provided, one
+ * is constructed from opts.apiKey (falling back to process.env.ANTHROPIC_API_KEY).
+ */
+const DEFAULT_MODEL = "claude-sonnet-4-6";
+/**
+ * Build or return a messages client from options.
+ * Dynamic-imports @anthropic-ai/sdk only when no client is injected,
+ * keeping the optional peer dep out of the eager module graph.
+ */
+async function resolveClient(opts) {
+    if (opts.client)
+        return opts.client;
+    // Dynamically load the SDK — only reachable when no client is injected.
+    // Uses a variable module specifier so TypeScript does not try to resolve
+    // the optional peer dep at compile time. At runtime the SDK must be installed.
+    const sdkModule = "@anthropic-ai/sdk";
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const sdkImport = await Function("m", "return import(m)")(sdkModule);
+    const { default: Anthropic } = sdkImport;
+    const apiKey = opts.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+    if (!apiKey) {
+        throw new Error("AnthropicAdapter: no API key. Provide opts.apiKey, set ANTHROPIC_API_KEY, or inject opts.client.");
+    }
+    const sdk = new Anthropic({ apiKey });
+    return sdk.messages;
+}
+// ---------------------------------------------------------------------------
+// JSON tool schemas
+// ---------------------------------------------------------------------------
+const MAPPING_PROPOSAL_TOOL = {
+    name: "submit_mapping_proposals",
+    description: "Submit an array of candidate mappings from the natural-language question to registered canonical claim targets or derivation rules. " +
+        "You are PROPOSING for human review — every proposal must carry a rationale and confidence score. " +
+        "Per ADR 0003 §4, proposals are reviewable records; they do not resolve questions by themselves.",
+    input_schema: {
+        type: "object",
+        properties: {
+            proposals: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        proposedTargetSubjectType: {
+                            type: "string",
+                            description: "subjectType of the canonical claim target (omit if proposing a rule)",
+                        },
+                        proposedTargetSubjectId: {
+                            type: "string",
+                            description: "subjectId of the canonical claim target (omit if proposing a rule)",
+                        },
+                        proposedTargetFieldOrBehavior: {
+                            type: "string",
+                            description: "fieldOrBehavior of the canonical claim target (omit if proposing a rule)",
+                        },
+                        proposedRuleId: {
+                            type: "string",
+                            description: "Id of the derivation rule this question maps to (omit if proposing a target)",
+                        },
+                        confidence: {
+                            type: "number",
+                            description: "Confidence in this mapping (0.0–1.0)",
+                        },
+                        rationale: {
+                            type: "string",
+                            description: "Human-readable explanation of why this mapping is proposed",
+                        },
+                        excerpt: {
+                            type: "string",
+                            description: "Verbatim excerpt from the question that drove the suggestion",
+                        },
+                    },
+                    required: ["confidence", "rationale"],
+                },
+            },
+        },
+        required: ["proposals"],
+    },
+};
+const UTTERANCE_EXTRACTION_TOOL = {
+    name: "submit_extracted_statements",
+    description: "Submit an array of factual statements extracted from the agent utterance. " +
+        "Each statement maps to a canonical claim target with full provenance (excerpt, span, confidence). " +
+        "You are EXTRACTING FOR REVIEW — output is a proposal queue, not authoritative truth. " +
+        "Per ADR 0003 §4, every extracted statement requires a rationale and confidence score.",
+    input_schema: {
+        type: "object",
+        properties: {
+            statements: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        subjectType: {
+                            type: "string",
+                            description: "The canonical subjectType (use 'unknown' if uncertain)",
+                        },
+                        subjectId: {
+                            type: "string",
+                            description: "The entity or resource the statement is about",
+                        },
+                        fieldOrBehavior: {
+                            type: "string",
+                            description: "The property or behavior being claimed",
+                        },
+                        value: {
+                            description: "The claimed value (string, number, boolean, or null)",
+                        },
+                        excerpt: {
+                            type: "string",
+                            description: "Verbatim text from the utterance that contains this claim",
+                        },
+                        spanStart: {
+                            type: "number",
+                            description: "0-indexed character offset where the excerpt starts in the utterance",
+                        },
+                        spanEnd: {
+                            type: "number",
+                            description: "0-indexed character offset where the excerpt ends in the utterance",
+                        },
+                        confidence: {
+                            type: "number",
+                            description: "Extraction confidence (0.0–1.0)",
+                        },
+                    },
+                    required: ["subjectId", "fieldOrBehavior", "excerpt", "confidence"],
+                },
+            },
+        },
+        required: ["statements"],
+    },
+};
+// ---------------------------------------------------------------------------
+// Tool output parsing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the first tool_use block with the given name from a message.
+ * Returns undefined if not found (malformed output is rejected, never silently accepted).
+ */
+function extractToolUseInput(message, toolName) {
+    for (const block of message.content) {
+        if (block.type === "tool_use" && block.name === toolName) {
+            return block.input;
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isArray(value) {
+    return Array.isArray(value);
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function numberInRange(value, min, max) {
+    if (typeof value !== "number" || !isFinite(value))
+        return undefined;
+    if (value < min || value > max)
+        return undefined;
+    return value;
+}
+// ---------------------------------------------------------------------------
+// createAnthropicMappingProposer
+// ---------------------------------------------------------------------------
+/**
+ * Create a MappingProposer backed by Anthropic's API using forced tool-use.
+ *
+ * ADR 0003 §4: returns PROPOSALS only — they flow through the existing
+ * review/auto-accept machinery before counting as mappings.
+ *
+ * Tool output is validated strictly: malformed items (missing required fields,
+ * out-of-range confidence, no target and no rule) are filtered out rather than
+ * silently accepted.
+ */
+export function createAnthropicMappingProposer(opts = {}) {
+    const model = opts.model ?? DEFAULT_MODEL;
+    return {
+        name: `anthropic-mapping-proposer:${model}`,
+        async propose(question, context) {
+            const client = await resolveClient(opts);
+            // Build context summary for the prompt
+            const claimsContext = buildClaimsContext(context.bundle);
+            const rulesContext = buildRulesContext(context.rules);
+            const systemPrompt = [
+                "You are a mapping proposer for the Kontour trust ledger.",
+                "Your role is to PROPOSE (not decide) how a natural-language question maps to a registered canonical claim or derivation rule.",
+                "Every proposal you return will be reviewed by a human or auto-accept policy before it counts.",
+                "Do not make up claim targets that are not in the registered list below.",
+                "Return only proposals you genuinely believe are plausible mappings — with honest confidence scores.",
+                "",
+                claimsContext,
+                rulesContext,
+            ]
+                .filter(Boolean)
+                .join("\n");
+            const userMessage = `Question to map: "${question}"`;
+            const message = await client.create({
+                model,
+                max_tokens: 1024,
+                messages: [{ role: "user", content: `${systemPrompt}\n\n${userMessage}` }],
+                tools: [MAPPING_PROPOSAL_TOOL],
+                tool_choice: { type: "tool", name: "submit_mapping_proposals" },
+            });
+            const input = extractToolUseInput(message, "submit_mapping_proposals");
+            if (!isRecord(input))
+                return [];
+            const rawProposals = input["proposals"];
+            if (!isArray(rawProposals))
+                return [];
+            const proposedAt = new Date().toISOString();
+            const results = [];
+            for (const item of rawProposals) {
+                const proposal = parseMappingProposalItem(item, question, model, proposedAt);
+                if (proposal)
+                    results.push(proposal);
+            }
+            return results;
+        },
+    };
+}
+function parseMappingProposalItem(item, question, proposedBy, proposedAt) {
+    if (!isRecord(item))
+        return undefined;
+    const raw = item;
+    const confidence = numberInRange(raw.confidence, 0, 1);
+    const rationale = stringOrUndefined(raw.rationale);
+    // Both required fields must be present
+    if (confidence === undefined || rationale === undefined)
+        return undefined;
+    const subjectType = stringOrUndefined(raw.proposedTargetSubjectType);
+    const subjectId = stringOrUndefined(raw.proposedTargetSubjectId);
+    const fieldOrBehavior = stringOrUndefined(raw.proposedTargetFieldOrBehavior);
+    const ruleId = stringOrUndefined(raw.proposedRuleId);
+    const excerpt = stringOrUndefined(raw.excerpt);
+    // Exactly one of (target triple) or ruleId must be present
+    const hasTarget = subjectType !== undefined && subjectId !== undefined && fieldOrBehavior !== undefined;
+    const hasRule = ruleId !== undefined;
+    if (!hasTarget && !hasRule)
+        return undefined;
+    const proposedTarget = hasTarget
+        ? { subjectType: subjectType, subjectId: subjectId, fieldOrBehavior: fieldOrBehavior }
+        : undefined;
+    const id = `proposal.anthropic.${encodeId(question)}.${Date.now()}`;
+    return {
+        id,
+        question,
+        proposedTarget,
+        proposedRuleId: hasRule ? ruleId : undefined,
+        confidence,
+        rationale,
+        excerpt,
+        proposedBy,
+        proposedAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// createAnthropicUtteranceExtractor
+// ---------------------------------------------------------------------------
+/**
+ * Create a UtteranceClaimExtractor backed by Anthropic's API using forced tool-use.
+ *
+ * ADR 0003 §4: returns EXTRACTED STATEMENTS only — they carry full provenance
+ * (excerpt, span, extractor name, confidence) and flow through the Inquiry
+ * pipeline. They are never treated as authoritative.
+ *
+ * Malformed tool output is rejected/filtered — items missing required fields
+ * (subjectId, fieldOrBehavior, excerpt, confidence) are dropped.
+ */
+export function createAnthropicUtteranceExtractor(opts = {}) {
+    const model = opts.model ?? DEFAULT_MODEL;
+    return {
+        name: `anthropic-utterance-extractor:${model}`,
+        async extract(utterance) {
+            const client = await resolveClient(opts);
+            const systemPrompt = [
+                "You are a factual statement extractor for the Kontour trust ledger.",
+                "Your role is to identify every factual claim in the agent utterance and extract it with full provenance.",
+                "Each extracted statement will be reviewed for trust coverage — you are NOT deciding truth, only extracting for review.",
+                "Extract only statements that assert factual properties of named entities.",
+                "Skip opinions, predictions, and procedural descriptions.",
+                "Provide honest confidence scores — low confidence for ambiguous phrasing.",
+                "Include the exact verbatim excerpt and 0-indexed character span offsets.",
+            ].join("\n");
+            const userMessage = `Extract factual statements from this agent utterance:\n\n"${utterance}"`;
+            const message = await client.create({
+                model,
+                max_tokens: 2048,
+                messages: [{ role: "user", content: `${systemPrompt}\n\n${userMessage}` }],
+                tools: [UTTERANCE_EXTRACTION_TOOL],
+                tool_choice: { type: "tool", name: "submit_extracted_statements" },
+            });
+            const input = extractToolUseInput(message, "submit_extracted_statements");
+            if (!isRecord(input))
+                return [];
+            const rawStatements = input["statements"];
+            if (!isArray(rawStatements))
+                return [];
+            const results = [];
+            for (const item of rawStatements) {
+                const statement = parseExtractedStatementItem(item, utterance);
+                if (statement)
+                    results.push(statement);
+            }
+            return results;
+        },
+    };
+}
+function parseExtractedStatementItem(item, utterance) {
+    if (!isRecord(item))
+        return undefined;
+    const raw = item;
+    const subjectId = stringOrUndefined(raw.subjectId);
+    const fieldOrBehavior = stringOrUndefined(raw.fieldOrBehavior);
+    const excerpt = stringOrUndefined(raw.excerpt);
+    const confidence = numberInRange(raw.confidence, 0, 1);
+    // All required fields must be present
+    if (!subjectId || !fieldOrBehavior || !excerpt || confidence === undefined)
+        return undefined;
+    const subjectType = stringOrUndefined(raw.subjectType) ?? "unknown";
+    // Validate span if provided — both start and end must be valid integers
+    // within the utterance length
+    let span;
+    if (typeof raw.spanStart === "number" && typeof raw.spanEnd === "number") {
+        const start = Math.trunc(raw.spanStart);
+        const end = Math.trunc(raw.spanEnd);
+        if (Number.isFinite(start) &&
+            Number.isFinite(end) &&
+            start >= 0 &&
+            end > start &&
+            end <= utterance.length) {
+            span = { start, end };
+        }
+    }
+    return {
+        target: { subjectType, subjectId, fieldOrBehavior },
+        value: raw.value ?? undefined,
+        excerpt,
+        span,
+        confidence,
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompt context builders
+// ---------------------------------------------------------------------------
+function buildClaimsContext(bundle) {
+    if (!bundle || bundle.claims.length === 0)
+        return "";
+    const lines = [
+        "Registered canonical claim targets (use ONLY these as proposedTarget):",
+        ...bundle.claims.map((c) => `  - subjectType="${c.subjectType}" subjectId="${c.subjectId}" fieldOrBehavior="${c.fieldOrBehavior}"`),
+    ];
+    return lines.join("\n");
+}
+function buildRulesContext(rules) {
+    if (!rules || rules.length === 0)
+        return "";
+    const lines = [
+        "Registered derivation rules (use rule id as proposedRuleId):",
+        ...rules.map((r) => `  - id="${r.id}" name="${r.name}"`),
+    ];
+    return lines.join("\n");
+}
+function encodeId(value) {
+    return value
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9\-]/g, "")
+        .slice(0, 40);
+}

package/dist/src/index.d.ts

@@ -9,8 +9,8 @@ export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-r
 export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-resolution.js";
 export { flowTrustArtifactFromReviewOutcome } from "./to-flow-artifact.js";
 export type { FlowTrustArtifact, FlowTrustArtifactOptions } from "./to-flow-artifact.js";
-export { buildSurveyTrustInput } from "./to-surface.js";
-export type { BuildSurveyTrustInputOptions } from "./to-surface.js";
+export { buildSurveyTrustBundle } from "./to-surface.js";
+export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export type { LearningProjection, LearningProjectionKind, LearningProjectionSeverity, LearningProjectionSignal, } from "./learning-projections.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
@@ -25,3 +25,9 @@ export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildRev
 export type { ReviewCandidatePresentation, ReviewCandidatePresentationContext, ReviewItemPresentation, ReviewItemPresentationContext, ReviewPresentationAdapter, ReviewPresentationLink, ReviewResultPresentation, ReviewTracePresentationContext, ReviewTraceRef, ReviewValuePresentationContext, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
 export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, PolicyStandardMetadata, PolicyStandardSourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";
+export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
+export type { AutoAcceptPolicy, InquiryMapping, MappingProposal, MappingProposer, } from "./inquiry-mapping.js";
+export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
+export type { ExtractedStatement, StatementBadge, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
+export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
+export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";

package/dist/src/index.js

@@ -3,7 +3,7 @@ export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export { flowTrustArtifactFromReviewOutcome } from "./to-flow-artifact.js";
-export { buildSurveyTrustInput } from "./to-surface.js";
+export { buildSurveyTrustBundle } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, 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";
@@ -11,3 +11,6 @@ export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-workbench/review-presentation.js";
 export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
+export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
+export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
+export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";

package/dist/src/inquiry-mapping.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Inquiry mapping — ADR 0003 step 5.
+ *
+ * This module implements the "memoize the mapping, never the answer" principle.
+ * A MappingProposal is a reviewable record produced by a pluggable MappingProposer.
+ * Proposals flow through Survey's existing candidate → review machinery.
+ * The durable artifact after review is an InquiryMapping.
+ * Answers always recompute live from the TrustBundle.
+ *
+ * Nothing here silently decides. Exact canonical-form matching is the only thing
+ * that resolves without review. A proposer may suggest that a question maps to a
+ * registered claim or rule — but every suggestion lands as a MappingProposal with
+ * provenance before it counts. (ADR 0003 §4)
+ *
+ * Integration point: resolveQuestion is the entry point for consumers checking
+ * whether a cached mapping already covers a question. Flow-agent hook wiring
+ * (connecting this to an agent's output pipeline) is out of scope for this module
+ * and lives in the flow-agents repo.
+ */
+import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
+import type { CanonicalClaimTarget } from "@kontourai/surface";
+import type { Candidate, CandidateSet, ReviewOutcome } from "./types.js";
+/**
+ * A single machine- or human-generated suggestion that a natural-language
+ * question maps to a canonical claim target or a named derivation rule.
+ *
+ * Exactly one of proposedTarget / proposedRuleId must be set.
+ */
+export interface MappingProposal {
+    id: string;
+    question: string;
+    /** The canonical claim target this question is proposed to map to. */
+    proposedTarget?: CanonicalClaimTarget;
+    /** The derivation rule id this question is proposed to map to. */
+    proposedRuleId?: string;
+    /** Proposer confidence in the mapping (0–1). */
+    confidence: number;
+    /** Human-readable rationale for the proposal. */
+    rationale: string;
+    /** Optional verbatim excerpt from the question that drove the suggestion. */
+    excerpt?: string;
+    /** Who or what generated this proposal (name of the MappingProposer). */
+    proposedBy: string;
+    /** ISO 8601 timestamp. */
+    proposedAt: string;
+}
+/**
+ * The durable reviewed artifact: a natural-language question has been mapped
+ * to a canonical claim target or derivation rule and the mapping has been
+ * given a status through review (or auto-accept policy).
+ *
+ * Per ADR 0003 §6: memoize the mapping, never the answer.  Answers always
+ * recompute from live claim status; this record is never updated to carry
+ * a cached answer.
+ */
+export interface InquiryMapping {
+    id: string;
+    /** Deterministic normalized form of the question (see normalizeQuestion). */
+    normalizedQuestion: string;
+    /** The canonical claim target this mapping resolves to. */
+    target?: CanonicalClaimTarget;
+    /** The derivation rule id this mapping resolves to. */
+    ruleId?: string;
+    /** Whether the mapping was accepted by a human reviewer or auto-accept policy. */
+    status: "verified" | "assumed" | "rejected";
+    /** Actor who performed the review (reviewer id or "auto-accept-policy"). */
+    reviewedBy: string;
+    /** ISO 8601 timestamp of review. */
+    reviewedAt: string;
+    /** Optional rationale for the decision. */
+    rationale?: string;
+    /**
+     * Whether the reviewer was within their declared comfort zone.
+     * Mirrors Survey's withinComfortZone semantics: false means a different
+     * authority should confirm; true (or absent) means the reviewer was
+     * comfortable making this decision.
+     */
+    withinComfortZone?: boolean;
+    /** The id of the MappingProposal that was accepted or rejected. */
+    proposalId: string;
+}
+/**
+ * Pluggable interface for proposing a canonical mapping for a question.
+ *
+ * Implementations may be deterministic (like the reference proposer below),
+ * embedding-based, or LLM-backed — but they are always proposers: their output
+ * goes through review before it counts (ADR 0003 §4).
+ *
+ * The interface accepts both synchronous return values and Promises, matching
+ * Survey's async-optional style.
+ */
+export interface MappingProposer {
+    name: string;
+    propose(question: string, context: {
+        bundle?: TrustBundle;
+        rules?: DerivationRule[];
+    }): MappingProposal[] | Promise<MappingProposal[]>;
+}
+/**
+ * Deterministic normalization for question strings.
+ *
+ * Rules:
+ * - Lowercase
+ * - Collapse internal whitespace runs to a single space
+ * - Trim leading/trailing whitespace
+ * - Strip terminal punctuation (. ? ! , ;) from the end
+ *
+ * This is exact normalized-text memoization, not semantic matching.
+ * Two questions that differ only in case, whitespace, or trailing punctuation
+ * are considered the same question.  Questions with different wording but the
+ * same intent are NOT matched here; a MappingProposer handles that.
+ */
+export declare function normalizeQuestion(question: string): string;
+/**
+ * Project an array of proposals for a single question into Survey's existing
+ * Candidate / CandidateSet shapes so they flow through the existing review
+ * machinery rather than a parallel system.
+ *
+ * Status rules:
+ * - All proposals agree on the same target/ruleId → "needs-review"
+ * - Proposals disagree (more than one distinct resolved target/rule) → "conflict"
+ * - Empty proposals → "needs-review" with empty candidates
+ *
+ * The CandidateSet target is the normalized question; each Candidate carries
+ * the proposal id as extractionId and the proposal metadata.
+ */
+export declare function proposalsToCandidateSet(question: string, proposals: MappingProposal[]): {
+    candidateSet: CandidateSet;
+    candidates: Candidate[];
+};
+/**
+ * Turn a Survey ReviewOutcome on a mapping candidate set into a durable
+ * InquiryMapping record.
+ *
+ * The candidateSet must have been built by proposalsToCandidateSet.
+ * The reviewOutcome's candidateId must match one of the candidates.
+ */
+export declare function applyMappingReview(candidateSet: CandidateSet, reviewOutcome: ReviewOutcome): InquiryMapping;
+export interface AutoAcceptPolicy {
+    minConfidence: number;
+}
+/**
+ * Apply an auto-accept policy to a list of proposals, returning InquiryMappings.
+ *
+ * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
+ * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ *
+ * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
+ * need human review regardless of confidence.
+ *
+ * Returns an array of InquiryMappings (only for accepted proposals).
+ */
+export declare function applyAutoAcceptPolicy(proposals: MappingProposal[], policy: AutoAcceptPolicy): InquiryMapping[];
+/**
+ * Look up an InquiryMapping for a question by exact normalized-text match.
+ *
+ * Rejected mappings are remembered but never resolve: this function returns
+ * undefined for rejected mappings so callers treat the question as a miss.
+ * To check whether a question was previously rejected (and should not be
+ * re-proposed), call lookupRejectedMapping.
+ */
+export declare function lookupMapping(mappings: InquiryMapping[], question: string): InquiryMapping | undefined;
+/**
+ * Check whether a question was previously rejected.
+ * Rejected mappings prevent re-proposing: if this returns a mapping, the
+ * question should not be sent to a proposer again without human escalation.
+ */
+export declare function lookupRejectedMapping(mappings: InquiryMapping[], question: string): InquiryMapping | undefined;
+/**
+ * Resolve a natural-language question against a TrustBundle.
+ *
+ * On mapping hit (verified or assumed): constructs a Surface Inquiry from the
+ * mapped target/rule and returns resolveInquiry(...) — answers always recompute
+ * live from the current bundle state; the mapping is memoized, not the answer.
+ *
+ * On miss (no mapping, or rejected mapping): returns an InquiryRecord with
+ * outcome "unsupported" so the gap is honest and recordable.
+ *
+ * This function is the clean integration point for consumers. Flow-agent hook
+ * wiring (connecting this to an agent's output pipeline) lives in the
+ * flow-agents repo.
+ */
+export declare function resolveQuestion(bundle: TrustBundle, question: string, options: {
+    mappings: InquiryMapping[];
+    rules?: DerivationRule[];
+    now?: Date;
+    askedBy: string;
+}): InquiryRecord;
+/**
+ * Build ReviewItem records for the existing review workbench from a list of
+ * mapping candidate sets.
+ *
+ * Follow the existing ReviewItem contract exactly. This helper produces
+ * ReviewItem payloads so mapping proposals can be reviewed through the same
+ * workbench as other Survey candidates.
+ */
+export declare function buildMappingReviewItems(candidateSets: Array<{
+    candidateSet: CandidateSet;
+    candidates: Candidate[];
+}>): Array<{
+    apiVersion: "survey.kontourai.io/v1alpha1";
+    kind: "ReviewItem";
+    metadata: {
+        name: string;
+        labels?: Record<string, string>;
+    };
+    spec: {
+        target: string;
+        candidates: Array<{
+            id: string;
+            role: "proposed";
+            value: unknown;
+            confidence?: number;
+            source: {
+                sourceRef: string;
+                kind: "inquiry-question";
+                observedAt: string;
+                locatorScheme: "text";
+            };
+            extraction: {
+                target: string;
+                confidence?: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "low";
+            };
+            projection?: {
+                candidateSetId: string;
+                candidateId: string;
+            };
+        }>;
+        candidateSetStatus: "needs-review" | "conflict";
+        rationale?: string;
+    };
+    status: {
+        observedCandidateCount: number;
+    };
+}>;
+/**
+ * Reference MappingProposer for tests.
+ *
+ * REFERENCE IMPLEMENTATION ONLY — not suitable for production matching.
+ *
+ * Matching strategy: a question maps to a claim if it contains both the
+ * claim's subjectId and fieldOrBehavior as token substrings (case-insensitive,
+ * space-delimited token match). This is intentionally simple and transparent
+ * so tests can be deterministic.
+ */
+export declare const referenceMappingProposer: MappingProposer;