@kontourai/survey 0.4.23 → 0.5.0

package/dist/src/inquiry-mapping.js

@@ -0,0 +1,385 @@
+/**
+ * Inquiry mapping — ADR 0003 step 5.
+ *
+ * This module implements the "memoize the mapping, never the answer" principle.
+ * A MappingProposal is a reviewable record produced by a pluggable MappingProposer.
+ * Proposals flow through Survey's existing candidate → review machinery.
+ * The durable artifact after review is an InquiryMapping.
+ * Answers always recompute live from the TrustBundle.
+ *
+ * Nothing here silently decides. Exact canonical-form matching is the only thing
+ * that resolves without review. A proposer may suggest that a question maps to a
+ * registered claim or rule — but every suggestion lands as a MappingProposal with
+ * provenance before it counts. (ADR 0003 §4)
+ *
+ * Integration point: resolveQuestion is the entry point for consumers checking
+ * whether a cached mapping already covers a question. Flow-agent hook wiring
+ * (connecting this to an agent's output pipeline) is out of scope for this module
+ * and lives in the flow-agents repo.
+ */
+import { resolveInquiry } from "@kontourai/surface";
+// ---------------------------------------------------------------------------
+// Question normalization
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic normalization for question strings.
+ *
+ * Rules:
+ * - Lowercase
+ * - Collapse internal whitespace runs to a single space
+ * - Trim leading/trailing whitespace
+ * - Strip terminal punctuation (. ? ! , ;) from the end
+ *
+ * This is exact normalized-text memoization, not semantic matching.
+ * Two questions that differ only in case, whitespace, or trailing punctuation
+ * are considered the same question.  Questions with different wording but the
+ * same intent are NOT matched here; a MappingProposer handles that.
+ */
+export function normalizeQuestion(question) {
+    return question
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/[.?!,;]+$/u, "");
+}
+// ---------------------------------------------------------------------------
+// Proposal → CandidateSet projection
+// ---------------------------------------------------------------------------
+/**
+ * Project an array of proposals for a single question into Survey's existing
+ * Candidate / CandidateSet shapes so they flow through the existing review
+ * machinery rather than a parallel system.
+ *
+ * Status rules:
+ * - All proposals agree on the same target/ruleId → "needs-review"
+ * - Proposals disagree (more than one distinct resolved target/rule) → "conflict"
+ * - Empty proposals → "needs-review" with empty candidates
+ *
+ * The CandidateSet target is the normalized question; each Candidate carries
+ * the proposal id as extractionId and the proposal metadata.
+ */
+export function proposalsToCandidateSet(question, proposals) {
+    const normalized = normalizeQuestion(question);
+    const candidates = proposals.map((proposal) => ({
+        id: `mapping-candidate.${proposal.id}`,
+        extractionId: proposal.id,
+        value: proposal.proposedTarget ?? proposal.proposedRuleId ?? null,
+        confidence: proposal.confidence,
+        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,
+            },
+        },
+    }));
+    // 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: {
+            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
+// ---------------------------------------------------------------------------
+/**
+ * Turn a Survey ReviewOutcome on a mapping candidate set into a durable
+ * InquiryMapping record.
+ *
+ * The candidateSet must have been built by proposalsToCandidateSet.
+ * The reviewOutcome's candidateId must match one of the candidates.
+ */
+export function applyMappingReview(candidateSet, reviewOutcome) {
+    const normalized = candidateSet.target;
+    // Find the reviewed candidate
+    const candidateId = reviewOutcome.candidateId ?? candidateSet.selectedCandidateId ?? candidateSet.candidates[0]?.id;
+    const candidate = candidateSet.candidates.find((c) => c.id === candidateId);
+    if (!candidate) {
+        throw new Error(`applyMappingReview: no candidate found for id ${candidateId ?? "<none>"}`);
+    }
+    const meta = candidate.metadata?.mappingProposal;
+    const proposalId = meta?.proposalId ?? candidate.extractionId;
+    const status = reviewOutcome.status === "verified" || reviewOutcome.status === "assumed" || reviewOutcome.status === "rejected"
+        ? reviewOutcome.status
+        : "rejected";
+    return {
+        id: `inquiry-mapping.${normalized}`,
+        normalizedQuestion: normalized,
+        target: meta?.proposedTarget,
+        ruleId: meta?.proposedRuleId,
+        status: status,
+        reviewedBy: reviewOutcome.actor ?? "unknown",
+        reviewedAt: reviewOutcome.reviewedAt ?? new Date().toISOString(),
+        rationale: reviewOutcome.rationale,
+        withinComfortZone: reviewOutcome.withinComfortZone,
+        proposalId,
+    };
+}
+/**
+ * Apply an auto-accept policy to a list of proposals, returning InquiryMappings.
+ *
+ * Proposals at or above minConfidence → status "assumed", withinComfortZone: true
+ * Proposals below minConfidence → return a "needs-review" mapping (not yet durable)
+ *
+ * Only non-conflicting proposals are auto-accepted. If proposals disagree, they
+ * need human review regardless of confidence.
+ *
+ * Returns an array of InquiryMappings (only for accepted proposals).
+ */
+export function applyAutoAcceptPolicy(proposals, policy) {
+    if (proposals.length === 0)
+        return [];
+    // If proposals disagree, none can be auto-accepted
+    if (proposals.length > 1 && proposalsDisagree(proposals))
+        return [];
+    return proposals
+        .filter((p) => 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",
+        reviewedAt: proposal.proposedAt,
+        rationale: `Auto-accepted: confidence ${proposal.confidence} >= threshold ${policy.minConfidence}. ${proposal.rationale}`,
+        withinComfortZone: true,
+        proposalId: proposal.id,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Mapping lookup
+// ---------------------------------------------------------------------------
+/**
+ * Look up an InquiryMapping for a question by exact normalized-text match.
+ *
+ * Rejected mappings are remembered but never resolve: this function returns
+ * undefined for rejected mappings so callers treat the question as a miss.
+ * To check whether a question was previously rejected (and should not be
+ * re-proposed), call lookupRejectedMapping.
+ */
+export function lookupMapping(mappings, question) {
+    const normalized = normalizeQuestion(question);
+    const match = mappings.find((m) => m.normalizedQuestion === normalized);
+    if (!match)
+        return undefined;
+    // Rejected mappings are remembered but never resolve
+    if (match.status === "rejected")
+        return undefined;
+    return match;
+}
+/**
+ * Check whether a question was previously rejected.
+ * Rejected mappings prevent re-proposing: if this returns a mapping, the
+ * question should not be sent to a proposer again without human escalation.
+ */
+export function lookupRejectedMapping(mappings, question) {
+    const normalized = normalizeQuestion(question);
+    return mappings.find((m) => m.normalizedQuestion === normalized && m.status === "rejected");
+}
+// ---------------------------------------------------------------------------
+// Live question resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a natural-language question against a TrustBundle.
+ *
+ * On mapping hit (verified or assumed): constructs a Surface Inquiry from the
+ * mapped target/rule and returns resolveInquiry(...) — answers always recompute
+ * live from the current bundle state; the mapping is memoized, not the answer.
+ *
+ * On miss (no mapping, or rejected mapping): returns an InquiryRecord with
+ * outcome "unsupported" so the gap is honest and recordable.
+ *
+ * This function is the clean integration point for consumers. Flow-agent hook
+ * wiring (connecting this to an agent's output pipeline) lives in the
+ * flow-agents repo.
+ */
+export function resolveQuestion(bundle, question, options) {
+    const { mappings, rules, now, askedBy } = options;
+    const normalized = normalizeQuestion(question);
+    const mapping = lookupMapping(mappings, question);
+    const askedAt = (now ?? new Date()).toISOString();
+    const inquiryId = `inquiry.${normalized}.${askedAt}`;
+    if (!mapping) {
+        // No mapping or rejected: return honest unsupported record
+        return {
+            id: inquiryId,
+            inquiry: {
+                id: inquiryId,
+                question,
+                askedBy,
+                askedAt,
+            },
+            outcome: "unsupported",
+            resolutionPath: { claimIds: [] },
+            inputSnapshot: [],
+            statusFunctionVersion: "1",
+            resolvedAt: askedAt,
+        };
+    }
+    // Build a Surface Inquiry from the mapping
+    const inquiry = {
+        id: inquiryId,
+        question,
+        target: mapping.target,
+        askedBy,
+        askedAt,
+        metadata: {
+            inquiryMappingId: mapping.id,
+            normalizedQuestion: normalized,
+        },
+    };
+    return resolveInquiry(bundle, inquiry, { now, rules });
+}
+// ---------------------------------------------------------------------------
+// Review workbench integration
+// ---------------------------------------------------------------------------
+/**
+ * Build ReviewItem records for the existing review workbench from a list of
+ * mapping candidate sets.
+ *
+ * Follow the existing ReviewItem contract exactly. This helper produces
+ * ReviewItem payloads so mapping proposals can be reviewed through the same
+ * workbench as other Survey candidates.
+ */
+export function buildMappingReviewItems(candidateSets) {
+    return candidateSets.map(({ candidateSet, candidates }) => ({
+        apiVersion: "survey.kontourai.io/v1alpha1",
+        kind: "ReviewItem",
+        metadata: {
+            name: candidateSet.id,
+            labels: { "survey.kontourai.io/kind": "inquiry-mapping" },
+        },
+        spec: {
+            target: candidateSet.target,
+            candidates: candidates.map((candidate) => {
+                const meta = candidate.metadata?.mappingProposal;
+                const targetOrRule = meta?.proposedTarget
+                    ? `${meta.proposedTarget.subjectType}/${meta.proposedTarget.subjectId}/${meta.proposedTarget.fieldOrBehavior}`
+                    : `rule:${meta?.proposedRuleId ?? "unknown"}`;
+                return {
+                    id: candidate.id,
+                    role: "proposed",
+                    value: candidate.value,
+                    confidence: candidate.confidence,
+                    source: {
+                        sourceRef: `inquiry-question:${candidateSet.target}`,
+                        kind: "inquiry-question",
+                        observedAt: meta?.proposedAt ?? new Date().toISOString(),
+                        locatorScheme: "text",
+                    },
+                    extraction: {
+                        target: targetOrRule,
+                        confidence: meta?.confidence,
+                        extractor: meta?.proposedBy ?? "unknown",
+                        extractedAt: meta?.proposedAt ?? new Date().toISOString(),
+                    },
+                    claimTarget: {
+                        subjectType: meta?.proposedTarget?.subjectType ?? "inquiry",
+                        subjectId: meta?.proposedTarget?.subjectId ?? candidateSet.target,
+                        surface: "inquiry.mapping",
+                        claimType: "inquiry-mapping",
+                        fieldOrBehavior: meta?.proposedTarget?.fieldOrBehavior ?? meta?.proposedRuleId ?? "unknown",
+                        impactLevel: "low",
+                    },
+                    projection: {
+                        candidateSetId: candidateSet.id,
+                        candidateId: candidate.id,
+                    },
+                };
+            }),
+            candidateSetStatus: candidateSet.status,
+            rationale: candidateSet.rationale,
+        },
+        status: {
+            observedCandidateCount: candidates.length,
+        },
+    }));
+}
+// ---------------------------------------------------------------------------
+// Reference proposer (deterministic, for tests — not for production use)
+// ---------------------------------------------------------------------------
+/**
+ * Reference MappingProposer for tests.
+ *
+ * REFERENCE IMPLEMENTATION ONLY — not suitable for production matching.
+ *
+ * Matching strategy: a question maps to a claim if it contains both the
+ * claim's subjectId and fieldOrBehavior as token substrings (case-insensitive,
+ * space-delimited token match). This is intentionally simple and transparent
+ * so tests can be deterministic.
+ */
+export const referenceMappingProposer = {
+    name: "reference-mapping-proposer",
+    propose(question, context) {
+        const q = question.toLowerCase();
+        const proposals = [];
+        const now = new Date().toISOString();
+        if (context.bundle) {
+            for (const claim of context.bundle.claims) {
+                const subjectTokens = claim.subjectId.toLowerCase().split(/[\s\-_.:/]+/);
+                const fieldTokens = claim.fieldOrBehavior.toLowerCase().split(/[\s\-_.:/]+/);
+                const subjectMatch = subjectTokens.some((tok) => tok.length > 2 && q.includes(tok));
+                const fieldMatch = fieldTokens.some((tok) => tok.length > 2 && q.includes(tok));
+                if (subjectMatch && fieldMatch) {
+                    const proposalId = `proposal.ref.${claim.subjectId}.${claim.fieldOrBehavior}.${Date.now()}`;
+                    proposals.push({
+                        id: proposalId,
+                        question,
+                        proposedTarget: {
+                            subjectType: claim.subjectType,
+                            subjectId: claim.subjectId,
+                            fieldOrBehavior: claim.fieldOrBehavior,
+                            qualifiers: claim.qualifiers,
+                        },
+                        confidence: 0.75,
+                        rationale: `Reference proposer: question contains subjectId token and fieldOrBehavior token for claim ${claim.id}.`,
+                        proposedBy: "reference-mapping-proposer",
+                        proposedAt: now,
+                    });
+                }
+            }
+        }
+        if (context.rules) {
+            for (const rule of context.rules) {
+                const ruleTokens = rule.name.toLowerCase().split(/[\s\-_.:/]+/);
+                const ruleMatch = ruleTokens.some((tok) => tok.length > 2 && q.includes(tok));
+                if (ruleMatch) {
+                    const proposalId = `proposal.ref.rule.${rule.id}.${Date.now()}`;
+                    proposals.push({
+                        id: proposalId,
+                        question,
+                        proposedRuleId: rule.id,
+                        confidence: 0.65,
+                        rationale: `Reference proposer: question contains rule name token for rule ${rule.id}.`,
+                        proposedBy: "reference-mapping-proposer",
+                        proposedAt: now,
+                    });
+                }
+            }
+        }
+        return proposals;
+    },
+};

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

@@ -1,4 +1,4 @@
-import { publicDirectoryReviewItemFixture, reviewWorkbenchQueueFixtures } from "./review-workbench-data.js";
+import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
 import { reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
@@ -22,7 +22,7 @@ export const workbenchDecisionDefinitions = {
         status: "rejected",
     },
 };
-export function initialReviewWorkbenchState(item = publicDirectoryReviewItemFixture) {
+export function initialReviewWorkbenchState(item = publicDirectoryReviewItemExample) {
     return {
         item,
         note: "",
@@ -31,7 +31,7 @@ export function initialReviewWorkbenchState(item = publicDirectoryReviewItemFixt
         actorId: "review-workbench-operator",
     };
 }
-export function initialReviewQueueSessionState(items = reviewWorkbenchQueueFixtures) {
+export function initialReviewQueueSessionState(items = reviewWorkbenchQueueExamples) {
     return {
         items,
         activeItemName: items[0]?.metadata.name ?? "",

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

@@ -109,7 +109,7 @@ function portableAuthorityTrace(value) {
         return {
             status: "provided",
             label: "Portable authority trace provided",
-            detail: `${value.length} authority trace entr${value.length === 1 ? "y" : "ies"} supplied by the fixture.`,
+            detail: `${value.length} authority trace entr${value.length === 1 ? "y" : "ies"} supplied by the example.`,
         };
     }
     return {

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

@@ -1,5 +1,5 @@
 import { type ReviewItem } from "../review-resource.js";
-export declare const publicDirectoryReviewItemFixture: {
+export declare const publicDirectoryReviewItemExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {
@@ -129,7 +129,7 @@ export declare const publicDirectoryReviewItemFixture: {
         reviewDecisionName: string;
     };
 };
-export declare const regulatedRuleConflictReviewItemFixture: {
+export declare const regulatedRuleConflictReviewItemExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {
@@ -267,7 +267,7 @@ export declare const regulatedRuleConflictReviewItemFixture: {
         selectedCandidateId: string;
     };
 };
-export declare const facilityCredentialReviewItemFixture: {
+export declare const facilityCredentialReviewItemExample: {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {
@@ -425,7 +425,7 @@ export declare const facilityCredentialReviewItemFixture: {
         selectedCandidateId: string;
     };
 };
-export declare const reviewWorkbenchQueueFixtures: (ReviewItem | {
+export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
     metadata: {

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

@@ -1,7 +1,7 @@
 import { reviewResourceApiVersion } from "../review-resource.js";
-// Browser-safe mirror of fixtures/public-directory-review-resource.ts.
-// scripts/check-review-workbench.cjs fails if this data drifts from the canonical fixture.
-export const publicDirectoryReviewItemFixture = {
+// Browser-safe mirror of example-data/public-directory-review-resource.ts.
+// scripts/check-review-workbench.cjs fails if this data drifts from the canonical example.
+export const publicDirectoryReviewItemExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewItem",
     metadata: {
@@ -131,7 +131,7 @@ export const publicDirectoryReviewItemFixture = {
         reviewDecisionName: "public-directory-availability-operator-decision",
     },
 };
-export const regulatedRuleConflictReviewItemFixture = {
+export const regulatedRuleConflictReviewItemExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewItem",
     metadata: {
@@ -267,7 +267,7 @@ export const regulatedRuleConflictReviewItemFixture = {
         selectedCandidateId: "regulated-rule-conflict-standard-threshold:candidate:current",
     },
 };
-export const facilityCredentialReviewItemFixture = {
+export const facilityCredentialReviewItemExample = {
     apiVersion: reviewResourceApiVersion,
     kind: "ReviewItem",
     metadata: {
@@ -424,21 +424,21 @@ export const facilityCredentialReviewItemFixture = {
 };
 function queueFixture(name, target, currentValue, proposedValue, candidateSetStatus, feedbackTags) {
     return {
-        ...publicDirectoryReviewItemFixture,
+        ...publicDirectoryReviewItemExample,
         metadata: {
-            ...publicDirectoryReviewItemFixture.metadata,
+            ...publicDirectoryReviewItemExample.metadata,
             name,
         },
         spec: {
-            ...publicDirectoryReviewItemFixture.spec,
+            ...publicDirectoryReviewItemExample.spec,
             target,
             selectedCandidateId: `${name}:candidate:current`,
             candidateSetStatus,
             producerPolicy: {
                 feedbackTags,
             },
-            rationale: `Fixture-backed local review queue item for ${target}.`,
-            candidates: publicDirectoryReviewItemFixture.spec.candidates.map((candidate) => {
+            rationale: `Example-backed local review queue item for ${target}.`,
+            candidates: publicDirectoryReviewItemExample.spec.candidates.map((candidate) => {
                 const role = candidate.role ?? "candidate";
                 const value = role === "proposed" ? proposedValue : currentValue;
                 return {
@@ -475,17 +475,17 @@ function queueFixture(name, target, currentValue, proposedValue, candidateSetSta
             }),
         },
         status: {
-            observedCandidateCount: publicDirectoryReviewItemFixture.status?.observedCandidateCount,
+            observedCandidateCount: publicDirectoryReviewItemExample.status?.observedCandidateCount,
             selectedCandidateId: `${name}:candidate:current`,
             reviewDecisionName: candidateSetStatus === "resolved" ? `${name}-resolved-decision` : undefined,
         },
     };
 }
-export const reviewWorkbenchQueueFixtures = [
+export const reviewWorkbenchQueueExamples = [
     queueFixture("public-directory-hours", "hours", "Weekdays 9am-5pm", "Weekdays 8am-6pm", "needs-review", ["hours-change", "crawler-suggested"]),
     queueFixture("public-directory-phone", "phoneNumber", "+1-555-0100", "+1-555-0199", "needs-review", ["contact-field", "source-conflict"]),
-    publicDirectoryReviewItemFixture,
+    publicDirectoryReviewItemExample,
     queueFixture("public-directory-address", "streetAddress", "100 Main Street", "102 Main Street", "needs-review", ["address-change", "producer-escalation-candidate"]),
     queueFixture("public-directory-license", "licenseStatus", "ACTIVE", "EXPIRED", "escalated", ["licensing", "manual-review-required"]),
-    regulatedRuleConflictReviewItemFixture,
+    regulatedRuleConflictReviewItemExample,
 ];