@kontourai/survey 1.3.0 → 1.5.0

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

@@ -20,6 +20,7 @@
 import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
 import type { CanonicalClaimTarget } from "@kontourai/surface";
 import type { Candidate, CandidateSet, ReviewOutcome } from "./types.js";
+import type { ReviewItem } from "./review-resource.js";
 /**
  * A single machine- or human-generated suggestion that a natural-language
  * question maps to a canonical claim target or a named derivation rule.
@@ -197,52 +198,7 @@ export declare function resolveQuestion(bundle: TrustBundle, question: string, o
 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;
-    };
-}>;
+}>): ReviewItem[];
 /**
  * Reference MappingProposer for tests.
  *

package/dist/src/inquiry-mapping.js

@@ -18,6 +18,8 @@
  * and lives in the flow-agents repo.
  */
 import { resolveInquiry } from "@kontourai/surface";
+import { AUTO_ACCEPT_ACTOR, AUTO_ACCEPT_WITHIN_COMFORT_ZONE, getProducerProposal, hasCandidateConflict, meetsAutoAcceptThreshold, projectProposalsToCandidateSet, } from "./producer-profile.js";
+import { reviewResourceApiVersion } from "./review-resource.js";
 // ---------------------------------------------------------------------------
 // Question normalization
 // ---------------------------------------------------------------------------
@@ -42,9 +44,18 @@ export function normalizeQuestion(question) {
         .trim()
         .replace(/[.?!,;]+$/u, "");
 }
