@kontourai/survey 0.1.3 → 0.1.5

package/README.md

@@ -64,6 +64,71 @@ const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
 const report = buildTrustReport(trustInput);
 ```
 
+## Field observations
+
+Use `fieldObservation` when a producer wants to describe one scalar field value
+without hand-assembling the repeated source, extraction, candidate, review, and
+claim defaults. The helper returns a normal `SurveyObservationInput`, so it
+works with `SurveyInputBuilder.addObservation` and the same Surface projection
+path.
+
+```ts
+import {
+  buildSurveyTrustInput,
+  fieldObservation,
+  SurveyInputBuilder,
+} from "@kontourai/survey";
+
+const surveyInput = new SurveyInputBuilder({
+  source: "example-producer:run-1",
+})
+  .addObservation(fieldObservation({
+    id: "entity-123.status.current",
+    field: "registrationStatus",
+    value: "ACTIVE",
+    rawSource: {
+      kind: "api-record",
+      sourceRef: "example-records://entity/entity-123",
+      observedAt: new Date().toISOString(),
+      locatorScheme: "structured-field",
+    },
+    extraction: {
+      confidence: 0.97,
+      locator: "json:$.registrationStatus",
+      extractor: "example-extractor",
+      extractedAt: new Date().toISOString(),
+    },
+    reviewOutcome: {
+      status: "verified",
+      actor: "records-operator",
+      reviewedAt: new Date().toISOString(),
+    },
+    claim: {
+      subjectType: "public-record.entity",
+      subjectId: "entity-123",
+      surface: "example.profile",
+      claimType: "public-data.field",
+      status: "verified",
+      impactLevel: "medium",
+      collectedBy: "example-extractor",
+    },
+    metadata: {
+      producerField: "registration_status",
+    },
+  }))
+  .build();
+
+const trustInput = buildSurveyTrustInput(surveyInput);
+```
+
+`fieldObservation` sets `extraction.target` and `claim.fieldOrBehavior` from
+`field` when omitted, uses the scalar as both the extraction and claim value,
+and adds neutral helper metadata at
+`metadata.survey.field = { representation: "scalar" }`. Producer metadata is
+preserved. Producers still own scalar semantics, validation, candidate ranking,
+review policy, and whether a value should be verified, proposed, rejected, or
+assumed.
+
 ## Repeated observations
 
 Use `repeatedObservation` when a producer wants to describe a repeated field or
@@ -133,6 +198,103 @@ Producer metadata is preserved. Producers still own item semantics,
 validation, candidate ranking, review policy, and whether a value should be
 verified, proposed, rejected, or assumed.
 
+## Candidate review records
+
+Use `candidateReviewRecord` when a producer has multiple candidate observations
+for the same target and wants Survey to assemble the shared candidate set,
+candidate links, and optional review outcome.
+
+```ts
+import {
+  candidateReviewRecord,
+  fieldObservation,
+  SurveyInputBuilder,
+} from "@kontourai/survey";
+
+const observations = [
+  fieldObservation({
+    id: "entity-123.status.registry",
+    field: "registrationStatus",
+    value: "ACTIVE",
+    rawSource: {
+      kind: "api-record",
+      sourceRef: "example-records://entity/entity-123",
+      observedAt: new Date().toISOString(),
+      locatorScheme: "structured-field",
+    },
+    extraction: {
+      confidence: 0.97,
+      locator: "json:$.registrationStatus",
+      extractor: "example-extractor",
+      extractedAt: new Date().toISOString(),
+    },
+    candidate: { id: "candidate.registry", confidence: 0.97 },
+    claim: {
+      id: "claim.entity-123.status.registry",
+      subjectType: "public-record.entity",
+      subjectId: "entity-123",
+      surface: "example.profile",
+      claimType: "public-data.field",
+      status: "verified",
+      impactLevel: "medium",
+      collectedBy: "example-extractor",
+    },
+  }),
+  fieldObservation({
+    id: "entity-123.status.archive",
+    field: "registrationStatus",
+    value: "INACTIVE",
+    rawSource: {
+      kind: "web-page",
+      sourceRef: "https://records.example.test/entity-123",
+      observedAt: new Date().toISOString(),
+      locatorScheme: "html",
+    },
+    extraction: {
+      confidence: 0.71,
+      locator: "css:#registration-status",
+      extractor: "example-crawler",
+      extractedAt: new Date().toISOString(),
+    },
+    candidate: { id: "candidate.archive", confidence: 0.71 },
+    claim: {
+      id: "claim.entity-123.status.archive",
+      subjectType: "public-record.entity",
+      subjectId: "entity-123",
+      surface: "example.profile",
+      claimType: "public-data.field",
+      status: "superseded",
+      impactLevel: "medium",
+      collectedBy: "example-crawler",
+    },
+  }),
+];
+
+const surveyInput = new SurveyInputBuilder({ source: "example-producer:run-1" })
+  .addClaimRecords(candidateReviewRecord({
+    id: "candidate-set.entity-123.registration-status",
+    target: "registrationStatus",
+    selectedCandidateId: "candidate.registry",
+    status: "resolved",
+    rationale: "Registry source wins over archive source.",
+    reviewOutcome: {
+      status: "verified",
+      actor: "records-operator",
+      reviewedAt: new Date().toISOString(),
+    },
+    observations,
+  }))
+  .build();
+```
+
+`candidateReviewRecord` does not choose the winning candidate or status. The
+producer still supplies candidate ids, selected candidate id, claim ids, review
+status, rationale, and all domain policy. Survey only assembles the generic
+record graph and tolerates repeated references to identical raw sources or the
+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.
+
 ## Product Boundary
 
 Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,

package/dist/src/builder.d.ts

@@ -37,6 +37,19 @@ export interface SurveyObservationInput {
         id?: string;
     };
 }
+export interface CandidateReviewRecordInput {
+    id: string;
+    target: string;
+    observations: SurveyObservationInput[];
+    selectedCandidateId?: string;
+    status?: CandidateSet["status"];
+    rationale?: string;
+    metadata?: Record<string, unknown>;
+    reviewOutcome?: Omit<ReviewOutcome, "id" | "candidateSetId"> & {
+        id?: string;
+        candidateId?: string;
+    };
+}
 export declare class SurveyInputBuilder {
     private readonly source;
     private readonly generatedAt;
@@ -58,4 +71,7 @@ export declare class SurveyInputBuilder {
     addObservation(observation: SurveyObservationInput): this;
     addObservations(observations: SurveyObservationInput[]): this;
     build(): SurveyInput;
+    private addRecordCandidateSet;
+    private addRecordRawSource;
 }
+export declare function candidateReviewRecord(input: CandidateReviewRecordInput): SurveyClaimRecord[];

package/dist/src/builder.js

@@ -36,9 +36,9 @@ export class SurveyInputBuilder {
         return this;
     }
     addClaimRecord(record) {
-        this.addRawSource(record.rawSource);
+        this.addRecordRawSource(record.rawSource);
         this.addExtraction(record.extraction);
-        this.addCandidateSet(record.candidateSet);
+        this.addRecordCandidateSet(record.candidateSet);
         if (record.reviewOutcome)
             this.addReviewOutcome(record.reviewOutcome);
         this.addClaim(record.claim);
@@ -69,6 +69,77 @@ export class SurveyInputBuilder {
             derivedClaims: [...this.derivedClaims.values()],
         };
     }
+    addRecordCandidateSet(candidateSet) {
+        addIdempotent(this.candidateSets, candidateSet, "candidate set");
+    }
+    addRecordRawSource(rawSource) {
+        addIdempotent(this.rawSources, rawSource, "raw source");
+    }
+}
+export function candidateReviewRecord(input) {
+    if (input.observations.length === 0) {
+        throw new Error(`Candidate review record ${input.id} needs at least one observation`);
+    }
+    const records = input.observations.map((observation) => observationToClaimRecord(observation));
+    const candidateSetId = input.id;
+    const selectedCandidateId = input.selectedCandidateId ?? input.reviewOutcome?.candidateId;
+    const candidates = records.map((record) => record.candidateSet.candidates[0]);
+    assertUniqueCandidateIds(candidates, candidateSetId);
+    assertCandidateIdExists(candidates, selectedCandidateId, candidateSetId, "selected");
+    if (input.selectedCandidateId && input.reviewOutcome?.candidateId && input.selectedCandidateId !== input.reviewOutcome.candidateId) {
+        throw new Error(`Candidate review record ${candidateSetId} has conflicting selected and review candidate ids`);
+    }
+    if (input.reviewOutcome && !selectedCandidateId) {
+        throw new Error(`Candidate review record ${candidateSetId} needs a selected candidate id for review outcome`);
+    }
+    const candidateSet = {
+        id: candidateSetId,
+        target: input.target,
+        candidates,
+        selectedCandidateId,
+        status: input.status ?? candidateSetStatusFor(input.reviewOutcome?.status),
+        rationale: input.rationale,
+        metadata: input.metadata,
+    };
+    const reviewCandidateId = input.reviewOutcome?.candidateId ?? selectedCandidateId;
+    const reviewOutcome = input.reviewOutcome
+        ? {
+            id: input.reviewOutcome.id ?? `${candidateSetId}.review`,
+            candidateSetId,
+            ...input.reviewOutcome,
+            candidateId: reviewCandidateId,
+        }
+        : undefined;
+    assertCandidateIdExists(candidates, reviewCandidateId, candidateSetId, "review");
+    return records.map((record) => {
+        const candidate = record.candidateSet.candidates[0];
+        return {
+            ...record,
+            candidateSet,
+            reviewOutcome: candidate.id === reviewCandidateId ? reviewOutcome : undefined,
+            claim: {
+                ...record.claim,
+                candidateSetId,
+                candidateId: candidate.id,
+            },
+        };
+    });
+}
+function assertUniqueCandidateIds(candidates, candidateSetId) {
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate.id)) {
+            throw new Error(`Candidate review record ${candidateSetId} has duplicate candidate id: ${candidate.id}`);
+        }
+        seen.add(candidate.id);
+    }
+}
+function assertCandidateIdExists(candidates, candidateId, candidateSetId, role) {
+    if (!candidateId)
+        return;
+    if (!candidates.some((candidate) => candidate.id === candidateId)) {
+        throw new Error(`Candidate review record ${candidateSetId} does not contain ${role} candidate ${candidateId}`);
+    }
 }
 function observationToClaimRecord(observation) {
     const ids = observationIds(observation.id, observation);
@@ -138,3 +209,25 @@ function addUnique(map, item, label) {
         throw new Error(`Duplicate ${label} id: ${item.id}`);
     map.set(item.id, item);
 }
+function addIdempotent(map, item, label) {
+    const existing = map.get(item.id);
+    if (existing) {
+        if (stableStringify(existing) !== stableStringify(item)) {
+            throw new Error(`Conflicting ${label} id: ${item.id}`);
+        }
+        return;
+    }
+    map.set(item.id, item);
+}
+function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, sortValue(item)]));
+}

package/dist/src/field-observation.d.ts

@@ -0,0 +1,20 @@
+import type { SurveyObservationInput } from "./builder.js";
+export interface FieldObservationInput<TValue> {
+    id: string;
+    field: string;
+    value: TValue;
+    rawSource: SurveyObservationInput["rawSource"];
+    extraction: Omit<SurveyObservationInput["extraction"], "target" | "value" | "excerpt"> & {
+        target?: string;
+        excerpt?: string | null;
+    };
+    reviewOutcome?: SurveyObservationInput["reviewOutcome"];
+    claim: Omit<SurveyObservationInput["claim"], "fieldOrBehavior" | "value"> & {
+        fieldOrBehavior?: string;
+    };
+    candidate?: SurveyObservationInput["candidate"];
+    candidateSet?: SurveyObservationInput["candidateSet"];
+    representation?: "scalar";
+    metadata?: Record<string, unknown>;
+}
+export declare function fieldObservation<TValue>(input: FieldObservationInput<TValue>): SurveyObservationInput;

package/dist/src/field-observation.js

@@ -0,0 +1,16 @@
+import { buildObservation } from "./observation-helper.js";
+export function fieldObservation(input) {
+    const representation = input.representation ?? "scalar";
+    return buildObservation({
+        ...input,
+        surveyMetadata: {
+            field: { representation },
+        },
+        defaultExcerpt: `${input.field}: ${valueSummary(input.value)}`,
+    });
+}
+function valueSummary(value) {
+    if (value === null || value === undefined)
+        return "<empty>";
+    return String(value);
+}

package/dist/src/index.d.ts

@@ -1,6 +1,8 @@
 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 { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
+export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.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";

package/dist/src/index.js

@@ -1,3 +1,4 @@
-export { SurveyInputBuilder } from "./builder.js";
+export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
+export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";

package/dist/src/observation-helper.d.ts

@@ -0,0 +1,21 @@
+import type { SurveyObservationInput } from "./builder.js";
+export interface BuildObservationInput<TValue> {
+    id: string;
+    field: string;
+    value: TValue;
+    rawSource: SurveyObservationInput["rawSource"];
+    extraction: Omit<SurveyObservationInput["extraction"], "target" | "value" | "excerpt"> & {
+        target?: string;
+        excerpt?: string | null;
+    };
+    reviewOutcome?: SurveyObservationInput["reviewOutcome"];
+    claim: Omit<SurveyObservationInput["claim"], "fieldOrBehavior" | "value"> & {
+        fieldOrBehavior?: string;
+    };
+    candidate?: SurveyObservationInput["candidate"];
+    candidateSet?: SurveyObservationInput["candidateSet"];
+    metadata?: Record<string, unknown>;
+    surveyMetadata: Record<string, unknown>;
+    defaultExcerpt: string;
+}
+export declare function buildObservation<TValue>(input: BuildObservationInput<TValue>): SurveyObservationInput;

package/dist/src/observation-helper.js

@@ -0,0 +1,63 @@
+export function buildObservation(input) {
+    return {
+        id: input.id,
+        rawSource: input.rawSource,
+        extraction: {
+            ...input.extraction,
+            target: input.extraction.target ?? input.field,
+            value: input.value,
+            excerpt: input.extraction.excerpt ?? input.defaultExcerpt,
+        },
+        candidate: input.candidate,
+        candidateSet: input.candidateSet,
+        reviewOutcome: input.reviewOutcome,
+        claim: {
+            ...input.claim,
+            fieldOrBehavior: input.claim.fieldOrBehavior ?? input.field,
+            value: input.value,
+            metadata: mergeObservationMetadata(input.claim.metadata, input.metadata, input.surveyMetadata),
+        },
+    };
+}
+function mergeObservationMetadata(claimMetadata, metadata, surveyMetadata) {
+    const claimSurvey = claimMetadata?.survey && isRecord(claimMetadata.survey) ? claimMetadata.survey : {};
+    const survey = metadata?.survey && isRecord(metadata.survey) ? metadata.survey : {};
+    return {
+        ...claimMetadata,
+        ...metadata,
+        survey: {
+            ...claimSurvey,
+            ...survey,
+            ...mergeNestedRecords(claimSurvey, survey, surveyMetadata),
+        },
+    };
+}
+function mergeNestedRecords(claimSurvey, survey, surveyMetadata) {
+    const merged = {};
+    const keys = new Set([
+        ...Object.keys(claimSurvey),
+        ...Object.keys(survey),
+        ...Object.keys(surveyMetadata),
+    ]);
+    for (const key of keys) {
+        const claimValue = claimSurvey[key];
+        const metadataValue = survey[key];
+        const helperValue = surveyMetadata[key];
+        if (isRecord(claimValue) && isRecord(metadataValue) && isRecord(helperValue)) {
+            merged[key] = { ...claimValue, ...metadataValue, ...helperValue };
+        }
+        else if (isRecord(claimValue) && isRecord(helperValue) && metadataValue === undefined) {
+            merged[key] = { ...claimValue, ...helperValue };
+        }
+        else if (isRecord(metadataValue) && isRecord(helperValue)) {
+            merged[key] = { ...metadataValue, ...helperValue };
+        }
+        else {
+            merged[key] = helperValue ?? metadataValue ?? claimValue;
+        }
+    }
+    return merged;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/repeated-observation.js

@@ -1,42 +1,16 @@
+import { buildObservation } from "./observation-helper.js";
 export function repeatedObservation(input) {
     const representation = input.representation ?? "aggregate-array";
     const value = [...input.value];
-    return {
-        id: input.id,
-        rawSource: input.rawSource,
-        extraction: {
-            ...input.extraction,
-            target: input.extraction.target ?? input.field,
-            value,
-            excerpt: input.extraction.excerpt ?? `${input.field}: ${value.length} item(s)`,
-        },
-        candidate: input.candidate,
-        candidateSet: input.candidateSet,
-        reviewOutcome: input.reviewOutcome,
-        claim: {
-            ...input.claim,
-            fieldOrBehavior: input.claim.fieldOrBehavior ?? input.field,
-            value,
-            metadata: repeatedMetadata(input.claim.metadata, input.metadata, representation, value.length),
-        },
-    };
-}
-function repeatedMetadata(claimMetadata, metadata, representation, itemCount) {
-    const claimSurvey = claimMetadata?.survey && isRecord(claimMetadata.survey) ? claimMetadata.survey : {};
-    const survey = metadata?.survey && isRecord(metadata.survey) ? metadata.survey : {};
-    return {
-        ...claimMetadata,
-        ...metadata,
-        survey: {
-            ...claimSurvey,
-            ...survey,
+    return buildObservation({
+        ...input,
+        value,
+        surveyMetadata: {
             repeated: {
                 representation,
-                itemCount,
+                itemCount: value.length,
             },
         },
-    };
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+        defaultExcerpt: `${input.field}: ${value.length} item(s)`,
+    });
 }

package/package.json

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