@kontourai/survey 0.4.0 → 0.4.1

package/README.md

@@ -183,6 +183,94 @@ preserved. Producers still own scalar semantics, validation, candidate ranking,
 review policy, and whether a value should be verified, proposed, rejected, or
 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.
+
+Verified or assumed source-of-authority observations require:
+
+- source reference
+- source locator
+- source-authority class
+- source-authority scope
+- review actor
+- reviewed time
+
+Source-authority metadata projects through Surface Evidence metadata under
+`sourceAuthority`. It does not project to Surface `authorityTrace`, which is
+reserved for actor, credential, role, organization, policy, or system authority.
+
+```ts
+import {
+  buildSurveyTrustInput,
+  sourceOfAuthorityObservation,
+  SurveyInputBuilder,
+  uploadedDocumentSource,
+} from "@kontourai/survey";
+
+const observedAt = new Date().toISOString();
+const rawSource = uploadedDocumentSource({
+  sourceRef: "https://rules.example.test/standard-deduction.pdf",
+  observedAt,
+  checksum: "abc123",
+  locatorScheme: "pdf",
+});
+
+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: {
+      authorityClass: "official_publication",
+      scope: {
+        jurisdiction: "federal",
+        productArea: "regulated-rule",
+        taxYear: 2026,
+      },
+      sourceVersion: "2026",
+      declaredBy: "rule-producer",
+    },
+    rawSource,
+    extraction: {
+      confidence: 0.94,
+      locator: "pdf:page=12;table=standard-deduction;row=mfj",
+      extractor: "rule-producer",
+      extractedAt: observedAt,
+    },
+    reviewOutcome: {
+      status: "verified",
+      actor: "rule-reviewer",
+      reviewedAt: new Date().toISOString(),
+    },
+    claim: {
+      subjectType: "regulated-rule",
+      subjectId: "federal:standard-deduction:mfj:2026",
+      surface: "regulated.rules",
+      claimType: "regulated.rule-value",
+      status: "verified",
+      impactLevel: "high",
+      evidenceType: "policy_rule",
+      evidenceMethod: "extraction",
+      collectedBy: "rule-producer",
+    },
+  }))
+  .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.
+They are Surface claims with Claim Dependencies on source-of-authority claims
+and other product facts. The vertical product owns that domain logic.
+
 ## Reviewed candidate resolutions
 
 Use `reviewedCandidateResolution` when a producer has multiple candidate
@@ -384,6 +472,53 @@ Conflict before review has resolved which candidate should win. When no review
 outcome overrides it, `buildSurveyTrustInput` projects the claim to Surface
 status `"disputed"` and records a `"candidate-conflict"` verification event.
 
+## Review proofs
+
+Use review proof helpers when a producer wants a Surface-compatible integrity
+anchor for one reviewed Survey source -> extraction -> candidate -> review ->
+claim path.
+
+```ts
+import {
+  buildCanonicalReviewProofPayload,
+  buildReviewProofAnchor,
+  canonicalReviewProofJson,
+  hashCanonicalReviewProofPayload,
+} from "@kontourai/survey";
+
+const proofInput = {
+  rawSource,
+  extraction,
+  candidate,
+  candidateSet,
+  reviewOutcome,
+  claim,
+};
+
+const payload = buildCanonicalReviewProofPayload(proofInput);
+const canonicalJson = canonicalReviewProofJson(payload);
+const hash = hashCanonicalReviewProofPayload(payload);
+const anchor = buildReviewProofAnchor(proofInput);
+```
+
+`buildReviewProofAnchor` returns a hash-only Surface `IntegrityAnchor` for the
+canonical payload. The lower-level payload, JSON, and hash helpers are exported
+so producers can store or recompute the exact canonical proof material used for
+the anchor. Producer metadata is not part of the canonical payload; any
+non-portable context belongs outside the hash, such as anchor metadata.
+
+When the Surface projection proof option is enabled, `buildSurveyTrustInput`
+will attach the same kind of anchor to the projected reviewed claim:
+
+```ts
+const trustInput = buildSurveyTrustInput(surveyInput, { reviewProofs: true });
+```
+
+The proof provides hash-only tamper evidence for the Survey review/provenance
+trail in the canonical payload. It does not authenticate an actor, sign the
+payload, or prove the real-world truth of the claim. Non-goals include JWT/JWS
+signing, key management, a transparency log, and any veracity guarantee.
+
 ## Computed values
 
 Computed values are normal `ClaimTarget` entries in `claims`. Producers should
@@ -395,6 +530,146 @@ Survey passes those fields through to Surface while keeping the same
 source -> extraction -> candidate -> review -> claim projection path. Surface
 owns dependency semantics such as recompute pressure and status ceilings.
 
+## Adversarial passes
+
+Producers that run a second adversarial pass — whether an LLM judge, a rules
+engine, or a second human reviewer — emit their output into Survey as a normal
+producer pass with a distinct `extractor` id. Survey does not know or care that
+a second pass ran; it sees two producers disagreeing on the same target, which
+is exactly what `conflict` and escalation records are for.
+
+Two patterns cover the adversary's output:
+
+**Conflicting candidate.** The adversary disagrees with the first-pass extraction
+value. Add the adversary's extraction as a second candidate to the same candidate
+set using `candidateReviewRecord` with `status: "conflict"`. Survey projects the
+conflict to a `disputed` claim in Surface.
+
+```ts
+import { candidateReviewRecord, fieldObservation, SurveyInputBuilder } from "@kontourai/survey";
+
+const records = candidateReviewRecord({
+  id: "candidate-set.entity-1.registration-status",
+  target: "registrationStatus",
+  status: "conflict",
+  rationale: "First pass and adversary disagree; human review required.",
+  observations: [
+    fieldObservation({
+      id: "observation.entity-1.status.first-pass",
+      field: "registrationStatus",
+      value: "ACTIVE",
+      rawSource: {
+        kind: "api-record",
+        sourceRef: "records://entity-1/registry",
+        observedAt: new Date().toISOString(),
+        locatorScheme: "structured-field",
+      },
+      extraction: {
+        confidence: 0.91,
+        locator: "json:$.registrationStatus",
+        extractor: "agent-v1",
+        extractedAt: new Date().toISOString(),
+      },
+      candidate: { id: "candidate.first-pass", confidence: 0.91 },
+      claim: {
+        subjectType: "public-record.entity",
+        subjectId: "entity-1",
+        surface: "public-record.profile",
+        claimType: "public-data.field",
+        impactLevel: "high",
+        collectedBy: "agent-v1",
+      },
+    }),
+    fieldObservation({
+      id: "observation.entity-1.status.adversary",
+      field: "registrationStatus",
+      value: "INACTIVE",
+      rawSource: {
+        kind: "api-record",
+        sourceRef: "records://entity-1/registry",
+        observedAt: new Date().toISOString(),
+        locatorScheme: "structured-field",
+      },
+      extraction: {
+        confidence: 0.84,
+        locator: "json:$.registrationStatus",
+        extractor: "adversary-v1",
+        extractedAt: new Date().toISOString(),
+      },
+      candidate: { id: "candidate.adversary", confidence: 0.84 },
+      claim: {
+        subjectType: "public-record.entity",
+        subjectId: "entity-1",
+        surface: "public-record.profile",
+        claimType: "public-data.field",
+        impactLevel: "high",
+        collectedBy: "adversary-v1",
+      },
+    }),
+  ],
+});
+```
+
+**Framing challenge.** The adversary identifies a target that was not addressed
+at all — a missed standard, an unconsidered alternative, or a misframed question.
+Use `addEscalation` to record the challenge. Attach it to the closest relevant
+claim with `attachToClaimId`; Survey projects it as an additional `disputed`
+verification event on that claim so the reviewer sees it prominently.
+
+```ts
+import { SurveyInputBuilder, fieldObservation } from "@kontourai/survey";
+
+const builder = new SurveyInputBuilder({ source: "example-producer:run-2" });
+
+// First-pass observation
+builder.addObservation(fieldObservation({ /* ... */ }));
+
+// Adversary raises a framing challenge
+builder.addEscalation({
+  id: "escalation.entity-1.fair-value.completeness",
+  target: "fairValue",
+  dimension: "completeness",
+  reason: "Measurement standard Level 3 inputs were not documented; sensitivity range and unobservable input assumptions are missing.",
+  raisedBy: "adversary-v1",
+  raisedAt: new Date().toISOString(),
+  attachToClaimId: "claim.entity-1.fair-value",
+});
+```
+
+If a subsequent first-pass or human-review pass resolves the challenge, set
+`resolvedBy` to the id of the observation that closes it. Survey will not project
+a `disputed` event for resolved escalations.
+
+Escalation dimensions follow the adversary's attack surface: `framing` (wrong
+question framed), `completeness` (missing standards, alternatives, or evidence),
+`conclusion` (reasoning would not survive challenge), and `citation` (cited
+sources do not support the claims attached to them).
+
+Framing challenges without an `attachToClaimId` are carried in `SurveyInput`
+for producer tooling but are not projected to Surface. If the adversary cannot
+identify a target claim to attach a framing challenge to, emit a candidate set
+with `status: "escalated"` for the affected target — that projects to `disputed`
+in Surface with a `candidate-escalation` event.
+
+## Comfort zone flags
+
+Use `withinComfortZone: false` on a `ReviewOutcome` when the reviewer is
+recording a decision outside their domain expertise or is flagging that the
+conclusion requires a different authority to confirm. The flag and optional
+`comfortZoneNote` are carried forward to the Surface verification event `notes`
+so the reviewer chain sees the signal without having to read into the rationale.
+
+```ts
+reviewOutcome: {
+  status: "assumed",
+  actor: "records-operator",
+  reviewedAt: new Date().toISOString(),
+  rationale: "Assumed from registry source pending specialist review.",
+  withinComfortZone: false,
+  comfortZoneNote: "Renewal clause interpretation requires specialist counsel.",
+},
+```
+
 ## Product Boundary
 
 Survey does not crawl pages, parse PDFs, rank candidates, decide review policy,

package/dist/src/builder.d.ts

@@ -1,4 +1,4 @@
-import type { CandidateSet, ClaimTarget, Extraction, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
+import type { CandidateSet, ClaimTarget, EscalationRecord, Extraction, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
 export interface SurveyInputBuilderArgs {
     source: string;
     generatedAt?: string;
@@ -58,12 +58,14 @@ export declare class SurveyInputBuilder {
     private readonly candidateSets;
     private readonly reviewOutcomes;
     private readonly claims;
+    private readonly escalations;
     constructor(args: SurveyInputBuilderArgs);
     addRawSource(rawSource: RawSource): this;
     addExtraction(extraction: Extraction): this;
     addCandidateSet(candidateSet: CandidateSet): this;
     addReviewOutcome(reviewOutcome: ReviewOutcome): this;
     addClaim(claim: ClaimTarget): this;
+    addEscalation(escalation: EscalationRecord): this;
     addClaimRecord(record: SurveyClaimRecord): this;
     addClaimRecords(records: SurveyClaimRecord[]): this;
     addObservation(observation: SurveyObservationInput): this;

package/dist/src/builder.js

@@ -6,6 +6,7 @@ export class SurveyInputBuilder {
     candidateSets = new Map();
     reviewOutcomes = new Map();
     claims = new Map();
+    escalations = new Map();
     constructor(args) {
         this.source = args.source;
         this.generatedAt = args.generatedAt ?? new Date().toISOString();
@@ -30,6 +31,10 @@ export class SurveyInputBuilder {
         addUnique(this.claims, claim, "claim target");
         return this;
     }
+    addEscalation(escalation) {
+        addUnique(this.escalations, escalation, "escalation");
+        return this;
+    }
     addClaimRecord(record) {
         this.addRecordRawSource(record.rawSource);
         this.addExtraction(record.extraction);
@@ -61,6 +66,7 @@ export class SurveyInputBuilder {
             candidateSets: [...this.candidateSets.values()],
             reviewOutcomes: [...this.reviewOutcomes.values()],
             claims: [...this.claims.values()],
+            escalations: this.escalations.size > 0 ? [...this.escalations.values()] : undefined,
         };
     }
     addRecordCandidateSet(candidateSet) {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, Extraction, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
@@ -6,9 +6,14 @@ export type { ReviewedCandidateResolutionInput } from "./reviewed-candidate-reso
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-resolution.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
+export type { BuildSurveyTrustInputOptions } from "./to-surface.js";
+export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, } from "./review-proof.js";
+export type { CanonicalReviewProofPayload, ReviewProofInput, } from "./review-proof.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";
+export { sourceOfAuthorityObservation } from "./source-of-authority-observation.js";
+export type { SourceAuthorityClass, SourceAuthorityMetadata, 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

@@ -2,6 +2,8 @@ export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 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 { apiRecordSource, manualEntrySource, uploadedDocumentSource, webPageSource, } from "./raw-source.js";

package/dist/src/review-proof.d.ts

@@ -0,0 +1,88 @@
+import type { IntegrityAnchor } from "@kontourai/surface";
+import type { Candidate, CandidateSet, ClaimTarget, Extraction, RawSource, ReviewOutcome } from "./types.js";
+export interface ReviewProofInput {
+    rawSource: RawSource;
+    extraction: Extraction;
+    candidate: Candidate;
+    candidateSet: CandidateSet;
+    reviewOutcome?: ReviewOutcome;
+    claim: ClaimTarget;
+    sourceRef?: string;
+    observedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CanonicalReviewProofPayload {
+    schemaVersion: 1;
+    rawSource: {
+        id: string;
+        kind: RawSource["kind"];
+        sourceRef: string;
+        observedAt: string;
+        fetchedAt?: string;
+        checksum?: string;
+        locatorScheme: RawSource["locatorScheme"];
+    };
+    extraction: {
+        id: string;
+        sourceId: string;
+        target: string;
+        value: unknown;
+        confidence?: number;
+        locator?: string;
+        excerpt?: string;
+        extractor: string;
+        extractedAt: string;
+    };
+    candidate: {
+        id: string;
+        extractionId: string;
+        value: unknown;
+        confidence?: number;
+        sourceRank?: number;
+    };
+    candidateSet: {
+        id: string;
+        target: string;
+        candidateIds: string[];
+        selectedCandidateId?: string;
+        status: CandidateSet["status"];
+        rationale?: string;
+    };
+    reviewOutcome?: {
+        id: string;
+        candidateSetId: string;
+        candidateId?: string;
+        status: ReviewOutcome["status"];
+        actor?: string;
+        reviewedAt?: string;
+        rationale?: string;
+        evidenceIds?: string[];
+    };
+    claim: {
+        id: string;
+        candidateSetId: string;
+        candidateId?: string;
+        subjectType: string;
+        subjectId: string;
+        surface: string;
+        claimType: string;
+        fieldOrBehavior: string;
+        value?: unknown;
+        status?: ClaimTarget["status"];
+        impactLevel: ClaimTarget["impactLevel"];
+        createdAt?: string;
+        updatedAt?: string;
+        evidenceType?: ClaimTarget["evidenceType"];
+        evidenceMethod?: ClaimTarget["evidenceMethod"];
+        confidenceBasis?: ClaimTarget["confidenceBasis"];
+        derivedFrom?: string[];
+        derivationEdges?: Array<Omit<NonNullable<ClaimTarget["derivationEdges"]>[number], "metadata">>;
+        collectedBy: string;
+        actor?: string;
+        eventMethod?: string;
+    };
+}
+export declare function buildCanonicalReviewProofPayload(input: ReviewProofInput): CanonicalReviewProofPayload;
+export declare function canonicalReviewProofJson(payload: CanonicalReviewProofPayload): string;
+export declare function hashCanonicalReviewProofPayload(payload: CanonicalReviewProofPayload): string;
+export declare function buildReviewProofAnchor(input: ReviewProofInput): IntegrityAnchor;

package/dist/src/review-proof.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+export function buildCanonicalReviewProofPayload(input) {
+    return {
+        schemaVersion: 1,
+        rawSource: {
+            id: input.rawSource.id,
+            kind: input.rawSource.kind,
+            sourceRef: input.rawSource.sourceRef,
+            observedAt: input.rawSource.observedAt,
+            fetchedAt: input.rawSource.fetchedAt,
+            checksum: input.rawSource.checksum,
+            locatorScheme: input.rawSource.locatorScheme,
+        },
+        extraction: {
+            id: input.extraction.id,
+            sourceId: input.extraction.sourceId,
+            target: input.extraction.target,
+            value: input.extraction.value,
+            confidence: input.extraction.confidence,
+            locator: input.extraction.locator,
+            excerpt: input.extraction.excerpt,
+            extractor: input.extraction.extractor,
+            extractedAt: input.extraction.extractedAt,
+        },
+        candidate: {
+            id: input.candidate.id,
+            extractionId: input.candidate.extractionId,
+            value: input.candidate.value,
+            confidence: input.candidate.confidence,
+            sourceRank: input.candidate.sourceRank,
+        },
+        candidateSet: {
+            id: input.candidateSet.id,
+            target: input.candidateSet.target,
+            candidateIds: input.candidateSet.candidates.map((candidate) => candidate.id).sort(),
+            selectedCandidateId: input.candidateSet.selectedCandidateId,
+            status: input.candidateSet.status,
+            rationale: input.candidateSet.rationale,
+        },
+        reviewOutcome: input.reviewOutcome
+            ? {
+                id: input.reviewOutcome.id,
+                candidateSetId: input.reviewOutcome.candidateSetId,
+                candidateId: input.reviewOutcome.candidateId,
+                status: input.reviewOutcome.status,
+                actor: input.reviewOutcome.actor,
+                reviewedAt: input.reviewOutcome.reviewedAt,
+                rationale: input.reviewOutcome.rationale,
+                evidenceIds: input.reviewOutcome.evidenceIds ? [...input.reviewOutcome.evidenceIds].sort() : undefined,
+            }
+            : undefined,
+        claim: {
+            id: input.claim.id,
+            candidateSetId: input.claim.candidateSetId,
+            candidateId: input.claim.candidateId,
+            subjectType: input.claim.subjectType,
+            subjectId: input.claim.subjectId,
+            surface: input.claim.surface,
+            claimType: input.claim.claimType,
+            fieldOrBehavior: input.claim.fieldOrBehavior,
+            value: input.claim.value,
+            status: input.claim.status,
+            impactLevel: input.claim.impactLevel,
+            createdAt: input.claim.createdAt,
+            updatedAt: input.claim.updatedAt,
+            evidenceType: input.claim.evidenceType,
+            evidenceMethod: input.claim.evidenceMethod,
+            confidenceBasis: input.claim.confidenceBasis,
+            derivedFrom: input.claim.derivedFrom ? [...input.claim.derivedFrom].sort() : undefined,
+            derivationEdges: input.claim.derivationEdges?.map((edge) => ({
+                inputClaimId: edge.inputClaimId,
+                method: edge.method,
+                role: edge.role,
+                supportStrength: edge.supportStrength,
+                rationale: edge.rationale,
+            })),
+            collectedBy: input.claim.collectedBy,
+            actor: input.claim.actor,
+            eventMethod: input.claim.eventMethod,
+        },
+    };
+}
+export function canonicalReviewProofJson(payload) {
+    return JSON.stringify(canonicalize(payload));
+}
+export function hashCanonicalReviewProofPayload(payload) {
+    return createHash("sha256").update(canonicalReviewProofJson(payload)).digest("hex");
+}
+export function buildReviewProofAnchor(input) {
+    const payload = buildCanonicalReviewProofPayload(input);
+    const hash = hashCanonicalReviewProofPayload(payload);
+    return {
+        id: `review-proof.${input.claim.id}.${hash.slice(0, 16)}`,
+        kind: "hash",
+        algorithm: "sha256",
+        value: hash,
+        sourceRef: input.sourceRef ?? input.rawSource.sourceRef,
+        observedAt: input.observedAt ?? input.reviewOutcome?.reviewedAt ?? input.rawSource.observedAt,
+        verificationStatus: "unverified",
+        metadata: input.metadata,
+    };
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    if (!isRecord(value))
+        return value;
+    const canonical = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+        const item = value[key];
+        if (item !== undefined) {
+            Object.defineProperty(canonical, key, {
+                value: canonicalize(item),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+    return canonical;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,31 @@
+import type { SurveyObservationInput } from "./builder.js";
+export type SourceAuthorityClass = "official_publication" | "system_of_record" | "publisher_owned_page" | "contract_record" | "policy_document" | "other";
+export interface SourceAuthorityMetadata {
+    authorityClass: SourceAuthorityClass;
+    scope: Record<string, unknown>;
+    effectiveFrom?: string;
+    effectiveUntil?: string;
+    sourceVersion?: string;
+    sourceOwner?: string;
+    declaredBy: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SourceOfAuthorityObservationInput<TValue> {
+    id: string;
+    field: string;
+    value: TValue;
+    sourceAuthority: SourceAuthorityMetadata;
+    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>;
+}
+export declare function sourceOfAuthorityObservation<TValue>(input: SourceOfAuthorityObservationInput<TValue>): SurveyObservationInput;

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

@@ -0,0 +1,70 @@
+import { buildObservation } from "./observation-helper.js";
+export function sourceOfAuthorityObservation(input) {
+    assertSourceAuthority(input.sourceAuthority, input.id);
+    assertVerifiedPosture(input);
+    const sourceAuthority = {
+        ...input.sourceAuthority,
+        scope: { ...input.sourceAuthority.scope },
+        metadata: input.sourceAuthority.metadata
+            ? { ...input.sourceAuthority.metadata }
+            : undefined,
+    };
+    return buildObservation({
+        ...input,
+        extraction: {
+            ...input.extraction,
+            metadata: {
+                ...input.extraction.metadata,
+                sourceAuthority,
+            },
+        },
+        surveyMetadata: {
+            sourceOfAuthority: {
+                authorityClass: sourceAuthority.authorityClass,
+            },
+        },
+        defaultExcerpt: `${input.field}: ${valueSummary(input.value)}`,
+    });
+}
+function assertSourceAuthority(sourceAuthority, observationId) {
+    if (!sourceAuthority.authorityClass) {
+        throw new Error(`Source-of-authority observation ${observationId} needs sourceAuthority.authorityClass`);
+    }
+    if (!sourceAuthority.declaredBy) {
+        throw new Error(`Source-of-authority observation ${observationId} needs sourceAuthority.declaredBy`);
+    }
+    if (!isRecord(sourceAuthority.scope) || Object.keys(sourceAuthority.scope).length === 0) {
+        throw new Error(`Source-of-authority observation ${observationId} needs sourceAuthority.scope`);
+    }
+}
+function assertVerifiedPosture(input) {
+    const status = claimStatus(input.claim.status, input.reviewOutcome?.status);
+    if (status !== "verified" && status !== "assumed")
+        return;
+    if (!input.rawSource.sourceRef) {
+        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a source reference`);
+    }
+    if (!input.extraction.locator) {
+        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a source locator`);
+    }
+    if (!input.reviewOutcome) {
+        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without a review outcome`);
+    }
+    if (!input.reviewOutcome.actor) {
+        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without review actor authority`);
+    }
+    if (!input.reviewOutcome.reviewedAt) {
+        throw new Error(`Source-of-authority observation ${input.id} cannot be ${status} without reviewedAt`);
+    }
+}
+function claimStatus(claimStatusValue, reviewStatus) {
+    return claimStatusValue ?? reviewStatus;
+}
+function valueSummary(value) {
+    if (value === null || value === undefined)
+        return "<empty>";
+    return String(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/to-surface.d.ts

@@ -1,3 +1,6 @@
 import type { TrustInput } from "@kontourai/surface";
 import type { SurveyInput } from "./types.js";
-export declare function buildSurveyTrustInput(input: SurveyInput): TrustInput;
+export interface BuildSurveyTrustInputOptions {
+    reviewProofs?: boolean;
+}
+export declare function buildSurveyTrustInput(input: SurveyInput, options?: BuildSurveyTrustInputOptions): TrustInput;

package/dist/src/to-surface.js

@@ -1,4 +1,5 @@
-export function buildSurveyTrustInput(input) {
+import { buildReviewProofAnchor } from "./review-proof.js";
+export function buildSurveyTrustInput(input, options = {}) {
     const rawSources = indexById(input.rawSources, "raw source");
     const extractions = indexById(input.extractions, "extraction");
     const candidateSets = indexById(input.candidateSets, "candidate set");
@@ -18,7 +19,7 @@ export function buildSurveyTrustInput(input) {
         const createdAt = projection.createdAt ?? extraction.extractedAt;
         const updatedAt = projection.updatedAt ?? review?.reviewedAt ?? input.generatedAt;
         const evidenceId = `${projection.id}.evidence.source`;
-        claims.push({
+        const claim = {
             id: projection.id,
             subjectType: projection.subjectType,
             subjectId: projection.subjectId,
@@ -51,7 +52,22 @@ export function buildSurveyTrustInput(input) {
                     reviewOutcomeId: review?.id,
                 },
             },
-        });
+        };
+        if (options.reviewProofs && review) {
+            claim.currentIntegrityAnchor = buildReviewProofAnchor({
+                rawSource,
+                extraction,
+                candidate,
+                candidateSet,
+                reviewOutcome: review,
+                claim: {
+                    ...projection,
+                    value: claimValue,
+                    status,
+                },
+            });
+        }
+        claims.push(claim);
         evidence.push({
             id: evidenceId,
             claimId: projection.id,
@@ -72,6 +88,10 @@ export function buildSurveyTrustInput(input) {
                 confidence: candidate.confidence ?? extraction.confidence,
             },
         });
+        const rationale = review?.rationale ?? candidateSet.rationale;
+        const comfortZoneNote = review?.withinComfortZone === false
+            ? `[outside comfort zone] ${review.comfortZoneNote ?? "reviewer flagged this as outside their comfort zone"}`
+            : undefined;
         events.push({
             id: `${projection.id}.event.${status}`,
             claimId: projection.id,
@@ -81,9 +101,31 @@ export function buildSurveyTrustInput(input) {
             evidenceIds: review?.evidenceIds?.length ? review.evidenceIds : [evidenceId],
             createdAt: review?.reviewedAt ?? input.generatedAt,
             verifiedAt: status === "verified" || status === "assumed" ? review?.reviewedAt ?? input.generatedAt : undefined,
-            notes: review?.rationale ?? candidateSet.rationale,
+            notes: [rationale, comfortZoneNote].filter(Boolean).join(" | ") || undefined,
         });
     }
+    if (input.escalations) {
+        const claimIds = new Set(claims.map((c) => c.id));
+        for (const escalation of input.escalations) {
+            if (escalation.resolvedBy)
+                continue;
+            if (!escalation.attachToClaimId)
+                continue;
+            if (!claimIds.has(escalation.attachToClaimId)) {
+                throw new Error(`Escalation ${escalation.id} references unknown claim ${escalation.attachToClaimId}`);
+            }
+            events.push({
+                id: `${escalation.id}.event`,
+                claimId: escalation.attachToClaimId,
+                status: "disputed",
+                actor: escalation.raisedBy,
+                method: "candidate-escalation",
+                evidenceIds: [],
+                createdAt: escalation.raisedAt,
+                notes: `[${escalation.dimension}] ${escalation.reason}`,
+            });
+        }
+    }
     return {
         schemaVersion: 3,
         source: input.source,
@@ -101,6 +143,8 @@ function statusFor(input) {
     }
     if (input.candidateSet.status === "conflict")
         return "disputed";
+    if (input.candidateSet.status === "escalated")
+        return "disputed";
     return "proposed";
 }
 function assertProducerDiscipline(input) {
@@ -144,6 +188,8 @@ function eventMethodFor(status, candidateSet) {
         return "survey-rejection";
     if (candidateSet.status === "conflict")
         return "candidate-conflict";
+    if (candidateSet.status === "escalated")
+        return "candidate-escalation";
     return "candidate-proposal";
 }
 function indexById(items, label) {

package/dist/src/types.d.ts

@@ -23,7 +23,8 @@ export interface Extraction {
     extractedAt: string;
     metadata?: Record<string, unknown>;
 }
-export type CandidateSetStatus = "resolved" | "needs-review" | "conflict";
+export type CandidateSetStatus = "resolved" | "needs-review" | "conflict" | "escalated";
+export type EscalationDimension = "framing" | "completeness" | "conclusion" | "citation";
 export interface Candidate {
     id: string;
     extractionId: string;
@@ -51,6 +52,19 @@ export interface ReviewOutcome {
     reviewedAt?: string;
     rationale?: string;
     evidenceIds?: string[];
+    withinComfortZone?: boolean;
+    comfortZoneNote?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EscalationRecord {
+    id: string;
+    target: string;
+    dimension: EscalationDimension;
+    reason: string;
+    raisedBy: string;
+    raisedAt: string;
+    attachToClaimId?: string;
+    resolvedBy?: string;
     metadata?: Record<string, unknown>;
 }
 export interface ClaimTarget {
@@ -85,4 +99,5 @@ export interface SurveyInput {
     candidateSets: CandidateSet[];
     reviewOutcomes: ReviewOutcome[];
     claims: ClaimTarget[];
+    escalations?: EscalationRecord[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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": "^0.5.0"
+    "@kontourai/surface": "git+https://github.com/kontourai/surface.git#9f2a18fb2c7c2430e81879d730b2a9b37c92f017"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",