@kontourai/survey 0.2.0 → 0.3.0

package/README.md

@@ -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
@@ -129,6 +183,20 @@ preserved. Producers still own scalar semantics, validation, candidate ranking,
 review policy, and whether a value should be verified, proposed, rejected, or
 assumed.
 
+## Reviewed candidate resolutions
+
+Use `reviewedCandidateResolution` when a producer has multiple candidate
+observations for the same target and a review outcome selects one candidate.
+The helper wraps `candidateReviewRecord`, attaches the review outcome to the
+selected candidate, defaults the candidate set to `resolved`, defaults the
+selected claim status from the review outcome, and defaults unselected
+candidates to `superseded`. Producers can override selected or unselected claim
+statuses when their domain workflow needs a different posture.
+
+This is useful for corrected documents, source-of-truth choices, and review
+queues where losing candidates should remain visible for transparency rather
+than disappearing from the trust trail.
+
 ## Repeated observations
 
 Use `repeatedObservation` when a producer wants to describe a repeated field or

package/dist/src/index.d.ts

@@ -1,8 +1,12 @@
 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 { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
+export type { ReviewedCandidateResolutionInput } from "./reviewed-candidate-resolution.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
 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

@@ -1,4 +1,6 @@
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
+export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.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/reviewed-candidate-resolution.d.ts

@@ -0,0 +1,18 @@
+import { type SurveyClaimRecord, type SurveyObservationInput } from "./builder.js";
+import type { CandidateSet, ClaimTarget, ReviewOutcome } from "./types.js";
+export interface ReviewedCandidateResolutionInput {
+    id: string;
+    target: string;
+    observations: SurveyObservationInput[];
+    selectedCandidateId: string;
+    rationale?: string;
+    metadata?: Record<string, unknown>;
+    status?: CandidateSet["status"];
+    reviewOutcome: Omit<ReviewOutcome, "id" | "candidateSetId" | "candidateId"> & {
+        id?: string;
+        candidateId?: string;
+    };
+    selectedClaimStatus?: ClaimTarget["status"];
+    unselectedClaimStatus?: ClaimTarget["status"];
+}
+export declare function reviewedCandidateResolution(input: ReviewedCandidateResolutionInput): SurveyClaimRecord[];

package/dist/src/reviewed-candidate-resolution.js

@@ -0,0 +1,36 @@
+import { candidateReviewRecord } from "./builder.js";
+export function reviewedCandidateResolution(input) {
+    return candidateReviewRecord({
+        id: input.id,
+        target: input.target,
+        selectedCandidateId: input.selectedCandidateId,
+        status: input.status ?? candidateSetStatusForReview(input.reviewOutcome.status),
+        rationale: input.rationale,
+        metadata: input.metadata,
+        reviewOutcome: {
+            ...input.reviewOutcome,
+            candidateId: input.reviewOutcome.candidateId ?? input.selectedCandidateId,
+        },
+        observations: input.observations.map((observation) => ({
+            ...observation,
+            claim: {
+                ...observation.claim,
+                status: observation.claim.status ?? claimStatusForObservation(input, observation),
+            },
+        })),
+    });
+}
+function claimStatusForObservation(input, observation) {
+    if (observationCandidateId(observation) === input.selectedCandidateId) {
+        return input.selectedClaimStatus ?? input.reviewOutcome.status;
+    }
+    return input.unselectedClaimStatus ?? "superseded";
+}
+function observationCandidateId(observation) {
+    return observation.candidate?.id ?? `${observation.id}.candidate`;
+}
+function candidateSetStatusForReview(status) {
+    if (status === "proposed")
+        return "needs-review";
+    return "resolved";
+}

package/package.json

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