@kontourai/survey 0.4.1 → 0.4.3

package/README.md

@@ -185,11 +185,13 @@ assumed.
 
 ## Source-of-authority observations
 
-Use `sourceOfAuthorityObservation` when a producer treats the raw source as
-authoritative for the extracted target: an official publication, registration
-platform page, policy document, contract record, or system-of-record response.
-The helper does not decide whether the source is truly authoritative. It
-enforces record discipline around the producer's declared source posture.
+Use `sourceOfAuthorityObservationBuilder` when a producer treats the raw source
+as authoritative for the extracted target: an official publication,
+registration platform page, policy document, contract record, or
+system-of-record response. The builder does not decide whether the source is
+truly authoritative. It guides producers through the source, extraction,
+source-authority posture, review outcome, and claim fields that make the
+declared source posture auditable.
 
 Verified or assumed source-of-authority observations require:
 
@@ -207,14 +209,14 @@ reserved for actor, credential, role, organization, policy, or system authority.
 ```ts
 import {
   buildSurveyTrustInput,
-  sourceOfAuthorityObservation,
+  sourceOfAuthorityObservationBuilder,
   SurveyInputBuilder,
   uploadedDocumentSource,
 } from "@kontourai/survey";
 
 const observedAt = new Date().toISOString();
 const rawSource = uploadedDocumentSource({
-  sourceRef: "https://rules.example.test/standard-deduction.pdf",
+  sourceRef: "https://rules.example.test/thresholds.pdf",
   observedAt,
   checksum: "abc123",
   locatorScheme: "pdf",
@@ -223,35 +225,36 @@ const rawSource = uploadedDocumentSource({
 const surveyInput = new SurveyInputBuilder({
   source: "rule-producer:run-1",
 })
-  .addObservation(sourceOfAuthorityObservation({
-    id: "rule.standard-deduction.mfj.2026",
-    field: "federal.standardDeduction.mfj.2026",
-    value: 30000,
-    sourceAuthority: {
+  .addObservation(sourceOfAuthorityObservationBuilder({
+    id: "rule.threshold.primary.2026",
+    field: "regulatedRule.threshold.primary.2026",
+    value: 1200,
+  })
+    .withSourceAuthority({
       authorityClass: "official_publication",
       scope: {
-        jurisdiction: "federal",
+        jurisdiction: "example",
         productArea: "regulated-rule",
-        taxYear: 2026,
+        effectiveYear: 2026,
       },
       sourceVersion: "2026",
       declaredBy: "rule-producer",
-    },
-    rawSource,
-    extraction: {
+    })
+    .fromSource(rawSource)
+    .withExtraction({
       confidence: 0.94,
-      locator: "pdf:page=12;table=standard-deduction;row=mfj",
+      locator: "pdf:page=12;table=thresholds;row=primary",
       extractor: "rule-producer",
       extractedAt: observedAt,
-    },
-    reviewOutcome: {
+    })
+    .withReviewOutcome({
       status: "verified",
       actor: "rule-reviewer",
       reviewedAt: new Date().toISOString(),
-    },
-    claim: {
+    })
+    .forClaim({
       subjectType: "regulated-rule",
-      subjectId: "federal:standard-deduction:mfj:2026",
+      subjectId: "example:threshold:primary:2026",
       surface: "regulated.rules",
       claimType: "regulated.rule-value",
       status: "verified",
@@ -259,18 +262,25 @@ const surveyInput = new SurveyInputBuilder({
       evidenceType: "policy_rule",
       evidenceMethod: "extraction",
       collectedBy: "rule-producer",
-    },
-  }))
+    })
+    .build())
   .build();
 
 const trustInput = buildSurveyTrustInput(surveyInput);
 ```
 
-Contextual claims such as "this return position is compliant" or "this camp is
-eligible for an 8-year-old in June" are not source-of-authority observations.
+`sourceOfAuthorityObservation` remains available as the lower-level object
+factory when a producer already has the full observation input assembled.
+
+Contextual claims such as "this submission is compliant" or "this listing is
+eligible for a specific requester" are not source-of-authority observations.
 They are Surface claims with Claim Dependencies on source-of-authority claims
 and other product facts. The vertical product owns that domain logic.
 
+For the reusable producer workflow, including manual confirmation state,
+source references, Survey review outcomes, and Surface report boundaries, see
+[Source-Authority Review Pattern](docs/source-authority-review-pattern.md).
+
 ## Reviewed candidate resolutions
 
 Use `reviewedCandidateResolution` when a producer has multiple candidate

package/dist/src/index.d.ts

@@ -13,7 +13,7 @@ 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 { sourceOfAuthorityObservation } from "./source-of-authority-observation.js";
-export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationInput, } from "./source-of-authority-observation.js";
+export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
+export type { SourceAuthorityClass, SourceAuthorityMetadata, SourceOfAuthorityObservationBuilderArgs, SourceOfAuthorityObservationInput, } from "./source-of-authority-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

@@ -5,5 +5,5 @@ export { buildSurveyTrustInput } from "./to-surface.js";
 export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
