@kontourai/survey 0.4.4 → 0.4.6

package/README.md

@@ -871,11 +871,18 @@ const learning = buildSurveyLearningProjections(surveyInput);
 const trustInput = buildSurveyTrustInput(surveyInput);
 ```
 
-Learning projections are product-neutral `learning.*` records. Survey currently
-emits `learning.comfort-zone` from structured `ReviewOutcome.withinComfortZone
-=== false` data and `learning.escalation` from unresolved `EscalationRecord`s,
-including unattached records that producer tooling can route but Surface cannot
-attach to a claim event.
+Learning projections are product-neutral `learning.*` records. Survey emits
+`learning.rejected-candidate` from structured candidate rejection data such as
+non-empty `Candidate.rejectionReason` values or a candidate-specific
+`ReviewOutcome.status === "rejected"` outcome with rationale. When both exist,
+Survey emits one rejected-candidate projection enriched with candidate and
+review outcome context.
+Ordinary rejected candidates do not emit `learning.comfort-zone`.
+
+Survey also emits `learning.comfort-zone` from structured
+`ReviewOutcome.withinComfortZone === false` data and `learning.escalation` from
+unresolved `EscalationRecord`s, including unattached records that producer
+tooling can route but Surface cannot attach to a claim event.
 
 These projections are producer/review workflow and evaluation signals. They are
 not claims about truth or veracity, not Surface claim status, not evidence, and

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

@@ -129,6 +129,144 @@ export declare const publicDirectoryReviewItemFixture: {
         reviewDecisionName: string;
     };
 };
+export declare const regulatedRuleConflictReviewItemFixture: {
+    apiVersion: "survey.kontourai.io/v1alpha1";
+    kind: "ReviewItem";
+    metadata: {
+        name: string;
+        labels: {
+            domain: string;
+        };
+        producer: {
+            displayName: string;
+            jurisdiction: string;
+            reportingPeriod: string;
+        };
+    };
+    spec: {
+        target: string;
+        selectedCandidateId: string;
+        candidateSetStatus: "conflict";
+        rationale: string;
+        projection: {
+            candidateSetId: string;
+        };
+        producerPolicy: {
+            decisionMode: string;
+            sourceAuthorityProjection: string;
+            feedbackTags: string[];
+        };
+        candidates: ({
+            id: string;
+            role: "current";
+            value: number;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "manual-entry";
+                observedAt: string;
+                locatorScheme: "structured-field";
+            };
+            locator: {
+                scheme: "structured-field";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "high";
+                evidenceType: "human_attestation";
+                evidenceMethod: "attestation";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+            };
+            producer: {
+                status: string;
+                sourceSection?: undefined;
+                sourcePage?: undefined;
+                sourceAuthority?: undefined;
+            };
+            sourceRank?: undefined;
+        } | {
+            id: string;
+            role: "proposed";
+            value: number;
+            confidence: number;
+            sourceRank: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "uploaded-document";
+                observedAt: string;
+                locatorScheme: "pdf";
+            };
+            locator: {
+                scheme: "pdf";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "high";
+                evidenceType: "policy_rule";
+                evidenceMethod: "extraction";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+            };
+            producer: {
+                sourceSection: string;
+                sourcePage: number;
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+                status?: undefined;
+            };
+        })[];
+    };
+    status: {
+        observedCandidateCount: number;
+        selectedCandidateId: string;
+    };
+};
 export declare const reviewWorkbenchQueueFixtures: (ReviewItem | {
     apiVersion: "survey.kontourai.io/v1alpha1";
     kind: "ReviewItem";
@@ -258,4 +396,141 @@ export declare const reviewWorkbenchQueueFixtures: (ReviewItem | {
         selectedCandidateId: string;
         reviewDecisionName: string;
     };
+} | {
+    apiVersion: "survey.kontourai.io/v1alpha1";
+    kind: "ReviewItem";
+    metadata: {
+        name: string;
+        labels: {
+            domain: string;
+        };
+        producer: {
+            displayName: string;
+            jurisdiction: string;
+            reportingPeriod: string;
+        };
+    };
+    spec: {
+        target: string;
+        selectedCandidateId: string;
+        candidateSetStatus: "conflict";
+        rationale: string;
+        projection: {
+            candidateSetId: string;
+        };
+        producerPolicy: {
+            decisionMode: string;
+            sourceAuthorityProjection: string;
+            feedbackTags: string[];
+        };
+        candidates: ({
+            id: string;
+            role: "current";
+            value: number;
+            confidence: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "manual-entry";
+                observedAt: string;
+                locatorScheme: "structured-field";
+            };
+            locator: {
+                scheme: "structured-field";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "high";
+                evidenceType: "human_attestation";
+                evidenceMethod: "attestation";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+            };
+            producer: {
+                status: string;
+                sourceSection?: undefined;
+                sourcePage?: undefined;
+                sourceAuthority?: undefined;
+            };
+            sourceRank?: undefined;
+        } | {
+            id: string;
+            role: "proposed";
+            value: number;
+            confidence: number;
+            sourceRank: number;
+            source: {
+                sourceId: string;
+                sourceRef: string;
+                kind: "uploaded-document";
+                observedAt: string;
+                locatorScheme: "pdf";
+            };
+            locator: {
+                scheme: "pdf";
+                locator: string;
+                excerpt: string;
+            };
+            extraction: {
+                extractionId: string;
+                target: string;
+                confidence: number;
+                extractor: string;
+                extractedAt: string;
+            };
+            claimTarget: {
+                claimId: string;
+                subjectType: string;
+                subjectId: string;
+                surface: string;
+                claimType: string;
+                fieldOrBehavior: string;
+                impactLevel: "high";
+                evidenceType: "policy_rule";
+                evidenceMethod: "extraction";
+                collectedBy: string;
+            };
+            projection: {
+                rawSourceId: string;
+                extractionId: string;
+                candidateSetId: string;
+                candidateId: string;
+                claimId: string;
+            };
+            producer: {
+                sourceSection: string;
+                sourcePage: number;
+                sourceAuthority: {
+                    authorityClass: string;
+                    declaredBy: string;
+                    scope: string;
+                };
+                status?: undefined;
+            };
+        })[];
+    };
+    status: {
+        observedCandidateCount: number;
+        selectedCandidateId: string;
+    };
 })[];

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

@@ -131,6 +131,142 @@ export const publicDirectoryReviewItemFixture = {
         reviewDecisionName: "public-directory-availability-operator-decision",
     },
 };
+export const regulatedRuleConflictReviewItemFixture = {
+    apiVersion: reviewResourceApiVersion,
+    kind: "ReviewItem",
+    metadata: {
+        name: "regulated-rule-conflict-standard-threshold",
+        labels: {
+            domain: "regulated-rule-source",
+        },
+        producer: {
+            displayName: "Regulated Rule Review",
+            jurisdiction: "example-jurisdiction",
+            reportingPeriod: "2026",
+        },
+    },
+    spec: {
+        target: "standardThreshold",
+        selectedCandidateId: "regulated-rule-conflict-standard-threshold:candidate:current",
+        candidateSetStatus: "conflict",
+        rationale: "A newly extracted source candidate conflicts with the currently managed rule value.",
+        projection: {
+            candidateSetId: "regulated-rule-conflict-standard-threshold:candidate-set",
+        },
+        producerPolicy: {
+            decisionMode: "keep-current",
+            sourceAuthorityProjection: "only-for-selected-source-backed-value",
+            feedbackTags: ["rule-conflict", "source-extraction-review"],
+        },
+        candidates: [
+            {
+                id: "regulated-rule-conflict-standard-threshold:candidate:current",
+                role: "current",
+                value: 15000,
+                confidence: 1,
+                source: {
+                    sourceId: "regulated-rule-conflict-standard-threshold:source:current",
+                    sourceRef: "survey-example://rules/example-jurisdiction/2026/standardThreshold",
+                    kind: "manual-entry",
+                    observedAt: "2026-06-03T00:00:00.000Z",
+                    locatorScheme: "structured-field",
+                },
+                locator: {
+                    scheme: "structured-field",
+                    locator: "managed-rules:path=standardThreshold",
+                    excerpt: "Current managed rule value.",
+                },
+                extraction: {
+                    extractionId: "regulated-rule-conflict-standard-threshold:extraction:current",
+                    target: "standardThreshold",
+                    confidence: 1,
+                    extractor: "example-rule-manager",
+                    extractedAt: "2026-06-03T00:00:00.000Z",
+                },
+                claimTarget: {
+                    claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.current",
+                    subjectType: "regulated-rule-source",
+                    subjectId: "example-jurisdiction:2026:standardThreshold",
+                    surface: "regulated.rules",
+                    claimType: "regulated.rule-source-value",
+                    fieldOrBehavior: "standardThreshold",
+                    impactLevel: "high",
+                    evidenceType: "human_attestation",
+                    evidenceMethod: "attestation",
+                    collectedBy: "example-rule-manager",
+                },
+                projection: {
+                    rawSourceId: "regulated-rule-conflict-standard-threshold:source:current",
+                    extractionId: "regulated-rule-conflict-standard-threshold:extraction:current",
+                    candidateSetId: "regulated-rule-conflict-standard-threshold:candidate-set",
+                    candidateId: "regulated-rule-conflict-standard-threshold:projection:current",
+                    claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.current",
+                },
+                producer: {
+                    status: "current-managed-value",
+                },
+            },
+            {
+                id: "regulated-rule-conflict-standard-threshold:candidate:proposed",
+                role: "proposed",
+                value: 16000,
+                confidence: 0.95,
+                sourceRank: 1,
+                source: {
+                    sourceId: "regulated-rule-conflict-standard-threshold:source:proposed",
+                    sourceRef: "https://example.test/regulatory-bulletins/2026-thresholds.pdf",
+                    kind: "uploaded-document",
+                    observedAt: "2026-06-03T00:30:00.000Z",
+                    locatorScheme: "pdf",
+                },
+                locator: {
+                    scheme: "pdf",
+                    locator: "pdf:page=12;section=Standard%20Threshold;path=standardThreshold",
+                    excerpt: "Example Individual Standard Threshold $16,000",
+                },
+                extraction: {
+                    extractionId: "regulated-rule-conflict-standard-threshold:extraction:proposed",
+                    target: "standardThreshold",
+                    confidence: 0.95,
+                    extractor: "example-rule-source-parser",
+                    extractedAt: "2026-06-03T00:30:00.000Z",
+                },
+                claimTarget: {
+                    claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.proposed",
+                    subjectType: "regulated-rule-source",
+                    subjectId: "example-jurisdiction:2026:standardThreshold",
+                    surface: "regulated.rules",
+                    claimType: "regulated.rule-source-value",
+                    fieldOrBehavior: "standardThreshold",
+                    impactLevel: "high",
+                    evidenceType: "policy_rule",
+                    evidenceMethod: "extraction",
+                    collectedBy: "example-rule-source-parser",
+                },
+                projection: {
+                    rawSourceId: "regulated-rule-conflict-standard-threshold:source:proposed",
+                    extractionId: "regulated-rule-conflict-standard-threshold:extraction:proposed",
+                    candidateSetId: "regulated-rule-conflict-standard-threshold:candidate-set",
+                    candidateId: "regulated-rule-conflict-standard-threshold:projection:proposed",
+                    claimId: "regulated-rule.example-jurisdiction.2026.standard-threshold.proposed",
+                },
+                producer: {
+                    sourceSection: "Standard Threshold",
+                    sourcePage: 12,
+                    sourceAuthority: {
+                        authorityClass: "official_publication",
+                        declaredBy: "Example regulatory source registry",
+                        scope: "standardThreshold rule value for example-jurisdiction 2026",
+                    },
+                },
+            },
+        ],
+    },
+    status: {
+        observedCandidateCount: 2,
+        selectedCandidateId: "regulated-rule-conflict-standard-threshold:candidate:current",
+    },
+};
 function queueFixture(name, target, currentValue, proposedValue, candidateSetStatus, feedbackTags) {
     return {
         ...publicDirectoryReviewItemFixture,
@@ -196,4 +332,5 @@ export const reviewWorkbenchQueueFixtures = [
     publicDirectoryReviewItemFixture,
     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,
 ];

package/dist/src/learning-projections.d.ts

@@ -1,6 +1,6 @@
 import type { SurveyInput } from "./types.js";
-export type LearningProjectionKind = "learning.comfort-zone" | "learning.escalation";
-export type LearningProjectionSignal = "comfort-zone.outside" | "escalation.unresolved";
+export type LearningProjectionKind = "learning.comfort-zone" | "learning.escalation" | "learning.rejected-candidate";
+export type LearningProjectionSignal = "comfort-zone.outside" | "escalation.unresolved" | "rejected-candidate.reason";
 export type LearningProjectionSeverity = "info" | "attention";
 export interface LearningProjection {
     id: string;

package/dist/src/learning-projections.js

@@ -1,7 +1,44 @@
 export function buildSurveyLearningProjections(input) {
     const claimsByCandidateSet = groupBy(input.claims, (claim) => claim.candidateSetId);
     const candidateSetTargets = new Map(input.candidateSets.map((candidateSet) => [candidateSet.id, candidateSet.target]));
+    const extractionsById = new Map(input.extractions.map((extraction) => [extraction.id, extraction]));
+    const rejectedReviewsByCandidate = groupBy(input.reviewOutcomes.filter((reviewOutcome) => reviewOutcome.status === "rejected" && reviewOutcome.candidateId), (reviewOutcome) => `${reviewOutcome.candidateSetId}:${reviewOutcome.candidateId}`);
     const projections = [];
+    for (const candidateSet of input.candidateSets) {
+        for (const candidate of candidateSet.candidates) {
+            const rejectedReviews = rejectedReviewsByCandidate.get(`${candidateSet.id}:${candidate.id}`) ?? [];
+            const candidateReason = normalizeText(candidate.rejectionReason);
+            const reviewOutcome = rejectedReviews[0];
+            const reviewRationale = normalizeText(reviewOutcome?.rationale);
+            const rejectionReason = candidateReason ?? reviewRationale;
+            if (!rejectionReason)
+                continue;
+            const claim = claimsByCandidateSet.get(candidateSet.id)?.find((candidateSetClaim) => candidateSetClaim.candidateId === candidate.id);
+            const extraction = extractionsById.get(candidate.extractionId);
+            projections.push({
+                id: `${candidateSet.id}.${candidate.id}.learning.rejected-candidate`,
+                kind: "learning.rejected-candidate",
+                source: input.source,
+                createdAt: reviewOutcome?.reviewedAt ?? extraction?.extractedAt ?? input.generatedAt,
+                target: candidateSet.target,
+                claimId: claim?.id,
+                reviewOutcomeId: reviewOutcome?.id,
+                signal: "rejected-candidate.reason",
+                severity: "info",
+                summary: `Rejected candidate reason: ${rejectionReason}`,
+                metadata: {
+                    rejectedCandidate: rejectedCandidateMetadata({
+                        candidateSet,
+                        candidate,
+                        extraction,
+                        reviewOutcome,
+                        claim,
+                        rejectionReason,
+                    }),
+                },
+            });
+        }
+    }
     for (const reviewOutcome of input.reviewOutcomes) {
         if (reviewOutcome.withinComfortZone !== false)
             continue;
@@ -48,6 +85,20 @@ export function buildSurveyLearningProjections(input) {
     }
     return projections;
 }
+function rejectedCandidateMetadata(input) {
+    return {
+        candidateId: input.candidate.id,
+        candidateSetId: input.candidateSet.id,
+        target: input.candidateSet.target,
+        rejectionReason: input.rejectionReason,
+        ...(input.reviewOutcome ? { reviewOutcomeId: input.reviewOutcome.id, reviewStatus: input.reviewOutcome.status } : {}),
+        ...(input.claim ? { claimId: input.claim.id } : {}),
+        ...(input.extraction ? { extractionId: input.extraction.id } : {}),
+        ...(input.candidateSet.selectedCandidateId ? { selectedCandidateId: input.candidateSet.selectedCandidateId } : {}),
+        ...(input.candidate.rejectionReason ? { candidateRejectionReason: input.candidate.rejectionReason } : {}),
+        ...(input.reviewOutcome?.rationale ? { reviewRationale: input.reviewOutcome.rationale } : {}),
+    };
+}
 function findClaimForReview(claims, reviewOutcome) {
     if (reviewOutcome.candidateId) {
         return claims.find((claim) => claim.candidateId === reviewOutcome.candidateId);
@@ -75,3 +126,7 @@ function groupBy(items, getKey) {
     }
     return map;
 }
+function normalizeText(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",