-// ---------------------------------------------------------------------------
-// Proposal → CandidateSet projection
-// ---------------------------------------------------------------------------
+/**
+ * The Candidate Conflict comparison key for a single mapping proposal: keys
+ * by canonical claim target (subjectType/subjectId/fieldOrBehavior) or by
+ * derivation rule id. Two proposals with the same key "agree"; more than one
+ * distinct key across a group of proposals is a conflict (see
+ * hasCandidateConflict).
+ */
+function mappingEquivalenceKey(proposal) {
+    return proposal.proposedTarget
+        ? `target:${proposal.proposedTarget.subjectType}/${proposal.proposedTarget.subjectId}/${proposal.proposedTarget.fieldOrBehavior}`
+        : `rule:${proposal.proposedRuleId}`;
+}
 /**
  * Project an array of proposals for a single question into Survey's existing
  * Candidate / CandidateSet shapes so they flow through the existing review
@@ -60,46 +71,33 @@ export function normalizeQuestion(question) {
  */
 export function proposalsToCandidateSet(question, proposals) {
     const normalized = normalizeQuestion(question);
-    const candidates = proposals.map((proposal) => ({
-        id: `mapping-candidate.${proposal.id}`,
+    const candidateSetProposals = proposals.map((proposal) => ({
+        candidateId: `mapping-candidate.${proposal.id}`,
         extractionId: proposal.id,
         value: proposal.proposedTarget ?? proposal.proposedRuleId ?? null,
         confidence: proposal.confidence,
+        equivalenceKey: mappingEquivalenceKey(proposal),
         metadata: {
-            mappingProposal: {
-                proposalId: proposal.id,
-                proposedTarget: proposal.proposedTarget,
-                proposedRuleId: proposal.proposedRuleId,
-                confidence: proposal.confidence,
-                rationale: proposal.rationale,
-                excerpt: proposal.excerpt,
-                proposedBy: proposal.proposedBy,
-                proposedAt: proposal.proposedAt,
-            },
+            proposalId: proposal.id,
+            proposedTarget: proposal.proposedTarget,
+            proposedRuleId: proposal.proposedRuleId,
+            confidence: proposal.confidence,
+            rationale: proposal.rationale,
+            excerpt: proposal.excerpt,
+            proposedBy: proposal.proposedBy,
+            proposedAt: proposal.proposedAt,
         },
     }));
-    // Determine status: conflict if proposals disagree on target/rule
-    const status = proposals.length > 1 && proposalsDisagree(proposals) ? "conflict" : "needs-review";
-    const candidateSet = {
-        id: `mapping-candidate-set.${normalized}`,
-        target: normalized,
-        candidates,
-        status,
-        metadata: {
+    return projectProposalsToCandidateSet(normalized, candidateSetProposals, {
+        candidateSetId: `mapping-candidate-set.${normalized}`,
+        candidateSetMetadata: {
             inquiryMapping: {
                 question,
                 normalizedQuestion: normalized,
                 kind: "inquiry-question",
             },
         },
-    };
-    return { candidateSet, candidates };
-}
-function proposalsDisagree(proposals) {
-    const keys = new Set(proposals.map((p) => p.proposedTarget
-        ? `target:${p.proposedTarget.subjectType}/${p.proposedTarget.subjectId}/${p.proposedTarget.fieldOrBehavior}`
-        : `rule:${p.proposedRuleId}`));
-    return keys.size > 1;
+    });
 }
 // ---------------------------------------------------------------------------
 // Review outcome → InquiryMapping
@@ -119,7 +117,7 @@ export function applyMappingReview(candidateSet, reviewOutcome) {
     if (!candidate) {
         throw new Error(`applyMappingReview: no candidate found for id ${candidateId ?? "<none>"}`);
     }
-    const meta = candidate.metadata?.mappingProposal;
+    const meta = getProducerProposal(candidate);
     const proposalId = meta?.proposalId ?? candidate.extractionId;
     const status = reviewOutcome.status === "verified" || reviewOutcome.status === "assumed" || reviewOutcome.status === "rejected"
         ? reviewOutcome.status
@@ -152,20 +150,20 @@ export function applyAutoAcceptPolicy(proposals, policy) {
     if (proposals.length === 0)
         return [];
     // If proposals disagree, none can be auto-accepted
-    if (proposals.length > 1 && proposalsDisagree(proposals))
+    if (hasCandidateConflict(proposals.map((p) => ({ equivalenceKey: mappingEquivalenceKey(p) }))))
         return [];
     return proposals
-        .filter((p) => p.confidence >= policy.minConfidence)
+        .filter((p) => meetsAutoAcceptThreshold(p.confidence, policy.minConfidence))
         .map((proposal) => ({
         id: `inquiry-mapping.auto.${normalizeQuestion(proposal.question)}`,
         normalizedQuestion: normalizeQuestion(proposal.question),
         target: proposal.proposedTarget,
         ruleId: proposal.proposedRuleId,
         status: "assumed",
-        reviewedBy: "auto-accept-policy",
+        reviewedBy: AUTO_ACCEPT_ACTOR,
         reviewedAt: proposal.proposedAt,
         rationale: `Auto-accepted: confidence ${proposal.confidence} >= threshold ${policy.minConfidence}. ${proposal.rationale}`,
-        withinComfortZone: true,
+        withinComfortZone: AUTO_ACCEPT_WITHIN_COMFORT_ZONE,
         proposalId: proposal.id,
     }));
 }
@@ -266,7 +264,7 @@ export function resolveQuestion(bundle, question, options) {
  */
 export function buildMappingReviewItems(candidateSets) {
     return candidateSets.map(({ candidateSet, candidates }) => ({
-        apiVersion: "survey.kontourai.io/v1alpha1",
+        apiVersion: reviewResourceApiVersion,
         kind: "ReviewItem",
         metadata: {
             name: candidateSet.id,
@@ -275,7 +273,7 @@ export function buildMappingReviewItems(candidateSets) {
         spec: {
             target: candidateSet.target,
             candidates: candidates.map((candidate) => {
-                const meta = candidate.metadata?.mappingProposal;
+                const meta = getProducerProposal(candidate);
                 const targetOrRule = meta?.proposedTarget
                     ? `${meta.proposedTarget.subjectType}/${meta.proposedTarget.subjectId}/${meta.proposedTarget.fieldOrBehavior}`
                     : `rule:${meta?.proposedRuleId ?? "unknown"}`;
@@ -299,7 +297,7 @@ export function buildMappingReviewItems(candidateSets) {
                     claimTarget: {
                         subjectType: meta?.proposedTarget?.subjectType ?? "inquiry",
                         subjectId: meta?.proposedTarget?.subjectId ?? candidateSet.target,
-                        surface: "inquiry.mapping",
+                        facet: "inquiry.mapping",
                         claimType: "inquiry-mapping",
                         fieldOrBehavior: meta?.proposedTarget?.fieldOrBehavior ?? meta?.proposedRuleId ?? "unknown",
                         impactLevel: "low",

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

@@ -1,8 +1,8 @@
 import { createInterface } from "node:readline";
 import { readFile, writeFile, rename } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
-import { buildReviewSessionEvents, currentReviewItem, deriveQueueRowStatus, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
-import { createServerReviewSessionRecord, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { buildReviewSessionEvents, currentReviewItem, deriveQueueRowStatus, nextUnresolvedItemName, reviewSessionSummary, workbenchDecisionDefinitions, } from "../review-workbench/review-workbench.js";
+import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
 /**
  * Minimal Model Context Protocol server over stdio for review-queue inspection
  * and decision-making against a session JSON file.
@@ -42,7 +42,7 @@ async function writeSessionFileAtomic(path, content) {
 }
 // ---- Queue helpers -------------------------------------------------------
 function queueSummaryText(snapshot, events) {
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const summary = reviewSessionSummary(current);
     const total = current.items.length;
     const resolved = total - summary.unresolved;
@@ -66,7 +66,7 @@ function queueSummaryText(snapshot, events) {
     ].join("\n");
 }
 function itemDetailText(item, snapshot, events) {
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const status = deriveQueueRowStatus(item, current);
     const decision = current.decisionsByItemName[item.metadata.name];
     const note = current.notesByItemName[item.metadata.name];
@@ -112,7 +112,7 @@ function escapeHtml(text) {
         .replace(/"/g, """);
 }
 function buildReviewCardHtml(item, snapshot, events) {
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const summary = reviewSessionSummary(current);
     const total = current.items.length;
     const resolved = total - summary.unresolved;
@@ -293,7 +293,7 @@ async function toolQueue(options) {
     const text = queueSummaryText(snapshot, events);
     const queueData = {
         items: snapshot.items.map((item) => {
-            const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+            const current = currentSessionState(snapshot, events);
             return {
                 name: item.metadata.name,
                 target: item.spec.target,
@@ -302,14 +302,14 @@ async function toolQueue(options) {
                 candidateSetStatus: item.spec.candidateSetStatus,
             };
         }),
-        summary: reviewSessionSummary(events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot),
-        activeItemName: (events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot).activeItemName,
+        summary: reviewSessionSummary(currentSessionState(snapshot, events)),
+        activeItemName: currentSessionState(snapshot, events).activeItemName,
     };
     const content = [
         { type: "text", text: `${text}\n\n${JSON.stringify(queueData, null, 2)}` },
     ];
     if (!options.noUi) {
-        const activeItem = currentReviewItem(events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot);
+        const activeItem = currentReviewItem(currentSessionState(snapshot, events));
         content.push(buildUiResource(activeItem, snapshot, events, "queue"));
     }
     return content;
@@ -317,7 +317,7 @@ async function toolQueue(options) {
 async function toolItem(itemName, options) {
     const file = await readSessionFile(options.sessionPath);
     const { snapshot, events } = file;
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const item = current.items.find((i) => i.metadata.name === itemName);
     if (!item) {
         throw new DomainError(`Unknown review item: ${itemName}`);
@@ -354,7 +354,7 @@ async function toolDecide(itemName, mcpDecision, note, options) {
     }
     const file = await readSessionFile(options.sessionPath);
     const { snapshot, events } = file;
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const item = current.items.find((i) => i.metadata.name === itemName);
     if (!item) {
         throw new DomainError(`Unknown review item: ${itemName}`);
@@ -436,7 +436,7 @@ function buildUiResource(item, snapshot, events, instance) {
 // embedded `queue` resource carries — here served via resources/read).
 async function readQueuePanelHtml(options) {
     const { snapshot, events } = await readSessionFile(options.sessionPath);
-    const current = events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+    const current = currentSessionState(snapshot, events);
     const activeItem = currentReviewItem(current);
     return buildReviewCardHtml(activeItem, snapshot, events);
 }

package/dist/src/observation-helper.d.ts

@@ -1,5 +1,41 @@
 import type { SurveyObservationInput } from "./builder.js";
-export interface BuildObservationInput<TValue> {
+/**
+ * Observation authoring core — CONTEXT.md "Observation" / "Field Observation
+ * and Repeated Observation" ("helper shapes for authoring Observations, not
+ * separate domain concepts").
+ *
+ * `buildObservation`/`BuildObservationInput` are the shared authoring
+ * primitive: they own the `extraction.target`/`value`/`excerpt` and
+ * `claim.fieldOrBehavior`/`value`/`metadata` assembly (including the
+ * three-way `claim.metadata` / caller `metadata` / representation-supplied
+ * `surveyMetadata` merge below). Consumed by relative import from
+ * `field-observation.ts`, `repeated-observation.ts` (via the
+ * representation-keyed `buildFieldObservation`/`buildRepeatedObservation`
+ * wrappers below), and `source-of-authority-observation.ts`, which calls
+ * `buildObservation` directly with its own `surveyMetadata`/`defaultExcerpt`.
+ * None of this is re-exported from `src/index.ts`.
+ *
+ * `ObservationAuthoringInput` is the shared base shape (id/field/value/
+ * rawSource/extraction/reviewOutcome/claim/candidate/candidateSet/metadata)
+ * common to `BuildObservationInput` and the two public skins' input types
+ * (`FieldObservationInput`, `RepeatedObservationInput`); the skins extend it
+ * with only their own `representation` literal.
+ *
+ * `buildFieldObservation`/`buildRepeatedObservation` are the representation-
+ * keyed layer above `buildObservation`: each owns the default-excerpt
+ * formula and the `surveyMetadata` sub-key (`field` vs `repeated`) for its
+ * representation. They do not change `buildObservation`'s own signature or
+ * body — `source-of-authority-observation.ts` depends on that staying
+ * exactly as-is.
+ *
+ * `mergeObservationMetadata`/`mergeNestedRecords` are exported as a
+ * module-internal seam (like `src/producer-discipline.ts`) purely for direct
+ * test import (`tests/observation-helper.test.ts`) — consumed by relative
+ * import only, NOT re-exported from `src/index.ts`. Their bodies, including
+ * the `mergeNestedRecords` nested-record-vs-scalar asymmetry and the `??`
+ * null/undefined coalescing, are unchanged characterization, not a defect.
+ */
+export interface ObservationAuthoringInput<TValue> {
     id: string;
     field: string;
     value: TValue;
@@ -15,7 +51,17 @@ export interface BuildObservationInput<TValue> {
     candidate?: SurveyObservationInput["candidate"];
     candidateSet?: SurveyObservationInput["candidateSet"];
     metadata?: Record<string, unknown>;
+}
+export interface BuildObservationInput<TValue> extends ObservationAuthoringInput<TValue> {
     surveyMetadata: Record<string, unknown>;
     defaultExcerpt: string;
 }
 export declare function buildObservation<TValue>(input: BuildObservationInput<TValue>): SurveyObservationInput;
+export declare function buildFieldObservation<TValue>(input: ObservationAuthoringInput<TValue> & {
+    representation?: "scalar";
+}): SurveyObservationInput;
+export declare function buildRepeatedObservation<TItem>(input: ObservationAuthoringInput<readonly TItem[]> & {
+    representation?: "aggregate-array";
+}): SurveyObservationInput;
+export declare function mergeObservationMetadata(claimMetadata: Record<string, unknown> | undefined, metadata: Record<string, unknown> | undefined, surveyMetadata: Record<string, unknown>): Record<string, unknown>;
+export declare function mergeNestedRecords(claimSurvey: Record<string, unknown>, survey: Record<string, unknown>, surveyMetadata: Record<string, unknown>): Record<string, unknown>;

package/dist/src/observation-helper.js

@@ -19,7 +19,46 @@ export function buildObservation(input) {
         },
     };
 }
-function mergeObservationMetadata(claimMetadata, metadata, surveyMetadata) {
+/**
+ * Representation-keyed layer above `buildObservation`. Owns the
+ * `surveyMetadata` sub-key name, the default-`representation` literal, and
+ * the default-excerpt formula for the "field" (scalar) and "repeated"
+ * (aggregate-array) representations — the knowledge previously duplicated
+ * inline in `field-observation.ts`/`repeated-observation.ts`. Called only by
+ * the two thin public skins; `buildObservation` itself stays representation-
+ * agnostic.
+ */
+function valueSummary(value) {
+    if (value === null || value === undefined)
+        return "<empty>";
+    return String(value);
+}
+export function buildFieldObservation(input) {
+    const representation = input.representation ?? "scalar";
+    return buildObservation({
+        ...input,
+        surveyMetadata: {
+            field: { representation },
+        },
+        defaultExcerpt: `${input.field}: ${valueSummary(input.value)}`,
+    });
+}
+export function buildRepeatedObservation(input) {
+    const representation = input.representation ?? "aggregate-array";
+    const value = [...input.value];
+    return buildObservation({
+        ...input,
+        value,
+        surveyMetadata: {
+            repeated: {
+                representation,
+                itemCount: value.length,
+            },
+        },
+        defaultExcerpt: `${input.field}: ${value.length} item(s)`,
+    });
+}
+export function mergeObservationMetadata(claimMetadata, metadata, surveyMetadata) {
     const claimSurvey = claimMetadata?.survey && isRecord(claimMetadata.survey) ? claimMetadata.survey : {};
     const survey = metadata?.survey && isRecord(metadata.survey) ? metadata.survey : {};
     return {
@@ -32,7 +71,7 @@ function mergeObservationMetadata(claimMetadata, metadata, surveyMetadata) {
         },
     };
 }
-function mergeNestedRecords(claimSurvey, survey, surveyMetadata) {
+export function mergeNestedRecords(claimSurvey, survey, surveyMetadata) {
     const merged = {};
     const keys = new Set([
         ...Object.keys(claimSurvey),

package/dist/src/oversight-metrics.d.ts

@@ -113,8 +113,8 @@ export interface OversightMetricsClaimsSubject {
     readonly subjectType: string;
     /** Surface subject id (e.g. a session name or actor id). */
     readonly subjectId: string;
-    /** Surface name (e.g. "review.oversight"). */
-    readonly surface: string;
+    /** Surface facet (e.g. "review.oversight"). */
+    readonly facet: string;
     /** Actor id to record on events. */
     readonly actor: string;
     /** ISO 8601 timestamp for claim created/updated times. */

package/dist/src/oversight-metrics.js

@@ -217,7 +217,7 @@ export function oversightMetricsToClaims(metrics, subject) {
             id: claimId,
             subjectType: subject.subjectType,
             subjectId: subject.subjectId,
-            surface: subject.surface,
+            facet: subject.facet,
             claimType: "oversight-quality",
             fieldOrBehavior,
             value,

package/dist/src/producer-discipline.d.ts

@@ -0,0 +1,40 @@
+import type { TrustStatus } from "@kontourai/surface";
+/**
+ * Producer Discipline core — CONTEXT.md "Producer Discipline" /
+ * "Source-of-Authority Observation".
+ *
+ * The one piece of the review-discipline rule proven identical, field by
+ * field, across both existing enforcement points (2026-07 exploration):
+ *   - src/to-surface.ts's assertProducerDiscipline (verified/assumed claims)
+ *   - src/source-of-authority-observation.ts's assertVerifiedPosture
+ *     (verified/assumed source-of-authority observations)
+ * Both require, in the same relative order, when status is "verified" or
+ * "assumed": (1) a review outcome exists, (2) it has a reviewer (actor),
+ * (3) it has a reviewedAt time — with identical error text modulo the
+ * subject noun ("Claim X" vs. "Source-of-authority observation X"), which
+ * each call site supplies.
+ *
+ * The two sites' SOURCE LOCATOR requirements are NOT identical (to-surface
+ * gates on rawSource.kind !== "manual-entry" regardless of status;
+ * source-of-authority-observation gates on status verified/assumed
+ * regardless of rawSource.kind, with no manual-entry exemption), and
+ * source-of-authority-observation has an additional sourceRef check
+ * to-surface does not have. Both stay call-site-local — this module does
+ * not decide them.
+ *
+ * Module-internal seam (like src/producer-profile.ts): consumed by
+ * relative import from src/to-surface.ts and
+ * src/source-of-authority-observation.ts, NOT re-exported from
+ * src/index.ts.
+ */
+export interface ReviewOutcomePosture {
+    actor?: string;
+    reviewedAt?: string;
+}
+export declare function assertReviewOutcomeDiscipline(input: {
+    /** Message subject, e.g. `Claim ${id}` or `Source-of-authority observation ${id}` —
+     *  each call site supplies its own noun so error text is unchanged. */
+    subject: string;
+    status: TrustStatus | undefined;
+    review?: ReviewOutcomePosture;
+}): void;

package/dist/src/producer-discipline.js

@@ -0,0 +1,13 @@
+export function assertReviewOutcomeDiscipline(input) {
+    if (input.status !== "verified" && input.status !== "assumed")
+        return;
+    if (!input.review) {
+        throw new Error(`${input.subject} cannot be ${input.status} without a review outcome`);
+    }
+    if (!input.review.actor) {
+        throw new Error(`${input.subject} cannot be ${input.status} without review actor authority`);
+    }
+    if (!input.review.reviewedAt) {
+        throw new Error(`${input.subject} cannot be ${input.status} without reviewedAt`);
+    }
+}

package/dist/src/producer-profile.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Producer Profile core — ADR 0003 §4, CONTEXT.md "Producer Profile".
+ *
+ * This module carries the shared scaffolding every Producer Profile
+ * (inquiry-mapping, schema-mapping, and — from Slice 4 — agent-utterance)
+ * needs to turn its own proposals into Survey's existing Candidate/Candidate
+ * Set records: a generic proposal -> Candidate Set projection grouped by
+ * target, the Candidate Conflict rule, and one canonical `Candidate.metadata`
+ * key with a typed accessor, replacing each profile's hand-rolled projection,
+ * conflict check, and `as`-cast metadata round-trip.
+ *
+ * This is a module-internal seam: its exports are consumed directly by
+ * profile modules via relative import and are NOT re-exported from
+ * `src/index.ts`.
+ *
+ * Hard constraint (ADR 0003 §4): this module never decides a review outcome
+ * or a claim status. It only shapes proposal-backed Candidate/Candidate Set
+ * records — every profile still routes its output through Survey's existing
+ * review -> claim machinery unchanged.
+ */
+import type { Candidate, CandidateSet, CandidateSetStatus } from "./types.js";
+/**
+ * The one canonical `Candidate.metadata` key every Producer Profile uses to
+ * carry its profile-specific proposal payload. Replaces the per-profile keys
+ * (`mappingProposal`, `schemaMappingProposal`) each profile used before
+ * adopting this core module.
+ */
+export declare const PRODUCER_PROPOSAL_METADATA_KEY: "producerProposal";
+/**
+ * One profile-adapted proposal, ready to be projected into a Candidate inside
+ * a shared Candidate Set.
+ */
+export interface CandidateSetProposal<TValue = unknown, TMetadata = unknown> {
+    /**
+     * Caller-supplied, fully-formed Candidate id. Not templated by the core so
+     * each profile keeps its own distinct id scheme byte-for-byte.
+     */
+    candidateId: string;
+    /**
+     * Caller-supplied, fully-formed Extraction id this proposal traces back to.
+     * Not templated by the core for the same reason as `candidateId`.
+     */
+    extractionId: string;
+    /** The proposed value, copied through to the projected Candidate verbatim. */
+    value: TValue;
+    /** Optional proposer confidence, copied through to the projected Candidate. */
+    confidence?: number;
+    /**
+     * The Candidate Conflict comparison key. Required, and deliberately not
+     * derived from `value` by the core, so each profile controls exactly what
+     * "agrees" means for its own domain (e.g. a compound value may still be
+     * considered equivalent under a narrower key than a full deep-compare).
+     */
+    equivalenceKey: string;
+    /**
+     * The profile's own payload, stored verbatim under
+     * {@link PRODUCER_PROPOSAL_METADATA_KEY} on the projected Candidate's
+     * `metadata`.
+     */
+    metadata: TMetadata;
+}
+/**
+ * The shared Candidate Conflict rule: a group of proposals conflicts iff it
+ * carries more than one distinct `equivalenceKey`. A group of 0 or 1
+ * proposals can never conflict.
+ */
+export declare function hasCandidateConflict(proposals: Array<Pick<CandidateSetProposal, "equivalenceKey">>): boolean;
+export interface ProjectProposalsToCandidateSetOptions {
+    /** The id for the projected Candidate Set. */
+    candidateSetId: string;
+    /** Optional metadata to attach to the projected Candidate Set. */
+    candidateSetMetadata?: Record<string, unknown>;
+    /**
+     * Optional rationale-builder for the projected Candidate Set, given the
+     * computed status and the input proposals.
+     */
+    candidateSetRationale?: (status: CandidateSetStatus, proposals: CandidateSetProposal[]) => string | undefined;
+}
+/**
+ * Build one Candidate Set (and its Candidates) from one target's proposal
+ * group. Grouping proposals by target itself stays a caller concern — this
+ * function projects exactly one group per call; it never reaches across
+ * multiple targets on its own. `status` is `"conflict"` when
+ * {@link hasCandidateConflict} is true for `proposals`, otherwise
+ * `"needs-review"` (an empty `proposals` array yields `"needs-review"` with
+ * an empty `candidates` array). `selectedCandidateId` is left unset — both
+ * profiles compute it themselves, or not at all, per their own review flow.
+ */
+export declare function projectProposalsToCandidateSet<TValue = unknown, TMetadata = unknown>(target: string, proposals: Array<CandidateSetProposal<TValue, TMetadata>>, options: ProjectProposalsToCandidateSetOptions): {
+    candidateSet: CandidateSet;
+    candidates: Candidate[];
+};
+/**
+ * Typed read-back of the proposal payload a Candidate carries under
+ * {@link PRODUCER_PROPOSAL_METADATA_KEY}. Returns `undefined` if the
+ * Candidate, its `metadata`, or the key itself is absent — never throws.
+ *
+ * No fallback reads of any legacy per-profile metadata key are performed
+ * (Owner decision: no legacy support).
+ */
+export declare function getProducerProposal<TMetadata>(candidate: Candidate | undefined): TMetadata | undefined;
+/**
+ * Actor identity every Producer Profile's auto-accept policy uses when it
+ * accepts a proposal without human review. Shared literal — see ADR 0003
+ * §4 (the core never decides "verified"; auto-accept only ever produces
+ * "assumed" + comfort-zone true).
+ */
+export declare const AUTO_ACCEPT_ACTOR: "auto-accept-policy";
+/**
+ * The comfort-zone posture every Producer Profile's auto-accept policy
+ * sets when it accepts a proposal: `withinComfortZone: true` always — an
+ * auto-accepted proposal is, by definition, one the policy's declared
+ * threshold covers, so there is nothing "outside comfort zone" about an
+ * auto-accept decision (ADR 0003 §4).
+ */
+export declare const AUTO_ACCEPT_WITHIN_COMFORT_ZONE: true;
+/**
+ * The one auto-accept threshold rule every Producer Profile applies: a
+ * confidence value clears an auto-accept policy iff it is at or above
+ * (inclusive) the policy's minimum confidence. This is the only piece of
+ * auto-accept *mechanics* that is identical across profiles today — each
+ * profile decides its own iteration granularity (per-proposal filter vs.
+ * per-group max-confidence gate) and output record shape around this call;
+ * the core does not decide that.
+ *
+ * These three exports are the ONLY auto-accept semantics the two profiles
+ * genuinely share today (see the Slice 3 plan's Part (a) field-by-field
+ * diff table). Everything else about auto-accept — iteration granularity
+ * (per-proposal vs. per-group), output record type and cardinality, id
+ * templates, timestamp source, and rationale string format — diverges
+ * between profiles and stays entirely per-profile; this module does not
+ * decide any of it.
+ */
+export declare function meetsAutoAcceptThreshold(confidence: number, minConfidence: number): boolean;