@kontourai/survey 1.3.0 → 1.5.0

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);
 }

package/dist/src/review-proof.d.ts

@@ -31,7 +31,7 @@ export interface CanonicalReviewProofPayload {
             candidateId?: string;
             subjectType: string;
             subjectId: string;
-            surface: string;
+            facet: string;
             claimType: string;
             fieldOrBehavior: string;
         };
@@ -92,7 +92,7 @@ export interface CanonicalReviewProofPayload {
         candidateId?: string;
         subjectType: string;
         subjectId: string;
-        surface: string;
+        facet: string;
         claimType: string;
         fieldOrBehavior: string;
         value?: unknown;

package/dist/src/review-proof.js

@@ -23,7 +23,7 @@ export function buildCanonicalReviewProofPayload(input) {
                 candidateId: input.candidate.id,
                 subjectType: input.claim.subjectType,
                 subjectId: input.claim.subjectId,
-                surface: input.claim.surface,
+                facet: input.claim.facet,
                 claimType: input.claim.claimType,
                 fieldOrBehavior: input.claim.fieldOrBehavior,
             },
@@ -86,7 +86,7 @@ export function buildCanonicalReviewProofPayload(input) {
             candidateId: input.claim.candidateId,
             subjectType: input.claim.subjectType,
             subjectId: input.claim.subjectId,
-            surface: input.claim.surface,
+            facet: input.claim.facet,
             claimType: input.claim.claimType,
             fieldOrBehavior: input.claim.fieldOrBehavior,
             value: input.claim.value,

package/dist/src/review-resource.d.ts

@@ -42,7 +42,11 @@ export interface ClaimTargetHint {
     claimId?: string;
     subjectType: string;
     subjectId: string;
-    surface: string;
+    /**
+     * Producer-defined grouping or namespace for this claim (Hachure schema 5,
+     * surface@2.0.0: Claim.surface -> Claim.facet).
+     */
+    facet: string;
     claimType: string;
     fieldOrBehavior: string;
     impactLevel: ClaimTarget["impactLevel"];

package/dist/src/review-workbench/review-workbench-data.d.ts

@@ -46,7 +46,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -98,7 +98,7 @@ export declare const publicDirectoryReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -184,7 +184,7 @@ export declare const regulatedRuleConflictReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -235,7 +235,7 @@ export declare const regulatedRuleConflictReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -334,7 +334,7 @@ export declare const facilityCredentialReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -395,7 +395,7 @@ export declare const facilityCredentialReviewItemExample: {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -472,7 +472,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -524,7 +524,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "medium";
@@ -609,7 +609,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";
@@ -660,7 +660,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
                 claimId: string;
                 subjectType: string;
                 subjectId: string;
-                surface: string;
+                facet: string;
                 claimType: string;
                 fieldOrBehavior: string;
                 impactLevel: "high";

package/dist/src/review-workbench/review-workbench-data.js

@@ -49,7 +49,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.current",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",
@@ -100,7 +100,7 @@ export const publicDirectoryReviewItemExample = {
                     claimId: "public-field.entity-123.availability-status.proposal-456",
                     subjectType: "public-record.entity",
                     subjectId: "entity-123",
-                    surface: "public-record.profile",
+                    facet: "public-record.profile",
                     claimType: "public-data.field-candidate",
                     fieldOrBehavior: "availabilityStatus",
                     impactLevel: "medium",
@@ -187,7 +187,7 @@ export const regulatedRuleConflictReviewItemExample = {
                     claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.current",
                     subjectType: "regulated-rule-source",
                     subjectId: "example-jurisdiction:2026:standardThreshold",
-                    surface: "regulated.rules",
+                    facet: "regulated.rules",
                     claimType: "regulated.rule-source-value",
                     fieldOrBehavior: "standardThreshold",
                     impactLevel: "high",
@@ -235,7 +235,7 @@ export const regulatedRuleConflictReviewItemExample = {
                     claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.proposed",
                     subjectType: "regulated-rule-source",
                     subjectId: "example-jurisdiction:2026:standardThreshold",
-                    surface: "regulated.rules",
+                    facet: "regulated.rules",
                     claimType: "regulated.rule-source-value",
                     fieldOrBehavior: "standardThreshold",
                     impactLevel: "high",
@@ -332,7 +332,7 @@ export const facilityCredentialReviewItemExample = {
                     claimId: "facility-credential.facility-42.operating-license.current",
                     subjectType: "facility",
                     subjectId: "facility-42",
-                    surface: "facility.credential-profile",
+                    facet: "facility.credential-profile",
                     claimType: "facility.credential",
                     fieldOrBehavior: "operatingLicenseCredential",
                     impactLevel: "high",
@@ -391,7 +391,7 @@ export const facilityCredentialReviewItemExample = {
                     claimId: "facility-credential.facility-42.operating-license.registry",
                     subjectType: "facility",
                     subjectId: "facility-42",
-                    surface: "facility.credential-profile",
+                    facet: "facility.credential-profile",
                     claimType: "facility.credential-candidate",
                     fieldOrBehavior: "operatingLicenseCredential",
                     impactLevel: "high",

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

@@ -1308,7 +1308,7 @@ function isReviewCandidate(value) {
         && isRecord(value.claimTarget)
         && typeof value.claimTarget.subjectType === "string"
         && typeof value.claimTarget.subjectId === "string"
-        && typeof value.claimTarget.surface === "string"
+        && typeof value.claimTarget.facet === "string"
         && typeof value.claimTarget.claimType === "string"
         && typeof value.claimTarget.fieldOrBehavior === "string"
         && typeof value.claimTarget.impactLevel === "string";

package/dist/src/review-workbench/server-review-session.d.ts

@@ -2,7 +2,7 @@ import { type DeriveReviewSessionApplyResultForSnapshotResult, type MapReviewWor
 import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
-import type { ReviewQueueSessionState } from "./review-queue-session.js";
+import { type ReviewQueueSessionState } from "./review-queue-session.js";
 export interface ServerReviewSessionRecord {
     readonly sessionName: string;
     readonly snapshot: ReviewQueueSessionState;
@@ -59,6 +59,19 @@ export interface DeriveServerReviewSessionApplyResultOptions {
 }
 export declare function createServerReviewSessionRecord(options: CreateServerReviewSessionRecordOptions): ServerReviewSessionRecord;
 export declare function hashReviewSessionSnapshot(snapshot: ReviewQueueSessionState): string;
+/**
+ * Project the current review session state from a snapshot plus its
+ * append-only event log: replay events over the snapshot when any exist,
+ * otherwise return the snapshot itself unchanged (same object reference —
+ * no eager replay, no copy). Collapses the
+ * `events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot`
+ * conditional that was duplicated across the MCP and console review
+ * adapters (src/mcp/review-mcp.ts, src/console/review-console-server.ts) —
+ * same shape of fix as canonicalJson in ./canonical.ts, which was
+ * extracted after two near-identical copies of a derivation desynced
+ * (audit 2026-06-28, ops#24).
+ */
+export declare function currentSessionState(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;
 export declare function compareServerReviewSessionFreshness(record: ServerReviewSessionRecord, snapshot: ReviewQueueSessionState, eventCount?: number): ServerReviewSessionFreshnessComparison;
 export declare function assertServerReviewSessionFreshness(record: ServerReviewSessionRecord, snapshot: ReviewQueueSessionState, eventCount?: number): void;
 export declare function validateServerReviewSessionEvents(record: ServerReviewSessionRecord, events: readonly ReviewSessionEvent[]): ServerReviewSessionEventValidationIssue[];

package/dist/src/review-workbench/server-review-session.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { deriveReviewSessionApplyResultForSnapshot, mapReviewWorkbenchResultsToApplyActions, ReviewApplyActionMappingError, } from "./review-workbench.js";
 import { validateReviewDecisionMode, } from "./producer-decision-mode.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+import { replayReviewSessionEvents } from "./review-queue-session.js";
 import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
     name = "StaleServerReviewSessionError";
@@ -34,6 +35,21 @@ export function createServerReviewSessionRecord(options) {
 export function hashReviewSessionSnapshot(snapshot) {
     return sha256(canonicalJson(snapshot));
 }
+/**
+ * Project the current review session state from a snapshot plus its
+ * append-only event log: replay events over the snapshot when any exist,
+ * otherwise return the snapshot itself unchanged (same object reference —
+ * no eager replay, no copy). Collapses the
+ * `events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot`
+ * conditional that was duplicated across the MCP and console review
+ * adapters (src/mcp/review-mcp.ts, src/console/review-console-server.ts) —
+ * same shape of fix as canonicalJson in ./canonical.ts, which was
+ * extracted after two near-identical copies of a derivation desynced
+ * (audit 2026-06-28, ops#24).
+ */
+export function currentSessionState(snapshot, events) {
+    return events.length > 0 ? replayReviewSessionEvents(snapshot, events) : snapshot;
+}
 export function compareServerReviewSessionFreshness(record, snapshot, eventCount) {
     const actualSnapshotHash = hashReviewSessionSnapshot(snapshot);
     const eventCountMatches = record.eventCount === undefined || eventCount === undefined || record.eventCount === eventCount;