@kontourai/survey 0.1.4 → 0.1.5

package/README.md

@@ -198,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/index.d.ts

@@ -1,6 +1,6 @@
 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";

package/dist/src/index.js

@@ -1,4 +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/package.json

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