@kontourai/survey 0.4.23 → 0.5.0

package/dist/example-data/corrected-document-candidates.d.ts

@@ -0,0 +1,2 @@
+import type { SurveyInput } from "../src/index.js";
+export declare const correctedDocumentCandidatesExample: SurveyInput;

package/dist/{fixtures → example-data}/corrected-document-candidates.js

@@ -1,6 +1,6 @@
 const generatedAt = "2026-05-31T16:00:00.000Z";
-export const correctedDocumentCandidatesFixture = {
-    source: "survey.fixture.corrected-document-candidates",
+export const correctedDocumentCandidatesExample = {
+    source: "survey.example.corrected-document-candidates",
     generatedAt,
     rawSources: [
         {
@@ -166,7 +166,7 @@ function computationClaim(id, status, inputClaimIds) {
         impactLevel: "high",
         evidenceType: "calculation_trace",
         evidenceMethod: "validation",
-        collectedBy: "survey-document-fixture",
+        collectedBy: "survey-document-example",
         eventMethod: "rule-application",
         derivedFrom: inputClaimIds,
         derivationEdges: inputClaimIds.map((inputClaimId, index) => ({

package/dist/{fixtures → example-data}/downstream-public-directory-proposal.d.ts

@@ -39,7 +39,7 @@ export interface DownstreamPublicDirectoryProposal {
     crawlTrigger?: string;
     crawlTriggeredBy?: string | null;
 }
-export declare const downstreamPublicDirectoryProposalFixture: {
+export declare const downstreamPublicDirectoryProposalExample: {
     id: string;
     publicRecordId: string;
     crawlRunId: string;

package/dist/{fixtures → example-data}/downstream-public-directory-proposal.js

@@ -1,4 +1,4 @@
-export const downstreamPublicDirectoryProposalFixture = {
+export const downstreamPublicDirectoryProposalExample = {
     id: "proposal-public-456",
     publicRecordId: "record-123",
     crawlRunId: "crawl-run-2026-05-31",

package/dist/{fixtures → example-data}/public-directory-review-resource.d.ts

@@ -1,4 +1,4 @@
-export declare const publicDirectoryReviewItemFixture: {
+export declare const publicDirectoryReviewItemExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {
@@ -128,7 +128,7 @@ export declare const publicDirectoryReviewItemFixture: {
         reviewDecisionName: string;
     };
 };
-export declare const publicDirectoryReviewDecisionFixture: {
+export declare const publicDirectoryReviewDecisionExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewDecision";
     metadata: {

package/dist/{fixtures → example-data}/public-directory-review-resource.js

@@ -1,5 +1,5 @@
 import { reviewResourceApiVersion } from "../src/index.js";
-export const publicDirectoryReviewItemFixture = {
+export const publicDirectoryReviewItemExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewItem",
     metadata: {
@@ -129,7 +129,7 @@ export const publicDirectoryReviewItemFixture = {
         reviewDecisionName: "public-directory-availability-operator-decision",
     },
 };
-export const publicDirectoryReviewDecisionFixture = {
+export const publicDirectoryReviewDecisionExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewDecision",
     metadata: {

package/dist/example-data/public-field-review.d.ts

@@ -0,0 +1,2 @@
+import type { SurveyInput } from "../src/index.js";
+export declare const publicFieldReviewExample: SurveyInput;

package/dist/{fixtures → example-data}/public-field-review.js

@@ -1,6 +1,6 @@
 const generatedAt = "2026-05-31T16:00:00.000Z";
-export const publicFieldReviewFixture = {
-    source: "survey.fixture.public-field-review",
+export const publicFieldReviewExample = {
+    source: "survey.example.public-field-review",
     generatedAt,
     rawSources: [
         {

package/dist/{fixtures → example-data}/regulated-document-review-resource.d.ts

@@ -1,4 +1,4 @@
-export declare const regulatedDocumentReviewItemFixture: {
+export declare const regulatedDocumentReviewItemExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {

package/dist/{fixtures → example-data}/regulated-document-review-resource.js

@@ -1,5 +1,5 @@
 import { reviewResourceApiVersion } from "../src/index.js";
-export const regulatedDocumentReviewItemFixture = {
+export const regulatedDocumentReviewItemExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewItem",
     metadata: {
@@ -56,7 +56,7 @@ export const regulatedDocumentReviewItemFixture = {
                     impactLevel: "high",
                     evidenceType: "calculation_trace",
                     evidenceMethod: "validation",
-                    collectedBy: "survey-document-fixture",
+                    collectedBy: "survey-document-example",
                     derivedFrom: [
                         "document.entity-1.statement.amount.original",
                         "document.entity-1.statement.credit.original",
@@ -108,7 +108,7 @@ export const regulatedDocumentReviewItemFixture = {
                     impactLevel: "high",
                     evidenceType: "calculation_trace",
                     evidenceMethod: "validation",
-                    collectedBy: "survey-document-fixture",
+                    collectedBy: "survey-document-example",
                     derivedFrom: [
                         "document.entity-1.statement.amount.corrected",
                         "document.entity-1.statement.credit.corrected",

package/dist/examples/public-field-observation.js

@@ -1,5 +1,5 @@
-import { buildTrustReport, validateTrustInput } from "@kontourai/surface";
-import { buildSurveyTrustInput, SurveyInputBuilder } from "../src/index.js";
+import { buildTrustReport, validateTrustBundle } from "@kontourai/surface";
+import { buildSurveyTrustBundle, SurveyInputBuilder } from "../src/index.js";
 const observedAt = "2026-05-31T16:00:00.000Z";
 const surveyInput = new SurveyInputBuilder({
     source: "example-producer:public-field",
@@ -38,6 +38,6 @@ const surveyInput = new SurveyInputBuilder({
     },
 })
     .build();
-const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
-const report = buildTrustReport(trustInput);
+const trustBundle = validateTrustBundle(buildSurveyTrustBundle(surveyInput));
+const report = buildTrustReport(trustBundle);
 console.log(JSON.stringify(report.summary, null, 2));

package/dist/examples/review-workbench/downstream-public-directory-adapter.d.ts

@@ -1,3 +1,3 @@
 import { type ReviewItem } from "../../src/review-resource.js";
-import type { DownstreamPublicDirectoryProposal } from "../../fixtures/downstream-public-directory-proposal.js";
+import type { DownstreamPublicDirectoryProposal } from "../../example-data/downstream-public-directory-proposal.js";
 export declare function downstreamPublicDirectoryProposalToReviewItem(proposal: DownstreamPublicDirectoryProposal, field?: string): ReviewItem;

package/dist/examples/review-workbench/facility-credential-consumer.d.ts

@@ -1,11 +1,11 @@
-import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
+import { facilityCredentialReviewItemExample } from "../../src/review-workbench/review-workbench-data.js";
 import { buildReviewItemPresentation, buildReviewResultPresentation, buildSurfaceProjectionPreview, deriveReviewSessionApplyResultForSnapshot, initialReviewQueueSessionState, type ReviewPresentationAdapter } from "../../src/review-workbench/review-workbench.js";
 import type { ReviewSessionEvent } from "../../src/review-resource.js";
 export declare const facilityCredentialPresentationAdapter: ReviewPresentationAdapter;
 export declare function buildFacilityCredentialConsumerExample(): Promise<FacilityCredentialConsumerExample>;
 export declare const facilityCredentialConsumerExample: FacilityCredentialConsumerExample;
 export interface FacilityCredentialConsumerExample {
-    readonly reviewItem: typeof facilityCredentialReviewItemFixture;
+    readonly reviewItem: typeof facilityCredentialReviewItemExample;
     readonly reviewSessionSnapshot: ReturnType<typeof initialReviewQueueSessionState>;
     readonly reviewedSnapshot: ReturnType<typeof initialReviewQueueSessionState>;
     readonly eventsToPersist: readonly ReviewSessionEvent[];

package/dist/examples/review-workbench/facility-credential-consumer.js

@@ -1,4 +1,4 @@
-import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
+import { facilityCredentialReviewItemExample } from "../../src/review-workbench/review-workbench-data.js";
 import { buildReviewItemPresentation, buildReviewResultPresentation, buildReviewSessionEvents, buildSurfaceProjectionPreview, deriveReviewSessionApplyResultForSnapshot, initialReviewQueueSessionState, persistReviewSessionEvents, } from "../../src/review-workbench/review-workbench.js";
 export const facilityCredentialPresentationAdapter = {
     labelForTarget: (target) => target === "operatingLicenseCredential"
@@ -46,17 +46,17 @@ export const facilityCredentialPresentationAdapter = {
 };
 export async function buildFacilityCredentialConsumerExample() {
     const reviewSessionSnapshot = {
-        ...initialReviewQueueSessionState([facilityCredentialReviewItemFixture]),
+        ...initialReviewQueueSessionState([facilityCredentialReviewItemExample]),
         actorId: "review-operator@example.test",
         reviewedAt: "2026-01-17T16:15:00.000Z",
     };
     const reviewedSnapshot = {
         ...reviewSessionSnapshot,
         decisionsByItemName: {
-            [facilityCredentialReviewItemFixture.metadata.name]: "accept-proposed",
+            [facilityCredentialReviewItemExample.metadata.name]: "accept-proposed",
         },
         notesByItemName: {
-            [facilityCredentialReviewItemFixture.metadata.name]: "Registry credential supersedes the managed snapshot.",
+            [facilityCredentialReviewItemExample.metadata.name]: "Registry credential supersedes the managed snapshot.",
         },
     };
     const eventsToPersist = buildReviewSessionEvents(reviewedSnapshot);
@@ -85,14 +85,14 @@ export async function buildFacilityCredentialConsumerExample() {
     if (!result) {
         throw new Error("Expected the reviewed credential snapshot to produce one review result.");
     }
-    const itemPresentation = buildReviewItemPresentation(facilityCredentialReviewItemFixture, facilityCredentialPresentationAdapter);
-    const resultPresentation = buildReviewResultPresentation(result, facilityCredentialReviewItemFixture, facilityCredentialPresentationAdapter);
-    const surfaceProjectionPreview = buildSurfaceProjectionPreview(facilityCredentialReviewItemFixture, result.reviewDecision, facilityCredentialPresentationAdapter);
+    const itemPresentation = buildReviewItemPresentation(facilityCredentialReviewItemExample, facilityCredentialPresentationAdapter);
+    const resultPresentation = buildReviewResultPresentation(result, facilityCredentialReviewItemExample, facilityCredentialPresentationAdapter);
+    const surfaceProjectionPreview = buildSurfaceProjectionPreview(facilityCredentialReviewItemExample, result.reviewDecision, facilityCredentialPresentationAdapter);
     if (!surfaceProjectionPreview) {
         throw new Error("Expected the reviewed credential result to produce a Surface projection preview.");
     }
     return {
-        reviewItem: facilityCredentialReviewItemFixture,
+        reviewItem: facilityCredentialReviewItemExample,
         reviewSessionSnapshot,
         reviewedSnapshot,
         eventsToPersist,

package/dist/examples/review-workbench/server-apply-consumer.d.ts

@@ -27,4 +27,4 @@ export declare function prepareFacilityCredentialServerApply(input: {
     readonly actorId: string;
     readonly appliedAt: string;
 }): FacilityCredentialApplyPreparation;
-export declare const facilityCredentialCurrentRecordFixture: FacilityCredentialRecord;
+export declare const facilityCredentialCurrentRecordExample: FacilityCredentialRecord;

package/dist/examples/review-workbench/server-apply-consumer.js

@@ -1,4 +1,4 @@
-import { facilityCredentialReviewItemFixture } from "../../src/review-workbench/review-workbench-data.js";
+import { facilityCredentialReviewItemExample } from "../../src/review-workbench/review-workbench-data.js";
 import { deriveReviewSessionApplyResultForSnapshot, } from "../../src/review-workbench/review-workbench.js";
 export function prepareFacilityCredentialServerApply(input) {
     const applyResult = deriveReviewSessionApplyResultForSnapshot({
@@ -40,8 +40,8 @@ export function prepareFacilityCredentialServerApply(input) {
         },
     };
 }
-export const facilityCredentialCurrentRecordFixture = {
+export const facilityCredentialCurrentRecordExample = {
     id: "facility-credential-record-1",
-    credential: facilityCredentialReviewItemFixture.spec.candidates.find((candidate) => candidate.role === "current")?.value,
+    credential: facilityCredentialReviewItemExample.spec.candidates.find((candidate) => candidate.role === "current")?.value,
     appliedReviewItemNames: [],
 };

package/dist/src/agent-utterance.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Agent-utterance producer profile — ADR 0003 step 6.
+ *
+ * This module implements Survey as a producer pointed at agent utterances
+ * instead of web sources. Each factual statement in agent prose is extracted
+ * as a candidate claim and run through the Inquiry pipeline.
+ *
+ * Integration point: surveyAgentUtterance is the clean entry point for
+ * consumers wanting to "spell-check" an agent's output for evidence. Flow-agent
+ * hook wiring (connecting this function to a live agent's output pipeline) is
+ * out of scope for this module and lives in the flow-agents repo.
+ *
+ * Hard constraint (ADR 0003 §4): nothing here silently decides. The
+ * UtteranceClaimExtractor is a pluggable interface; implementations may be
+ * deterministic or model-backed, but they are always extractors — their output
+ * has full provenance (excerpt, span, extractor name, confidence) and is
+ * run through the Inquiry pipeline rather than treated as authoritative.
+ */
+import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
+import type { CanonicalClaimTarget } from "@kontourai/surface";
+import type { Candidate, CandidateSet, Extraction, RawSource, SurveyInput } from "./types.js";
+import type { InquiryMapping } from "./inquiry-mapping.js";
+/**
+ * A single extracted statement from an utterance.
+ */
+export interface ExtractedStatement {
+    /** The canonical claim target this statement is about. */
+    target: CanonicalClaimTarget;
+    /** The value claimed (if parseable). */
+    value?: unknown;
+    /** The verbatim text segment that contains this claim. */
+    excerpt: string;
+    /** Character-offset span within the utterance (0-indexed). */
+    span?: {
+        start: number;
+        end: number;
+    };
+    /** Extractor confidence (0–1). */
+    confidence: number;
+}
+/**
+ * Pluggable interface for extracting canonical claim statements from
+ * agent-generated text.
+ *
+ * Implementations may be deterministic (like the reference extractor below),
+ * regex-based, NLP-based, or LLM-backed — but they are always extractors:
+ * their output carries full provenance and goes through the Inquiry pipeline
+ * rather than being treated as an authoritative answer.
+ */
+export interface UtteranceClaimExtractor {
+    name: string;
+    extract(utterance: string): ExtractedStatement[] | Promise<ExtractedStatement[]>;
+}
+/**
+ * Badge values for each extracted statement, derived from the inquiry outcome
+ * and the answer status.
+ *
+ * - "verified": inquiry matched/derived and answer status is "verified"
+ * - "assumed": inquiry matched/derived and answer status is "assumed"
+ * - "stale": inquiry matched/derived and answer status is "stale"
+ * - "disputed": inquiry matched/derived and answer status is "disputed"
+ * - "rejected": inquiry matched/derived and answer status is "rejected"
+ * - "unsupported": inquiry outcome is "unsupported" (no mapping or no registered claim)
+ */
+export type StatementBadge = "verified" | "assumed" | "stale" | "disputed" | "rejected" | "unsupported";
+export interface UtteranceStatement {
+    excerpt: string;
+    span?: {
+        start: number;
+        end: number;
+    };
+    target: CanonicalClaimTarget;
+    inquiryRecord: InquiryRecord;
+    badge: StatementBadge;
+}
+/**
+ * The result of surveying an agent utterance.
+ *
+ * source: the RawSource representing the utterance (kind: "agent-utterance").
+ * statements: per-statement verdicts, each with full provenance.
+ *
+ * This is the "spell-check for evidence" projection. Flow-agent hook wiring
+ * is out of scope for this module (lives in flow-agents repo).
+ */
+export interface UtteranceTrustReport {
+    source: RawSource;
+    statements: UtteranceStatement[];
+}
+/**
+ * Full set of Survey records generated for a single extracted statement.
+ * These are produced for provenance but not projected to Surface directly —
+ * the report is the consumer-facing artifact.
+ */
+export interface UtteranceStatementRecords {
+    extraction: Extraction;
+    candidate: Candidate;
+    candidateSet: CandidateSet;
+}
+/**
+ * Project an agent utterance and its extracted statements into the standard
+ * SurveyInput shape so they can flow into buildSurveyTrustBundle.
+ *
+ * Each extracted statement lands as:
+ *   RawSource (agent-utterance) → Extraction (with text-span locator) →
+ *   Candidate → CandidateSet (needs-review, no review outcome) → ClaimTarget
+ *
+ * Status discipline (ADR 0003 §4, to-surface.ts producer rules):
+ * - All claims project as "proposed" — unreviewed extractions are proposals,
+ *   never authoritative. assertProducerDiscipline forbids verified/assumed
+ *   without a review outcome.
+ * - agent-utterance is not a manual-entry source, so extraction.locator is
+ *   required. Span-located statements use text-span:start-end; span-less
+ *   statements use text-span derived from the excerpt offset in the utterance
+ *   (best-effort, 0-based).
+ *
+ * The returned SurveyInput can be passed directly to buildSurveyTrustBundle
+ * to produce a TrustBundle with full provenance in the Trust Bundle metadata.
+ *
+ * @param utterance - The raw agent utterance text.
+ * @param extracted - ExtractedStatements produced by a UtteranceClaimExtractor.
+ * @param context - agentId, extractor name, optional now timestamp.
+ */
+export declare function utteranceToSurveyInput(utterance: string, extracted: ExtractedStatement[], context: {
+    agentId: string;
+    extractorName: string;
+    now?: Date;
+    source?: string;
+}): SurveyInput;
+/**
+ * Survey an agent utterance, returning a trust report for each extracted claim.
+ *
+ * Steps:
+ * 1. Build a RawSource for the utterance (kind: "agent-utterance").
+ * 2. Run the extractor → project each statement into Survey records with full
+ *    provenance (excerpt, span locator, extractor name, confidence).
+ * 3. Resolve each extracted claim against the bundle via resolveInquiry or
+ *    resolveQuestion (if mappings are provided).
+ * 4. Return an UtteranceTrustReport with per-statement badges.
+ *
+ * This function is the integration point for consumers. Flow-agent hook wiring
+ * lives in the flow-agents repo.
+ */
+export declare function surveyAgentUtterance(utterance: string, extractor: UtteranceClaimExtractor, context: {
+    bundle: TrustBundle;
+    mappings?: InquiryMapping[];
+    rules?: DerivationRule[];
+    now?: Date;
+    agentId: string;
+}): Promise<UtteranceTrustReport>;
+/**
+ * Reference UtteranceClaimExtractor for tests.
+ *
+ * REFERENCE IMPLEMENTATION ONLY — not suitable for production extraction.
+ *
+ * Parsing strategy: looks for statements matching the pattern:
+ *   "<subjectId> <fieldOrBehavior> is <value>"
+ * or
+ *   "<subjectId> <fieldOrBehavior>: <value>"
+ *
+ * where subjectId and fieldOrBehavior are single words. This intentionally
+ * simple and transparent pattern lets tests be deterministic.
+ *
+ * The subjectType is always "unknown" since it cannot be inferred from text
+ * alone in this reference implementation.
+ */
+export declare const referenceUtteranceExtractor: UtteranceClaimExtractor;