@kontourai/survey 0.1.1

package/README.md

@@ -0,0 +1,80 @@
+# Kontour Survey
+
+Survey is the producer-side contract for turning raw observations into
+Surface-ready trust records.
+
+This repo is intentionally small right now. It is a proof package, not an
+ingestion platform:
+
+- producers own acquisition, parsing, ranking, review UX, and vertical policy;
+- 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.
+
+The first success criterion is that generic corrected-document and public-field
+fixtures can pass through Survey and produce valid Surface reports without
+Survey absorbing vertical policy.
+
+## Quickstart
+
+```ts
+import { buildTrustReport, validateTrustInput } from "@kontourai/surface";
+import { buildSurveyTrustInput, SurveyInputBuilder } from "@kontourai/survey";
+
+const surveyInput = new SurveyInputBuilder({
+  source: "example-producer:run-1",
+})
+  .addObservation({
+    id: "listing-123.availability.current",
+    rawSource: {
+      kind: "web-page",
+      sourceRef: "https://example.test/listings/123",
+      observedAt: new Date().toISOString(),
+      locatorScheme: "html",
+    },
+    extraction: {
+      target: "availabilityStatus",
+      value: "AVAILABLE",
+      confidence: 0.92,
+      locator: "html:field=availabilityStatus",
+      excerpt: "Availability is open.",
+      extractor: "example-crawler",
+      extractedAt: new Date().toISOString(),
+    },
+    reviewOutcome: {
+      status: "verified",
+      actor: "example-operator",
+      reviewedAt: new Date().toISOString(),
+    },
+    claim: {
+      subjectType: "public-record.entity",
+      subjectId: "listing-123",
+      surface: "public-record.profile",
+      claimType: "public-data.field",
+      fieldOrBehavior: "availabilityStatus",
+      impactLevel: "medium",
+      collectedBy: "example-crawler",
+    },
+  })
+  .build();
+
+const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
+const report = buildTrustReport(trustInput);
+```
+
+## Product Boundary
+
+Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,
+or claim a value is true. Producers own acquisition, extraction, ranking, review
+UX, materiality, and domain policy. Survey gives those producers a consistent
+source -> extraction -> candidate -> review -> claim contract before the records
+enter Surface.
+
+## Commands
+
+```sh
+npm install
+npm run verify
+```

package/dist/examples/public-field-observation.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,43 @@
+import { buildTrustReport, validateTrustInput } from "@kontourai/surface";
+import { buildSurveyTrustInput, SurveyInputBuilder } from "../src/index.js";
+const observedAt = "2026-05-31T16:00:00.000Z";
+const surveyInput = new SurveyInputBuilder({
+    source: "example-producer:public-field",
+    generatedAt: observedAt,
+})
+    .addObservation({
+    id: "example.entity-1.availability.current",
+    rawSource: {
+        kind: "web-page",
+        sourceRef: "https://example.test/entities/1",
+        observedAt,
+        locatorScheme: "html",
+    },
+    extraction: {
+        target: "availabilityStatus",
+        value: "AVAILABLE",
+        confidence: 0.92,
+        locator: "html:field=availabilityStatus",
+        excerpt: "Availability is open.",
+        extractor: "example-crawler",
+        extractedAt: observedAt,
+    },
+    reviewOutcome: {
+        status: "verified",
+        actor: "example-operator",
+        reviewedAt: observedAt,
+    },
+    claim: {
+        subjectType: "public-record.entity",
+        subjectId: "entity-1",
+        surface: "public-record.profile",
+        claimType: "public-data.field",
+        fieldOrBehavior: "availabilityStatus",
+        impactLevel: "medium",
+        collectedBy: "example-crawler",
+    },
+})
+    .build();
+const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
+const report = buildTrustReport(trustInput);
+console.log(JSON.stringify(report.summary, null, 2));

package/dist/fixtures/corrected-document-candidates.d.ts

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

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

