@kontourai/survey 0.1.5 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # Kontour Survey
 
-Survey is the producer-side contract for turning raw observations into
-Surface-ready trust records.
+Survey is the producer-side contract for turning producer observations into
+Surface-ready `TrustInput`.
 
 This repo is intentionally small right now. It is a proof package, not an
 ingestion platform:
@@ -10,8 +10,8 @@ ingestion platform:
 - Survey owns source, extraction, candidate, and review record shapes;
 - `buildSurveyTrustInput` projects those records into `@kontourai/surface`
   `TrustInput`;
-- Surface owns trust reporting, derivation, console projections, and downstream
-  transparency.
+- Surface owns Claim, Subject, Claim Type, Evidence, Status, Claim Dependency,
+  TrustInput, trust reporting, console projections, and downstream transparency.
 
 The first success criterion is that generic corrected-document and public-field
 fixtures can pass through Survey and produce valid Surface reports without
@@ -295,6 +295,22 @@ shared candidate set while rejecting conflicting duplicate ids. Duplicate
 conflict checks assume Survey records are JSON-shaped data, which is the same
 shape expected by Surface validation and reports.
 
+A candidate set with status `"conflict"` represents a Survey-side Candidate
+Conflict before review has resolved which candidate should win. When no review
+outcome overrides it, `buildSurveyTrustInput` projects the claim to Surface
+status `"disputed"` and records a `"candidate-conflict"` verification event.
+
+## Computed values
+
+Computed values are normal `ClaimTarget` entries in `claims`. Producers should
+link them to their inputs with Surface Claim Dependency fields:
+`derivedFrom` for simple claim-id links, or `derivationEdges` when the link
+needs method, role, support-strength, rationale, or metadata.
+
+Survey passes those fields through to Surface while keeping the same
+source -> extraction -> candidate -> review -> claim projection path. Surface
+owns dependency semantics such as recompute pressure and status ceilings.
+
 ## Product Boundary
 
 Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,

package/dist/fixtures/corrected-document-candidates.js

@@ -19,16 +19,22 @@ export const correctedDocumentCandidatesFixture = {
             checksum: "sha256:corrected",
             locatorScheme: "pdf",
         },
