@kontourai/survey 0.1.2 → 0.1.4

package/README.md

@@ -64,6 +64,140 @@ 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
+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/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

@@ -2,3 +2,7 @@ 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 { 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,2 +1,4 @@
 export { 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.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,16 @@
+import { buildObservation } from "./observation-helper.js";
+export function repeatedObservation(input) {
+    const representation = input.representation ?? "aggregate-array";
+    const value = [...input.value];
+    return buildObservation({
+        ...input,
+        value,
+        surveyMetadata: {
+            repeated: {
+                representation,
+                itemCount: value.length,
+            },
+        },
+        defaultExcerpt: `${input.field}: ${value.length} item(s)`,
+    });
+}

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.2",
+  "version": "0.1.4",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",