@kontourai/survey 0.2.0 → 0.2.1

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

package/dist/src/index.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.2.0",
+  "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",