+        computationSource("current"),
+        computationSource("original"),
     ],
     extractions: [
         documentExtraction("original:amount", "document:source:original", "statement.totalAmount", 82000, "pdf:page=1;box=1"),
         documentExtraction("original:credit", "document:source:original", "statement.creditAmount", 8600, "pdf:page=1;box=2"),
         documentExtraction("corrected:amount", "document:source:corrected", "statement.totalAmount", 84000, "pdf:page=1;box=1"),
         documentExtraction("corrected:credit", "document:source:corrected", "statement.creditAmount", 9100, "pdf:page=1;box=2"),
+        computationExtraction("current", 84000, 9100),
+        computationExtraction("original", 82000, 8600),
     ],
     candidateSets: [
         documentCandidateSet("amount", "original:amount", 82000, "corrected:amount", 84000),
         documentCandidateSet("credit", "original:credit", 8600, "corrected:credit", 9100),
+        computationCandidateSet("current", 84000, 9100),
+        computationCandidateSet("original", 82000, 8600),
     ],
     reviewOutcomes: [],
     claims: [
@@ -36,58 +42,23 @@ export const correctedDocumentCandidatesFixture = {
         documentClaim("document.entity-1.statement.credit.original", "credit", "original:credit", "statement.creditAmount", "superseded"),
         documentClaim("document.entity-1.statement.amount.corrected", "amount", "corrected:amount", "statement.totalAmount", "proposed"),
         documentClaim("document.entity-1.statement.credit.corrected", "credit", "corrected:credit", "statement.creditAmount", "proposed"),
-    ],
-    derivedClaims: [
-        {
-            id: "document.entity-1.statement-position.current",
-            subjectType: "verified-record.period",
-            subjectId: "entity-1:2026",
-            surface: "document-review",
-            claimType: "derived-field",
-            fieldOrBehavior: "statementPosition",
-            value: {
-                totalAmount: 84000,
-                creditAmount: 9100,
-                position: "credit-present",
-            },
-            status: "proposed",
-            impactLevel: "high",
-            inputClaimIds: [
-                { claimId: "document.entity-1.statement.amount.corrected", role: "amount-input", supportStrength: "strong" },
-                { claimId: "document.entity-1.statement.credit.corrected", role: "credit-input", supportStrength: "strong" },
-            ],
-            createdAt: generatedAt,
-            updatedAt: generatedAt,
-            evidenceSummary: "Derived statement position from corrected source fields.",
-            sourceRef: "documents://entities/entity-1/periods/2026/resolved-fields/statement",
-            collectedBy: "survey-document-fixture",
-        },
-        {
-            id: "document.entity-1.statement-position.original",
-            subjectType: "verified-record.period",
-            subjectId: "entity-1:2026",
-            surface: "document-review",
-            claimType: "derived-field",
-            fieldOrBehavior: "statementPosition",
-            value: {
-                totalAmount: 82000,
-                creditAmount: 8600,
-                position: "credit-present",
-            },
-            status: "stale",
-            impactLevel: "high",
-            inputClaimIds: [
-                { claimId: "document.entity-1.statement.amount.original", role: "amount-input", supportStrength: "strong" },
-                { claimId: "document.entity-1.statement.credit.original", role: "credit-input", supportStrength: "strong" },
-            ],
-            createdAt: generatedAt,
-            updatedAt: generatedAt,
-            evidenceSummary: "Prior statement position derived from original source fields.",
-            sourceRef: "documents://entities/entity-1/periods/2026/resolved-fields/statement",
-            collectedBy: "survey-document-fixture",
-        },
+        computationClaim("current", "proposed", [
+            "document.entity-1.statement.amount.corrected",
+            "document.entity-1.statement.credit.corrected",
+        ]),
+        computationClaim("original", "stale", [
+            "document.entity-1.statement.amount.original",
+            "document.entity-1.statement.credit.original",
+        ]),
     ],
 };
+function statementPosition(totalAmount, creditAmount) {
+    return {
+        totalAmount,
+        creditAmount,
+        position: "credit-present",
+    };
+}
 function documentExtraction(id, sourceId, target, value, locator) {
     return {
         id: `document:extraction:${id}`,
@@ -126,6 +97,45 @@ function documentCandidateSet(target, originalId, originalValue, correctedId, co
         ],
     };
 }
