@kontourai/survey 1.4.0 → 1.5.0

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/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;

package/dist/src/producer-profile.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Canonical proposal-metadata key
+// ---------------------------------------------------------------------------
+/**
+ * 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 const PRODUCER_PROPOSAL_METADATA_KEY = "producerProposal";
+// ---------------------------------------------------------------------------
+// Candidate Conflict rule
+// ---------------------------------------------------------------------------
+/**
+ * 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 function hasCandidateConflict(proposals) {
+    return new Set(proposals.map((p) => p.equivalenceKey)).size > 1;
+}
+/**
+ * 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 function projectProposalsToCandidateSet(target, proposals, options) {
+    const candidates = proposals.map((proposal) => ({
+        id: proposal.candidateId,
+        extractionId: proposal.extractionId,
+        value: proposal.value,
+        confidence: proposal.confidence,
+        metadata: {
+            [PRODUCER_PROPOSAL_METADATA_KEY]: proposal.metadata,
+        },
+    }));
+    const status = hasCandidateConflict(proposals) ? "conflict" : "needs-review";
+    const candidateSet = {
+        id: options.candidateSetId,
+        target,
+        candidates,
+        status,
+        rationale: options.candidateSetRationale?.(status, proposals),
+        metadata: options.candidateSetMetadata,
+    };
+    return { candidateSet, candidates };
+}
+// ---------------------------------------------------------------------------
+// Typed proposal-metadata accessor
+// ---------------------------------------------------------------------------
+/**
+ * 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 function getProducerProposal(candidate) {
+    return candidate?.metadata?.[PRODUCER_PROPOSAL_METADATA_KEY];
+}
+// ---------------------------------------------------------------------------
+// Shared auto-accept primitives
+// ---------------------------------------------------------------------------
+/**
+ * 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 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 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 function meetsAutoAcceptThreshold(confidence, minConfidence) {
+    return confidence >= minConfidence;
+}

package/dist/src/raw-source.d.ts

@@ -39,6 +39,24 @@ export interface PolicyStandardSourceInput extends Omit<RawSourceInput, "locator
     locatorScheme?: LocatorScheme;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Raw Source kinds whose factories accept a caller-supplied `locatorScheme`
+ * override and otherwise fall back to a per-kind default. `uploaded-document`
+ * has no default (`undefined`) because `UploadedDocumentSourceInput.locatorScheme`
+ * is required, not optional — modeled here as a real, explicit table entry
+ * rather than an omission, so a caller-supplied value is the only source of
+ * truth for that kind.
+ *
+ * Module-internal seam: consumed by relative import from
+ * `rawSourceWithDefaultLocatorScheme` below and by
+ * `tests/raw-source-defaults.test.ts`, NOT re-exported from `src/index.ts`.
+ */
+export declare const DEFAULT_LOCATOR_SCHEME: {
+    "uploaded-document": undefined;
+    "api-record": LocatorScheme;
+    "web-page": LocatorScheme;
+    "manual-entry": LocatorScheme;
+};
 export declare function uploadedDocumentSource(input: UploadedDocumentSourceInput): RawSource;
 export declare function apiRecordSource(input: ApiRecordSourceInput): RawSource;
 export declare function webPageSource(input: WebPageSourceInput): RawSource;

package/dist/src/raw-source.js

@@ -1,23 +1,38 @@
+/**
+ * Raw Source kinds whose factories accept a caller-supplied `locatorScheme`
+ * override and otherwise fall back to a per-kind default. `uploaded-document`
+ * has no default (`undefined`) because `UploadedDocumentSourceInput.locatorScheme`
+ * is required, not optional — modeled here as a real, explicit table entry
+ * rather than an omission, so a caller-supplied value is the only source of
+ * truth for that kind.
+ *
+ * Module-internal seam: consumed by relative import from
+ * `rawSourceWithDefaultLocatorScheme` below and by
+ * `tests/raw-source-defaults.test.ts`, NOT re-exported from `src/index.ts`.
+ */
+export const DEFAULT_LOCATOR_SCHEME = {
+    "uploaded-document": undefined,
+    "api-record": "structured-field",
+    "web-page": "html",
+    "manual-entry": "structured-field",
+};
+function rawSourceWithDefaultLocatorScheme(kind, input) {
+    return rawSource(kind, {
+        locatorScheme: DEFAULT_LOCATOR_SCHEME[kind],
+        ...input,
+    });
+}
 export function uploadedDocumentSource(input) {
-    return rawSource("uploaded-document", input);
+    return rawSourceWithDefaultLocatorScheme("uploaded-document", input);
 }
 export function apiRecordSource(input) {
-    return rawSource("api-record", {
-        locatorScheme: "structured-field",
-        ...input,
-    });
+    return rawSourceWithDefaultLocatorScheme("api-record", input);
 }
 export function webPageSource(input) {
-    return rawSource("web-page", {
-        locatorScheme: "html",
-        ...input,
-    });
+    return rawSourceWithDefaultLocatorScheme("web-page", input);
 }
 export function manualEntrySource(input) {
-    return rawSource("manual-entry", {
-        locatorScheme: "structured-field",
-        ...input,
-    });
+    return rawSourceWithDefaultLocatorScheme("manual-entry", input);
 }
 export function policyStandardSource(input) {
     const policyStandard = {

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

@@ -1,20 +1,6 @@
 import type { SurveyObservationInput } from "./builder.js";
-export interface RepeatedObservationInput<TItem> {
-    id: string;
-    field: string;
-    value: readonly TItem[];
-    rawSource: SurveyObservationInput["rawSource"];
-    extraction: Omit<SurveyObservationInput["extraction"], "target" | "value" | "excerpt"> & {
-        target?: string;
-        excerpt?: string | null;
-    };
-    reviewOutcome?: SurveyObservationInput["reviewOutcome"];
-    claim: Omit<SurveyObservationInput["claim"], "fieldOrBehavior" | "value"> & {
-        fieldOrBehavior?: string;
-    };
-    candidate?: SurveyObservationInput["candidate"];
-    candidateSet?: SurveyObservationInput["candidateSet"];
+import { type ObservationAuthoringInput } from "./observation-helper.js";
+export interface RepeatedObservationInput<TItem> extends ObservationAuthoringInput<readonly TItem[]> {
     representation?: "aggregate-array";
-    metadata?: Record<string, unknown>;
 }
 export declare function repeatedObservation<TItem>(input: RepeatedObservationInput<TItem>): SurveyObservationInput;

package/dist/src/repeated-observation.js

@@ -1,16 +1,4 @@
-import { buildObservation } from "./observation-helper.js";
+import { buildRepeatedObservation } from "./observation-helper.js";
 export function repeatedObservation(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)`,
-    });
+    return buildRepeatedObservation(input);
 }