@kontourai/survey 0.1.1 → 0.1.3

package/README.md

@@ -64,6 +64,75 @@ const trustInput = validateTrustInput(buildSurveyTrustInput(surveyInput));
 const report = buildTrustReport(trustInput);
 ```
 
+## Repeated observations
+
+Use `repeatedObservation` when a producer wants to describe a repeated field or
+entity list as one aggregate observation. The helper returns a normal
+`SurveyObservationInput`, so it works with `SurveyInputBuilder.addObservation`
+and the same Surface projection path.
+
+```ts
+import {
+  buildSurveyTrustInput,
+  repeatedObservation,
+  SurveyInputBuilder,
+} from "@kontourai/survey";
+
+const aliases = [
+  { name: "North Annex", sourceLabel: "record row 1" },
+  { name: "East Annex", sourceLabel: "record row 2" },
+];
+
+const surveyInput = new SurveyInputBuilder({
+  source: "example-producer:run-1",
+})
+  .addObservation(repeatedObservation({
+    id: "entity-123.aliases.current",
+    field: "knownAliases",
+    value: aliases,
+    rawSource: {
+      kind: "api-record",
+      sourceRef: "example-records://entity/entity-123",
+      observedAt: new Date().toISOString(),
+      locatorScheme: "structured-field",
+    },
+    extraction: {
+      confidence: 0.88,
+      locator: "json:$.aliases",
+      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.repeated-field",
+      status: "verified",
+      impactLevel: "medium",
+      collectedBy: "example-extractor",
+    },
+    metadata: {
+      producerField: "aliases",
+    },
+  }))
+  .build();
+
+const trustInput = buildSurveyTrustInput(surveyInput);
+```
+
+`repeatedObservation` sets `extraction.target` and
+`claim.fieldOrBehavior` from `field` when omitted, uses the array as both the
+extraction and claim value, and adds neutral helper metadata at
+`metadata.survey.repeated = { representation: "aggregate-array", itemCount }`.
+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.
+
 ## Product Boundary
 
 Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,

package/dist/src/index.d.ts

@@ -2,3 +2,5 @@ export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, DerivedC
 export { SurveyInputBuilder } from "./builder.js";
 export type { SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput } from "./builder.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
+export { repeatedObservation } from "./repeated-observation.js";
+export type { RepeatedObservationInput } from "./repeated-observation.js";

package/dist/src/index.js

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

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

@@ -0,0 +1,20 @@
+import type { SurveyObservationInput } from "./builder.js";
+export interface RepeatedObservationInput<TItem> {
+    id: string;
+    field: string;
+    value: readonly TItem[];
+    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?: "aggregate-array";
+    metadata?: Record<string, unknown>;
+}
+export declare function repeatedObservation<TItem>(input: RepeatedObservationInput<TItem>): SurveyObservationInput;

package/dist/src/repeated-observation.js

@@ -0,0 +1,42 @@
+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,
+            repeated: {
+                representation,
+                itemCount,
+            },
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/to-surface.js

@@ -41,6 +41,7 @@ export function buildSurveyTrustInput(input) {
             metadata: {
                 ...projection.metadata,
                 survey: {
+                    ...(isRecord(projection.metadata?.survey) ? projection.metadata.survey : {}),
                     rawSourceId: rawSource.id,
                     extractionId: extraction.id,
                     candidateSetId: candidateSet.id,
@@ -213,3 +214,6 @@ function groupBy(items, getKey) {
     }
     return map;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

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