@@ -0,0 +1,143 @@
+const generatedAt = "2026-05-31T16:00:00.000Z";
+export const correctedDocumentCandidatesFixture = {
+    source: "survey.fixture.corrected-document-candidates",
+    generatedAt,
+    rawSources: [
+        {
+            id: "document:source:original",
+            kind: "uploaded-document",
+            sourceRef: "documents://original-statement.pdf",
+            observedAt: "2026-02-01T12:00:00.000Z",
+            checksum: "sha256:original",
+            locatorScheme: "pdf",
+        },
+        {
+            id: "document:source:corrected",
+            kind: "uploaded-document",
+            sourceRef: "documents://corrected-statement.pdf",
+            observedAt: "2026-03-01T12:00:00.000Z",
+            checksum: "sha256:corrected",
+            locatorScheme: "pdf",
+        },
+    ],
+    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"),
+    ],
+    candidateSets: [
+        documentCandidateSet("amount", "original:amount", 82000, "corrected:amount", 84000),
+        documentCandidateSet("credit", "original:credit", 8600, "corrected:credit", 9100),
+    ],
+    reviewOutcomes: [],
+    claims: [
+        documentClaim("document.entity-1.statement.amount.original", "amount", "original:amount", "statement.totalAmount", "superseded"),
+        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",
+        },
+    ],
+};
+function documentExtraction(id, sourceId, target, value, locator) {
+    return {
+        id: `document:extraction:${id}`,
+        sourceId,
+        target,
+        value,
+        confidence: 0.96,
+        locator,
+        excerpt: `${target}=${value}`,
+        extractor: "document-field-parser",
+        extractedAt: generatedAt,
+    };
+}
+function documentCandidateSet(target, originalId, originalValue, correctedId, correctedValue) {
+    return {
+        id: `document:candidates:${target}`,
+        target: `statement.${target}`,
+        selectedCandidateId: `document:candidate:${correctedId}`,
+        status: "needs-review",
+        rationale: "Corrected document supersedes the original source but still needs review.",
+        candidates: [
+            {
+                id: `document:candidate:${originalId}`,
+                extractionId: `document:extraction:${originalId}`,
+                value: originalValue,
+                confidence: 0.96,
+                sourceRank: 2,
+            },
+            {
+                id: `document:candidate:${correctedId}`,
+                extractionId: `document:extraction:${correctedId}`,
+                value: correctedValue,
+                confidence: 0.96,
+                sourceRank: 1,
+            },
+        ],
+    };
+}
+function documentClaim(id, target, candidateId, fieldOrBehavior, status) {
+    return {
+        id,
+        candidateSetId: `document:candidates:${target}`,
+        candidateId: `document:candidate:${candidateId}`,
+        subjectType: "verified-record.period",
+        subjectId: "entity-1:2026",
+        surface: "document-review",
+        claimType: "source-field",
+        fieldOrBehavior,
+        status,
+        impactLevel: "high",
+        collectedBy: "document-field-parser",
+    };
+}

package/dist/fixtures/public-field-review.d.ts

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

package/dist/fixtures/public-field-review.js

