@kontourai/survey 0.1.5 → 0.2.1

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
@@ -64,6 +64,60 @@ const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
 const report = buildTrustReport(trustInput);
 ```
 
+## Raw sources
+
+Use raw-source helpers when a producer wants Survey to shape source identity
+before building observations. The helpers do not fetch, crawl, parse, or judge
+the source; they only produce stable `RawSource` records with explicit source
+references, observed times, locator schemes, checksums, and producer metadata.
+
+```ts
+import {
+  apiRecordSource,
+  fieldObservation,
+  SurveyInputBuilder,
+} from "@kontourai/survey";
+
+const rawSource = apiRecordSource({
+  sourceRef: "example-records://entity/entity-123",
+  observedAt: new Date().toISOString(),
+  checksum: "abc123",
+  metadata: {
+    provider: "example-records",
+  },
+});
+
+const surveyInput = new SurveyInputBuilder({ source: "example-producer:run-1" })
+  .addObservation(fieldObservation({
+    id: "entity-123.status.current",
+    field: "registrationStatus",
+    value: "ACTIVE",
+    rawSource,
+    extraction: {
+      confidence: 0.97,
+      locator: "json:$.registrationStatus",
+      extractor: "example-extractor",
+      extractedAt: new Date().toISOString(),
+    },
+    claim: {
+      subjectType: "public-record.entity",
+      subjectId: "entity-123",
+      surface: "example.profile",
+      claimType: "public-data.field",
+      status: "proposed",
+      impactLevel: "medium",
+      collectedBy: "example-extractor",
+    },
+  }))
+  .build();
+```
+
+Survey exports `uploadedDocumentSource`, `apiRecordSource`, `webPageSource`,
+and `manualEntrySource`. Producer-provided `id` values are preserved; otherwise
+Survey derives a stable id from source kind and `sourceRef`. Bare checksum
+values are normalized to `sha256:<value>`, while already-prefixed checksum
+values are preserved. Producer metadata is copied through to Surface evidence.
+
 ## Field observations
 
 Use `fieldObservation` when a producer wants to describe one scalar field value
@@ -295,6 +349,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";
@@ -6,3 +6,5 @@ export { fieldObservation } from "./field-observation.js";
 export type { FieldObservationInput } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export type { RepeatedObservationInput } from "./repeated-observation.js";
+export { apiRecordSource, manualEntrySource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";
+export type { ApiRecordSourceInput, ChecksumInput, ManualEntrySourceInput, RawSourceInput, UploadedDocumentSourceInput, WebPageSourceInput, } from "./raw-source.js";

package/dist/src/index.js

@@ -2,3 +2,4 @@ export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
+export { apiRecordSource, manualEntrySource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";

package/dist/src/raw-source.d.ts

@@ -0,0 +1,31 @@
+import type { LocatorScheme, RawSource } from "./types.js";
+export type ChecksumInput = string | {
+    algorithm?: string;
+    value: string;
+};
+export interface RawSourceInput {
+    id?: string;
+    sourceRef: string;
+    observedAt: string;
+    fetchedAt?: string;
+    checksum?: ChecksumInput;
+    locatorScheme: LocatorScheme;
+    metadata?: Record<string, unknown>;
+}
+export interface UploadedDocumentSourceInput extends RawSourceInput {
+    locatorScheme: LocatorScheme;
+}
+export interface ApiRecordSourceInput extends Omit<RawSourceInput, "locatorScheme"> {
+    locatorScheme?: LocatorScheme;
+}
+export interface WebPageSourceInput extends Omit<RawSourceInput, "locatorScheme"> {
+    locatorScheme?: LocatorScheme;
+}
+export interface ManualEntrySourceInput extends Omit<RawSourceInput, "checksum" | "locatorScheme"> {
+    checksum?: ChecksumInput;
+    locatorScheme?: LocatorScheme;
+}
+export declare function uploadedDocumentSource(input: UploadedDocumentSourceInput): RawSource;
+export declare function apiRecordSource(input: ApiRecordSourceInput): RawSource;
+export declare function webPageSource(input: WebPageSourceInput): RawSource;
+export declare function manualEntrySource(input: ManualEntrySourceInput): RawSource;

package/dist/src/raw-source.js

@@ -0,0 +1,48 @@
+export function uploadedDocumentSource(input) {
+    return rawSource("uploaded-document", input);
+}
+export function apiRecordSource(input) {
+    return rawSource("api-record", {
+        locatorScheme: "structured-field",
+        ...input,
+    });
+}
+export function webPageSource(input) {
+    return rawSource("web-page", {
+        locatorScheme: "html",
+        ...input,
+    });
+}
+export function manualEntrySource(input) {
+    return rawSource("manual-entry", {
+        locatorScheme: "structured-field",
+        ...input,
+    });
+}
+function rawSource(kind, input) {
+    return {
+        id: input.id ?? sourceId(kind, input.sourceRef),
+        kind,
+        sourceRef: input.sourceRef,
+        observedAt: input.observedAt,
+        fetchedAt: input.fetchedAt,
+        checksum: normalizeChecksum(input.checksum),
+        locatorScheme: input.locatorScheme,
+        metadata: input.metadata,
+    };
+}
+function sourceId(kind, sourceRef) {
+    return `${kind}:${sourceRef}`;
+}
+function normalizeChecksum(checksum) {
+    if (!checksum)
+        return undefined;
+    if (typeof checksum === "string") {
+        if (checksum.includes(":"))
+            return checksum;
+        return `sha256:${checksum}`;
+    }
+    if (checksum.value.includes(":"))
+        return checksum.value;
+    return `${checksum.algorithm ?? "sha256"}:${checksum.value}`;
+}

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.1",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",