-export { sourceOfAuthorityObservation } from "./source-of-authority-observation.js";
+export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";
 export { apiRecordSource, manualEntrySource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";

package/dist/src/source-of-authority-observation.d.ts

@@ -28,4 +28,24 @@ export interface SourceOfAuthorityObservationInput<TValue> {
     candidateSet?: SurveyObservationInput["candidateSet"];
     metadata?: Record<string, unknown>;
 }
+export interface SourceOfAuthorityObservationBuilderArgs<TValue> {
+    id: string;
+    field: string;
+    value: TValue;
+}
+export declare class SourceOfAuthorityObservationBuilder<TValue> {
+    private readonly state;
+    constructor(args: SourceOfAuthorityObservationBuilderArgs<TValue>);
+    static create<TValue>(args: SourceOfAuthorityObservationBuilderArgs<TValue>): SourceOfAuthorityObservationBuilder<TValue>;
+    withSourceAuthority(sourceAuthority: SourceAuthorityMetadata): this;
+    fromSource(rawSource: SourceOfAuthorityObservationInput<TValue>["rawSource"]): this;
+    withExtraction(extraction: SourceOfAuthorityObservationInput<TValue>["extraction"]): this;
+    withReviewOutcome(reviewOutcome: SourceOfAuthorityObservationInput<TValue>["reviewOutcome"]): this;
+    forClaim(claim: SourceOfAuthorityObservationInput<TValue>["claim"]): this;
+    withCandidate(candidate: SourceOfAuthorityObservationInput<TValue>["candidate"]): this;
+    withCandidateSet(candidateSet: SourceOfAuthorityObservationInput<TValue>["candidateSet"]): this;
+    withMetadata(metadata: Record<string, unknown>): this;
+    build(): SurveyObservationInput;
+}
+export declare function sourceOfAuthorityObservationBuilder<TValue>(args: SourceOfAuthorityObservationBuilderArgs<TValue>): SourceOfAuthorityObservationBuilder<TValue>;
 export declare function sourceOfAuthorityObservation<TValue>(input: SourceOfAuthorityObservationInput<TValue>): SurveyObservationInput;

package/dist/src/source-of-authority-observation.js

@@ -1,4 +1,51 @@
 import { buildObservation } from "./observation-helper.js";
+export class SourceOfAuthorityObservationBuilder {
+    state;
+    constructor(args) {
+        this.state = { ...args };
+    }
+    static create(args) {
+        return new SourceOfAuthorityObservationBuilder(args);
+    }
+    withSourceAuthority(sourceAuthority) {
+        this.state.sourceAuthority = sourceAuthority;
+        return this;
+    }
+    fromSource(rawSource) {
+        this.state.rawSource = rawSource;
+        return this;
+    }
+    withExtraction(extraction) {
+        this.state.extraction = extraction;
+        return this;
+    }
+    withReviewOutcome(reviewOutcome) {
+        this.state.reviewOutcome = reviewOutcome;
+        return this;
+    }
+    forClaim(claim) {
+        this.state.claim = claim;
+        return this;
+    }
+    withCandidate(candidate) {
+        this.state.candidate = candidate;
+        return this;
+    }
+    withCandidateSet(candidateSet) {
+        this.state.candidateSet = candidateSet;
+        return this;
+    }
+    withMetadata(metadata) {
+        this.state.metadata = metadata;
+        return this;
+    }
+    build() {
+        return sourceOfAuthorityObservation(completeBuilderState(this.state));
+    }
+}
+export function sourceOfAuthorityObservationBuilder(args) {
+    return SourceOfAuthorityObservationBuilder.create(args);
+}
 export function sourceOfAuthorityObservation(input) {
     assertSourceAuthority(input.sourceAuthority, input.id);
     assertVerifiedPosture(input);
@@ -26,6 +73,27 @@ export function sourceOfAuthorityObservation(input) {
         defaultExcerpt: `${input.field}: ${valueSummary(input.value)}`,
     });
 }
+function completeBuilderState(state) {
+    return {
+        id: state.id,
+        field: state.field,
+        value: state.value,
+        sourceAuthority: requireBuilderField(state.sourceAuthority, state.id, "sourceAuthority"),
+        rawSource: requireBuilderField(state.rawSource, state.id, "rawSource"),
+        extraction: requireBuilderField(state.extraction, state.id, "extraction"),
+        reviewOutcome: state.reviewOutcome,
+        claim: requireBuilderField(state.claim, state.id, "claim"),
+        candidate: state.candidate,
+        candidateSet: state.candidateSet,
+        metadata: state.metadata,
+    };
+}
+function requireBuilderField(value, observationId, field) {
+    if (value === undefined) {
+        throw new Error(`Source-of-authority observation ${observationId} builder needs ${field}`);
+    }
+    return value;
+}
 function assertSourceAuthority(sourceAuthority, observationId) {
     if (!sourceAuthority.authorityClass) {
         throw new Error(`Source-of-authority observation ${observationId} needs sourceAuthority.authorityClass`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     "check:content-boundary": "node scripts/check-content-boundary.cjs"
   },
   "dependencies": {
-    "@kontourai/surface": "git+https://github.com/kontourai/surface.git#9f2a18fb2c7c2430e81879d730b2a9b37c92f017"
+    "@kontourai/surface": "^0.5.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",