@@ -0,0 +1,125 @@
+const generatedAt = "2026-05-31T16:00:00.000Z";
+export const publicFieldReviewFixture = {
+    source: "survey.fixture.public-field-review",
+    generatedAt,
+    rawSources: [
+        {
+            id: "public-field:source:approved-page",
+            kind: "web-page",
+            sourceRef: "https://example.test/listings/example-program",
+            observedAt: "2026-05-30T18:00:00.000Z",
+            fetchedAt: "2026-05-30T18:00:00.000Z",
+            locatorScheme: "html",
+        },
+        {
+            id: "public-field:source:proposal-page",
+            kind: "web-page",
+            sourceRef: "https://example.test/listings/example-program",
+            observedAt: "2026-05-31T15:00:00.000Z",
+            fetchedAt: "2026-05-31T15:00:00.000Z",
+            locatorScheme: "html",
+        },
+    ],
+    extractions: [
+        {
+            id: "public-field:extraction:approved",
+            sourceId: "public-field:source:approved-page",
+            target: "availabilityStatus",
+            value: "AVAILABLE",
+            confidence: 0.91,
+            locator: "html:field=availabilityStatus",
+            excerpt: "Availability is open for the example program.",
+            extractor: "example-field-review",
+            extractedAt: "2026-05-30T18:00:00.000Z",
+        },
+        {
+            id: "public-field:extraction:proposal",
+            sourceId: "public-field:source:proposal-page",
+            target: "availabilityStatus",
+            value: "WAITLIST",
+            confidence: 0.82,
+            locator: "html:field=availabilityStatus",
+            excerpt: "Join the waitlist for this listing.",
+            extractor: "example-crawl",
+            extractedAt: "2026-05-31T15:00:00.000Z",
+        },
+    ],
+    candidateSets: [
+        {
+            id: "public-field:candidates:current",
+            target: "availabilityStatus",
+            selectedCandidateId: "public-field:candidate:approved",
+            status: "resolved",
+            candidates: [
+                {
+                    id: "public-field:candidate:approved",
+                    extractionId: "public-field:extraction:approved",
+                    value: "AVAILABLE",
+                    confidence: 0.91,
+                },
+            ],
+        },
+        {
+            id: "public-field:candidates:proposal",
+            target: "availabilityStatus",
+            status: "needs-review",
+            candidates: [
+                {
+                    id: "public-field:candidate:proposal",
+                    extractionId: "public-field:extraction:proposal",
+                    value: "WAITLIST",
+                    confidence: 0.82,
+                },
+            ],
+        },
+    ],
+    reviewOutcomes: [
+        {
+            id: "public-field:review:approved",
+            candidateSetId: "public-field:candidates:current",
+            candidateId: "public-field:candidate:approved",
+            status: "verified",
+            actor: "example-operator",
+            reviewedAt: "2026-05-30T18:05:00.000Z",
+            rationale: "Operator approved the field source.",
+        },
+    ],
+    claims: [
+        {
+            id: "public-field.entity-123.availability-status.current",
+            candidateSetId: "public-field:candidates:current",
+            candidateId: "public-field:candidate:approved",
+            subjectType: "public-record.entity",
+            subjectId: "entity-123",
+            surface: "public-record.profile",
+            claimType: "public-data.field",
+            fieldOrBehavior: "availabilityStatus",
+            impactLevel: "medium",
+            collectedBy: "example-field-review",
+            metadata: {
+                producer: {
+                    slug: "example-program",
+                    displayName: "Example Program",
+                },
+            },
+        },
+        {
+            id: "public-field.entity-123.availability-status.proposal-456",
+            candidateSetId: "public-field:candidates:proposal",
+            candidateId: "public-field:candidate:proposal",
+            subjectType: "public-record.entity",
+            subjectId: "entity-123",
+            surface: "public-record.profile",
+            claimType: "public-data.field-candidate",
+            fieldOrBehavior: "availabilityStatus",
+            impactLevel: "medium",
+            collectedBy: "example-crawl",
+            metadata: {
+                producer: {
+                    proposalId: "proposal-456",
+                    oldValue: "AVAILABLE",
+                },
+            },
+        },
+    ],
+};

package/dist/src/builder.d.ts