+function computationSource(id) {
+    return {
+        id: `document:source:statement-position:${id}`,
+        kind: "manual-entry",
+        sourceRef: "documents://entities/entity-1/periods/2026/resolved-fields/statement",
+        observedAt: generatedAt,
+        locatorScheme: "structured-field",
+    };
+}
+function computationExtraction(id, totalAmount, creditAmount) {
+    return {
+        id: `document:extraction:statement-position:${id}`,
+        sourceId: `document:source:statement-position:${id}`,
+        target: "statementPosition",
+        value: statementPosition(totalAmount, creditAmount),
+        confidence: 0.96,
+        extractor: "statement-position-rule",
+        extractedAt: generatedAt,
+        excerpt: `${id} statement position from source fields.`,
+    };
+}
+function computationCandidateSet(id, totalAmount, creditAmount) {
+    return {
+        id: `document:candidates:statement-position:${id}`,
+        target: "statementPosition",
+        selectedCandidateId: `document:candidate:statement-position:${id}`,
+        status: "needs-review",
+        rationale: "Statement position is computed from statement amount and credit fields.",
+        candidates: [
+            {
+                id: `document:candidate:statement-position:${id}`,
+                extractionId: `document:extraction:statement-position:${id}`,
+                value: statementPosition(totalAmount, creditAmount),
+                confidence: 0.96,
+                sourceRank: 1,
+            },
+        ],
+    };
+}
 function documentClaim(id, target, candidateId, fieldOrBehavior, status) {
     return {
         id,
@@ -141,3 +151,29 @@ function documentClaim(id, target, candidateId, fieldOrBehavior, status) {
         collectedBy: "document-field-parser",
     };
 }
+function computationClaim(id, status, inputClaimIds) {
+    const roles = ["amount-input", "credit-input"];
+    return {
+        id: `document.entity-1.statement-position.${id}`,
+        candidateSetId: `document:candidates:statement-position:${id}`,
+        candidateId: `document:candidate:statement-position:${id}`,
+        subjectType: "verified-record.period",
+        subjectId: "entity-1:2026",
+        surface: "document-review",
+        claimType: "computed-field",
+        fieldOrBehavior: "statementPosition",
+        status,
+        impactLevel: "high",
+        evidenceType: "calculation_trace",
+        evidenceMethod: "validation",
+        collectedBy: "survey-document-fixture",
+        eventMethod: "rule-application",
+        derivedFrom: inputClaimIds,
+        derivationEdges: inputClaimIds.map((inputClaimId, index) => ({
+            inputClaimId,
+            method: "rule-application",
+            role: roles[index],
+            supportStrength: "strong",
+        })),
+    };
+}

package/dist/src/builder.d.ts

@@ -1,4 +1,4 @@
-import type { CandidateSet, ClaimTarget, DerivedClaimTarget, Extraction, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
+import type { CandidateSet, ClaimTarget, Extraction, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
 export interface SurveyInputBuilderArgs {
     source: string;
     generatedAt?: string;
@@ -58,14 +58,12 @@ export declare class SurveyInputBuilder {
     private readonly candidateSets;
     private readonly reviewOutcomes;
     private readonly claims;
-    private readonly derivedClaims;
     constructor(args: SurveyInputBuilderArgs);
     addRawSource(rawSource: RawSource): this;
     addExtraction(extraction: Extraction): this;
     addCandidateSet(candidateSet: CandidateSet): this;
     addReviewOutcome(reviewOutcome: ReviewOutcome): this;
     addClaim(claim: ClaimTarget): this;
-    addDerivedClaim(derivedClaim: DerivedClaimTarget): this;
     addClaimRecord(record: SurveyClaimRecord): this;
     addClaimRecords(records: SurveyClaimRecord[]): this;
     addObservation(observation: SurveyObservationInput): this;

package/dist/src/builder.js

@@ -6,7 +6,6 @@ export class SurveyInputBuilder {
     candidateSets = new Map();
     reviewOutcomes = new Map();
     claims = new Map();
-    derivedClaims = new Map();
     constructor(args) {
         this.source = args.source;
         this.generatedAt = args.generatedAt ?? new Date().toISOString();
@@ -31,10 +30,6 @@ export class SurveyInputBuilder {
         addUnique(this.claims, claim, "claim target");
         return this;
     }
-    addDerivedClaim(derivedClaim) {
-        addUnique(this.derivedClaims, derivedClaim, "derived claim target");
-        return this;
-    }
     addClaimRecord(record) {
         this.addRecordRawSource(record.rawSource);
         this.addExtraction(record.extraction);
@@ -66,7 +61,6 @@ export class SurveyInputBuilder {
             candidateSets: [...this.candidateSets.values()],
             reviewOutcomes: [...this.reviewOutcomes.values()],
             claims: [...this.claims.values()],
-            derivedClaims: [...this.derivedClaims.values()],
         };
     }
     addRecordCandidateSet(candidateSet) {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, DerivedClaimTarget, Extraction, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, Extraction, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
 export { buildSurveyTrustInput } from "./to-surface.js";

package/dist/src/to-surface.js

@@ -30,6 +30,8 @@ export function buildSurveyTrustInput(input) {
             createdAt,
             updatedAt,
             impactLevel: projection.impactLevel,
+            derivedFrom: projection.derivedFrom,
+            derivationEdges: projection.derivationEdges,
             confidenceBasis: {
                 sourceQuality: "moderate",
                 extractionConfidence: candidate.confidence ?? extraction.confidence,
@@ -82,9 +84,6 @@ export function buildSurveyTrustInput(input) {
             notes: review?.rationale ?? candidateSet.rationale,
         });
     }
-    for (const derived of input.derivedClaims ?? []) {
-        addDerivedClaim({ derived, claims, evidence, events });
-    }
     return {
         schemaVersion: 3,
         source: input.source,
@@ -94,50 +93,6 @@ export function buildSurveyTrustInput(input) {
         events,
     };
 }
-function addDerivedClaim(input) {
-    const { derived } = input;
-    input.claims.push({
-        id: derived.id,
-        subjectType: derived.subjectType,
-        subjectId: derived.subjectId,
-        surface: derived.surface,
-        claimType: derived.claimType,
-        fieldOrBehavior: derived.fieldOrBehavior,
-        value: derived.value,
-        status: derived.status,
-        createdAt: derived.createdAt,
-        updatedAt: derived.updatedAt,
-        impactLevel: derived.impactLevel,
-        derivationEdges: derived.inputClaimIds.map((edge) => ({
-            inputClaimId: edge.claimId,
-            method: "rule-application",
-            role: edge.role,
-            supportStrength: edge.supportStrength,
-        })),
-        metadata: derived.metadata,
-    });
-    const evidenceId = `${derived.id}.evidence.calculation`;
-    input.evidence.push({
-        id: evidenceId,
-        claimId: derived.id,
-        evidenceType: "calculation_trace",
-        method: "validation",
-        sourceRef: derived.sourceRef,
-        excerptOrSummary: derived.evidenceSummary,
-        observedAt: derived.updatedAt,
-        collectedBy: derived.collectedBy,
-    });
-    input.events.push({
-        id: `${derived.id}.event.${derived.status}`,
-        claimId: derived.id,
-        status: derived.status,
-        actor: derived.collectedBy,
-        method: "rule-application",
-        evidenceIds: [evidenceId],
-        createdAt: derived.updatedAt,
-        verifiedAt: derived.status === "verified" ? derived.updatedAt : undefined,
-    });
-}
 function statusFor(input) {
     if (input.review)
         return input.review.status;

package/dist/src/types.d.ts

@@ -1,4 +1,4 @@
-import type { ConfidenceBasis, EvidenceMethod, EvidenceType, ImpactLevel, TrustStatus } from "@kontourai/surface";
+import type { ConfidenceBasis, DerivationEdge, EvidenceMethod, EvidenceType, ImpactLevel, TrustStatus } from "@kontourai/surface";
 export type RawSourceKind = "uploaded-document" | "web-page" | "api-record" | "manual-entry";
 export type LocatorScheme = "pdf" | "text" | "html" | "structured-field";
 export interface RawSource {
@@ -70,33 +70,13 @@ export interface ClaimTarget {
     evidenceType?: EvidenceType;
     evidenceMethod?: EvidenceMethod;
     confidenceBasis?: ConfidenceBasis;
+    derivedFrom?: string[];
+    derivationEdges?: DerivationEdge[];
     collectedBy: string;
     actor?: string;
     eventMethod?: string;
     metadata?: Record<string, unknown>;
 }
-export interface DerivedClaimTarget {
-    id: string;
-    subjectType: string;
-    subjectId: string;
-    surface: string;
-    claimType: string;
-    fieldOrBehavior: string;
-    value: unknown;
-    status: TrustStatus;
-    impactLevel: ImpactLevel;
-    inputClaimIds: Array<{
-        claimId: string;
-        role?: string;
-        supportStrength?: "weak" | "moderate" | "strong";
-    }>;
-    createdAt: string;
-    updatedAt: string;
-    evidenceSummary: string;
-    sourceRef: string;
-    collectedBy: string;
-    metadata?: Record<string, unknown>;
-}
 export interface SurveyInput {
     source: string;
     generatedAt: string;
@@ -105,5 +85,4 @@ export interface SurveyInput {
     candidateSets: CandidateSet[];
     reviewOutcomes: ReviewOutcome[];
     claims: ClaimTarget[];
-    derivedClaims?: DerivedClaimTarget[];
 }

package/package.json

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