@@ -0,0 +1,61 @@
+import type { CandidateSet, ClaimTarget, DerivedClaimTarget, Extraction, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
+export interface SurveyInputBuilderArgs {
+    source: string;
+    generatedAt?: string;
+}
+export interface SurveyClaimRecord {
+    rawSource: RawSource;
+    extraction: Extraction;
+    candidateSet: CandidateSet;
+    reviewOutcome?: ReviewOutcome;
+    claim: ClaimTarget;
+}
+export interface SurveyObservationInput {
+    id: string;
+    rawSource: Omit<RawSource, "id"> & {
+        id?: string;
+    };
+    extraction: Omit<Extraction, "id" | "sourceId"> & {
+        id?: string;
+    };
+    candidate?: {
+        id?: string;
+        confidence?: number;
+        sourceRank?: number;
+        metadata?: Record<string, unknown>;
+    };
+    candidateSet?: {
+        id?: string;
+        status?: CandidateSet["status"];
+        rationale?: string;
+        metadata?: Record<string, unknown>;
+    };
+    reviewOutcome?: Omit<ReviewOutcome, "id" | "candidateSetId" | "candidateId"> & {
+        id?: string;
+    };
+    claim: Omit<ClaimTarget, "id" | "candidateSetId" | "candidateId"> & {
+        id?: string;
+    };
+}
+export declare class SurveyInputBuilder {
+    private readonly source;
+    private readonly generatedAt;
+    private readonly rawSources;
+    private readonly extractions;
+    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;
+    addObservations(observations: SurveyObservationInput[]): this;
+    build(): SurveyInput;
+}

package/dist/src/builder.js

@@ -0,0 +1,140 @@
+export class SurveyInputBuilder {
+    source;
+    generatedAt;
+    rawSources = new Map();
+    extractions = new Map();
+    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();
+    }
+    addRawSource(rawSource) {
+        addUnique(this.rawSources, rawSource, "raw source");
+        return this;
+    }
+    addExtraction(extraction) {
+        addUnique(this.extractions, extraction, "extraction");
+        return this;
+    }
+    addCandidateSet(candidateSet) {
+        addUnique(this.candidateSets, candidateSet, "candidate set");
+        return this;
+    }
+    addReviewOutcome(reviewOutcome) {
+        addUnique(this.reviewOutcomes, reviewOutcome, "review outcome");
+        return this;
+    }
+    addClaim(claim) {
+        addUnique(this.claims, claim, "claim target");
+        return this;
+    }
+    addDerivedClaim(derivedClaim) {
+        addUnique(this.derivedClaims, derivedClaim, "derived claim target");
+        return this;
+    }
+    addClaimRecord(record) {
+        this.addRawSource(record.rawSource);
+        this.addExtraction(record.extraction);
+        this.addCandidateSet(record.candidateSet);
+        if (record.reviewOutcome)
+            this.addReviewOutcome(record.reviewOutcome);
+        this.addClaim(record.claim);
+        return this;
+    }
+    addClaimRecords(records) {
+        for (const record of records)
+            this.addClaimRecord(record);
+        return this;
+    }
+    addObservation(observation) {
+        return this.addClaimRecord(observationToClaimRecord(observation));
+    }
+    addObservations(observations) {
+        for (const observation of observations)
+            this.addObservation(observation);
+        return this;
+    }
+    build() {
+        return {
+            source: this.source,
+            generatedAt: this.generatedAt,
+            rawSources: [...this.rawSources.values()],
+            extractions: [...this.extractions.values()],
+            candidateSets: [...this.candidateSets.values()],
+            reviewOutcomes: [...this.reviewOutcomes.values()],
+            claims: [...this.claims.values()],
+            derivedClaims: [...this.derivedClaims.values()],
+        };
+    }
+}
+function observationToClaimRecord(observation) {
+    const ids = observationIds(observation.id, observation);
+    const value = observation.claim.value ?? observation.extraction.value;
+    const confidence = observation.candidate?.confidence ?? observation.extraction.confidence;
+    return {
+        rawSource: {
+            id: ids.sourceId,
+            ...observation.rawSource,
+        },
+        extraction: {
+            id: ids.extractionId,
+            sourceId: ids.sourceId,
+            ...observation.extraction,
+        },
+        candidateSet: {
+            id: ids.candidateSetId,
+            target: observation.extraction.target,
+            selectedCandidateId: ids.candidateId,
+            status: observation.candidateSet?.status ?? candidateSetStatusFor(observation.reviewOutcome?.status),
+            rationale: observation.candidateSet?.rationale,
+            metadata: observation.candidateSet?.metadata,
+            candidates: [{
+                    id: ids.candidateId,
+                    extractionId: ids.extractionId,
+                    value,
+                    confidence,
+                    sourceRank: observation.candidate?.sourceRank,
+                    metadata: observation.candidate?.metadata,
+                }],
+        },
+        reviewOutcome: observation.reviewOutcome
+            ? {
+                id: ids.reviewOutcomeId,
+                candidateSetId: ids.candidateSetId,
+                candidateId: ids.candidateId,
+                ...observation.reviewOutcome,
+            }
+            : undefined,
+        claim: {
+            id: ids.claimId,
+            candidateSetId: ids.candidateSetId,
+            candidateId: ids.candidateId,
+            ...observation.claim,
+            value,
+        },
+    };
+}
+function observationIds(rootId, observation) {
+    const claimId = observation.claim.id ?? rootId;
+    return {
+        claimId,
+        sourceId: observation.rawSource.id ?? `${rootId}.source`,
+        extractionId: observation.extraction.id ?? `${rootId}.extraction`,
+        candidateId: observation.candidate?.id ?? `${rootId}.candidate`,
+        candidateSetId: observation.candidateSet?.id ?? `${rootId}.candidates`,
+        reviewOutcomeId: observation.reviewOutcome?.id ?? `${rootId}.review`,
+    };
+}
+function candidateSetStatusFor(reviewStatus) {
+    if (!reviewStatus || reviewStatus === "proposed")
+        return "needs-review";
+    return "resolved";
+}
+function addUnique(map, item, label) {
+    if (map.has(item.id))
+        throw new Error(`Duplicate ${label} id: ${item.id}`);
+    map.set(item.id, item);
+}

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { SurveyInputBuilder } from "./builder.js";
+export { buildSurveyTrustInput } from "./to-surface.js";

package/dist/src/to-surface.d.ts

@@ -0,0 +1,3 @@
+import type { TrustInput } from "@kontourai/surface";
+import type { SurveyInput } from "./types.js";
+export declare function buildSurveyTrustInput(input: SurveyInput): TrustInput;

package/dist/src/to-surface.js

@@ -0,0 +1,215 @@
+export function buildSurveyTrustInput(input) {
+    const rawSources = indexById(input.rawSources, "raw source");
+    const extractions = indexById(input.extractions, "extraction");
+    const candidateSets = indexById(input.candidateSets, "candidate set");
+    const reviewsByCandidateSet = groupBy(input.reviewOutcomes, (review) => review.candidateSetId);
+    const claims = [];
+    const evidence = [];
+    const events = [];
+    for (const projection of input.claims) {
+        const candidateSet = requireMapValue(candidateSets, projection.candidateSetId, "candidate set");
+        const candidate = selectCandidate(candidateSet, projection.candidateId);
+        const extraction = requireMapValue(extractions, candidate.extractionId, "extraction");
+        const rawSource = requireMapValue(rawSources, extraction.sourceId, "raw source");
+        const review = selectReview(reviewsByCandidateSet.get(candidateSet.id) ?? [], candidate.id);
+        const status = projection.status ?? statusFor({ candidateSet, candidate, review });
+        assertProducerDiscipline({ status, review, extraction, rawSource, projection });
+        const claimValue = projection.value ?? candidate.value;
+        const createdAt = projection.createdAt ?? extraction.extractedAt;
+        const updatedAt = projection.updatedAt ?? review?.reviewedAt ?? input.generatedAt;
+        const evidenceId = `${projection.id}.evidence.source`;
+        claims.push({
+            id: projection.id,
+            subjectType: projection.subjectType,
+            subjectId: projection.subjectId,
+            surface: projection.surface,
+            claimType: projection.claimType,
+            fieldOrBehavior: projection.fieldOrBehavior,
+            value: claimValue,
+            status,
+            createdAt,
+            updatedAt,
+            impactLevel: projection.impactLevel,
+            confidenceBasis: {
+                sourceQuality: "moderate",
+                extractionConfidence: candidate.confidence ?? extraction.confidence,
+                reviewerAuthority: status === "verified" || status === "assumed" ? "operator" : "none",
+                evidenceStrength: status === "verified" || status === "assumed" ? "moderate" : "weak",
+                impactLevel: projection.impactLevel,
+                ...projection.confidenceBasis,
+            },
+            metadata: {
+                ...projection.metadata,
+                survey: {
+                    rawSourceId: rawSource.id,
+                    extractionId: extraction.id,
+                    candidateSetId: candidateSet.id,
+                    candidateId: candidate.id,
+                    reviewOutcomeId: review?.id,
+                },
+            },
+        });
+        evidence.push({
+            id: evidenceId,
+            claimId: projection.id,
+            evidenceType: projection.evidenceType ?? evidenceTypeFor(rawSource),
+            method: projection.evidenceMethod ?? "extraction",
+            sourceRef: rawSource.sourceRef,
+            sourceLocator: extraction.locator,
+            excerptOrSummary: extraction.excerpt ?? `Extracted ${projection.fieldOrBehavior} from ${rawSource.kind}.`,
+            observedAt: rawSource.observedAt,
+            collectedBy: projection.collectedBy,
+            integrityRef: rawSource.checksum,
+            metadata: {
+                ...rawSource.metadata,
+                ...extraction.metadata,
+                ...candidate.metadata,
+                rawSourceKind: rawSource.kind,
+                locatorScheme: rawSource.locatorScheme,
+                confidence: candidate.confidence ?? extraction.confidence,
+            },
+        });
+        events.push({
+            id: `${projection.id}.event.${status}`,
+            claimId: projection.id,
+            status,
+            actor: projection.actor ?? review?.actor ?? projection.collectedBy,
+            method: projection.eventMethod ?? eventMethodFor(status, candidateSet),
+            evidenceIds: review?.evidenceIds?.length ? review.evidenceIds : [evidenceId],
+            createdAt: review?.reviewedAt ?? input.generatedAt,
+            verifiedAt: status === "verified" || status === "assumed" ? review?.reviewedAt ?? input.generatedAt : undefined,
+            notes: review?.rationale ?? candidateSet.rationale,
+        });
+    }
+    for (const derived of input.derivedClaims ?? []) {
+        addDerivedClaim({ derived, claims, evidence, events });
+    }
+    return {
+        schemaVersion: 3,
+        source: input.source,
+        claims,
+        evidence,
+        policies: [],
+        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;
+    if (input.candidateSet.status === "resolved" && input.candidateSet.selectedCandidateId === input.candidate.id) {
+        return "proposed";
+    }
+    if (input.candidateSet.status === "conflict")
+        return "disputed";
+    return "proposed";
+}
+function assertProducerDiscipline(input) {
+    if ((input.status === "verified" || input.status === "assumed") && !input.review) {
+        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without a review outcome`);
+    }
+    if ((input.status === "verified" || input.status === "assumed") && !input.review?.actor) {
+        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without review actor authority`);
+    }
+    if ((input.status === "verified" || input.status === "assumed") && !input.review?.reviewedAt) {
+        throw new Error(`Claim ${input.projection.id} cannot be ${input.status} without reviewedAt`);
+    }
+    if (input.rawSource.kind !== "manual-entry" && !input.extraction.locator) {
+        throw new Error(`Claim ${input.projection.id} needs a source locator for ${input.rawSource.kind}`);
+    }
+}
+function selectCandidate(candidateSet, candidateId) {
+    const id = candidateId ?? candidateSet.selectedCandidateId ?? candidateSet.candidates[0]?.id;
+    const candidate = candidateSet.candidates.find((item) => item.id === id);
+    if (!candidate) {
+        throw new Error(`Candidate set ${candidateSet.id} does not contain candidate ${id ?? "<none>"}`);
+    }
+    return candidate;
+}
+function selectReview(reviews, candidateId) {
+    return reviews.find((review) => review.candidateId === candidateId) ?? reviews.find((review) => !review.candidateId);
+}
+function evidenceTypeFor(rawSource) {
+    if (rawSource.kind === "uploaded-document")
+        return "document_citation";
+    if (rawSource.kind === "web-page")
+        return "crawl_observation";
+    return "attestation";
+}
+function eventMethodFor(status, candidateSet) {
+    if (status === "verified")
+        return "survey-review";
+    if (status === "assumed")
+        return "survey-assumption";
+    if (status === "rejected")
+        return "survey-rejection";
+    if (candidateSet.status === "conflict")
+        return "candidate-conflict";
+    return "candidate-proposal";
+}
+function indexById(items, label) {
+    const map = new Map();
+    for (const item of items) {
+        if (map.has(item.id))
+            throw new Error(`Duplicate ${label} id: ${item.id}`);
+        map.set(item.id, item);
+    }
+    return map;
+}
+function requireMapValue(map, id, label) {
+    const value = map.get(id);
+    if (!value)
+        throw new Error(`Missing ${label}: ${id}`);
+    return value;
+}
+function groupBy(items, getKey) {
+    const map = new Map();
+    for (const item of items) {
+        const key = getKey(item);
+        map.set(key, [...(map.get(key) ?? []), item]);
+    }
+    return map;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,109 @@
+import type { ConfidenceBasis, 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 {
+    id: string;
+    kind: RawSourceKind;
+    sourceRef: string;
+    observedAt: string;
+    fetchedAt?: string;
+    checksum?: string;
+    locatorScheme: LocatorScheme;
+    metadata?: Record<string, unknown>;
+}
+export interface Extraction {
+    id: string;
+    sourceId: string;
+    target: string;
+    value: unknown;
+    confidence?: number;
+    locator?: string;
+    excerpt?: string;
+    extractor: string;
+    extractedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export type CandidateSetStatus = "resolved" | "needs-review" | "conflict";
+export interface Candidate {
+    id: string;
+    extractionId: string;
+    value: unknown;
+    confidence?: number;
+    sourceRank?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CandidateSet {
+    id: string;
+    target: string;
+    candidates: Candidate[];
+    selectedCandidateId?: string;
+    status: CandidateSetStatus;
+    rationale?: string;
+    metadata?: Record<string, unknown>;
+}
+export type ReviewStatus = Extract<TrustStatus, "verified" | "assumed" | "rejected" | "proposed">;
+export interface ReviewOutcome {
+    id: string;
+    candidateSetId: string;
+    candidateId?: string;
+    status: ReviewStatus;
+    actor?: string;
+    reviewedAt?: string;
+    rationale?: string;
+    evidenceIds?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ClaimTarget {
+    id: string;
+    candidateSetId: string;
+    candidateId?: string;
+    subjectType: string;
+    subjectId: string;
+    surface: string;
+    claimType: string;
+    fieldOrBehavior: string;
+    value?: unknown;
+    status?: TrustStatus;
+    impactLevel: ImpactLevel;
+    createdAt?: string;
+    updatedAt?: string;
+    evidenceType?: EvidenceType;
+    evidenceMethod?: EvidenceMethod;
+    confidenceBasis?: ConfidenceBasis;
+    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;
+    rawSources: RawSource[];
+    extractions: Extraction[];
+    candidateSets: CandidateSet[];
+    reviewOutcomes: ReviewOutcome[];
+    claims: ClaimTarget[];
+    derivedClaims?: DerivedClaimTarget[];
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kontourai/survey",
+  "version": "0.1.1",
+  "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kontourai/survey.git"
+  },
+  "homepage": "https://kontourai.io/survey",
+  "bugs": {
+    "url": "https://github.com/kontourai/survey/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./fixtures/public-field-review": "./dist/fixtures/public-field-review.js",
+    "./fixtures/corrected-document-candidates": "./dist/fixtures/corrected-document-candidates.js"
+  },
+  "files": [
+    "dist/examples/",
+    "dist/fixtures/",
+    "dist/src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "verify": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "@kontourai/surface": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}