@kontourai/survey 0.4.2 → 0.4.4

package/dist/src/learning-projections.d.ts

@@ -0,0 +1,19 @@
+import type { SurveyInput } from "./types.js";
+export type LearningProjectionKind = "learning.comfort-zone" | "learning.escalation";
+export type LearningProjectionSignal = "comfort-zone.outside" | "escalation.unresolved";
+export type LearningProjectionSeverity = "info" | "attention";
+export interface LearningProjection {
+    id: string;
+    kind: LearningProjectionKind;
+    source: string;
+    createdAt: string;
+    target?: string;
+    claimId?: string;
+    reviewOutcomeId?: string;
+    escalationId?: string;
+    signal: LearningProjectionSignal;
+    severity?: LearningProjectionSeverity;
+    summary: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function buildSurveyLearningProjections(input: SurveyInput): LearningProjection[];

package/dist/src/learning-projections.js

@@ -0,0 +1,77 @@
+export function buildSurveyLearningProjections(input) {
+    const claimsByCandidateSet = groupBy(input.claims, (claim) => claim.candidateSetId);
+    const candidateSetTargets = new Map(input.candidateSets.map((candidateSet) => [candidateSet.id, candidateSet.target]));
+    const projections = [];
+    for (const reviewOutcome of input.reviewOutcomes) {
+        if (reviewOutcome.withinComfortZone !== false)
+            continue;
+        const target = candidateSetTargets.get(reviewOutcome.candidateSetId);
+        const claim = findClaimForReview(claimsByCandidateSet.get(reviewOutcome.candidateSetId) ?? [], reviewOutcome);
+        const note = reviewOutcome.comfortZoneNote;
+        projections.push({
+            id: `${reviewOutcome.id}.learning.comfort-zone`,
+            kind: "learning.comfort-zone",
+            source: input.source,
+            createdAt: reviewOutcome.reviewedAt ?? input.generatedAt,
+            target,
+            claimId: claim?.id,
+            reviewOutcomeId: reviewOutcome.id,
+            signal: "comfort-zone.outside",
+            severity: "attention",
+            summary: note ? `Review outcome is outside comfort zone: ${note}` : "Review outcome is outside comfort zone.",
+            metadata: {
+                comfortZone: {
+                    withinComfortZone: false,
+                    ...(note ? { note } : {}),
+                },
+            },
+        });
+    }
+    for (const escalation of input.escalations ?? []) {
+        if (escalation.resolvedBy)
+            continue;
+        projections.push({
+            id: `${escalation.id}.learning.escalation`,
+            kind: "learning.escalation",
+            source: input.source,
+            createdAt: escalation.raisedAt,
+            target: escalation.target,
+            claimId: escalation.attachToClaimId,
+            escalationId: escalation.id,
+            signal: "escalation.unresolved",
+            severity: "attention",
+            summary: `Unresolved ${escalation.dimension} escalation: ${escalation.reason}`,
+            metadata: {
+                escalation: unresolvedEscalationMetadata(escalation),
+            },
+        });
+    }
+    return projections;
+}
+function findClaimForReview(claims, reviewOutcome) {
+    if (reviewOutcome.candidateId) {
+        return claims.find((claim) => claim.candidateId === reviewOutcome.candidateId);
+    }
+    return claims[0];
+}
+function unresolvedEscalationMetadata(escalation) {
+    return {
+        id: escalation.id,
+        target: escalation.target,
+        dimension: escalation.dimension,
+        reason: escalation.reason,
+        raisedBy: escalation.raisedBy,
+        raisedAt: escalation.raisedAt,
+        ...(escalation.attachToClaimId ? { attachToClaimId: escalation.attachToClaimId } : {}),
+        resolved: false,
+        ...(escalation.metadata ? { metadata: escalation.metadata } : {}),
+    };
+}
+function groupBy(items, getKey) {
+    const map = new Map();
+    for (const item of items) {
+        const key = getKey(item);
+        map.set(key, [...(map.get(key) ?? []), item]);
+    }
+    return map;
+}

package/dist/src/raw-source.d.ts

@@ -25,7 +25,22 @@ export interface ManualEntrySourceInput extends Omit<RawSourceInput, "checksum"
     checksum?: ChecksumInput;
     locatorScheme?: LocatorScheme;
 }
+export interface PolicyStandardMetadata {
+    inlineText: string;
+    standardVersion: string;
+    paragraphRef?: string;
+    reference?: string;
+}
+export interface PolicyStandardSourceInput extends Omit<RawSourceInput, "locatorScheme" | "metadata"> {
+    inlineText: string;
+    standardVersion: string;
+    paragraphRef?: string;
+    reference?: string;
+    locatorScheme?: LocatorScheme;
+    metadata?: Record<string, unknown>;
+}
 export declare function uploadedDocumentSource(input: UploadedDocumentSourceInput): RawSource;
 export declare function apiRecordSource(input: ApiRecordSourceInput): RawSource;
 export declare function webPageSource(input: WebPageSourceInput): RawSource;
 export declare function manualEntrySource(input: ManualEntrySourceInput): RawSource;
+export declare function policyStandardSource(input: PolicyStandardSourceInput): RawSource;

package/dist/src/raw-source.js

@@ -19,6 +19,28 @@ export function manualEntrySource(input) {
         ...input,
     });
 }
+export function policyStandardSource(input) {
+    const policyStandard = {
+        inlineText: input.inlineText,
+        standardVersion: input.standardVersion,
+        paragraphRef: input.paragraphRef,
+        reference: input.reference,
+    };
+    const source = rawSource("policy-standard", {
+        locatorScheme: "text",
+        ...input,
+        metadata: {
+            ...input.metadata,
+            policyStandard,
+        },
+    });
+    return {
+        ...source,
+        inlineText: input.inlineText,
+        standardVersion: input.standardVersion,
+        paragraphRef: input.paragraphRef,
+    };
+}
 function rawSource(kind, input) {
     return {
         id: input.id ?? sourceId(kind, input.sourceRef),

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

@@ -1,5 +1,9 @@
 import type { IntegrityAnchor } from "@kontourai/surface";
 import type { Candidate, CandidateSet, ClaimTarget, Extraction, RawSource, ReviewOutcome } from "./types.js";
+export declare const REVIEW_PROOF_SCHEMA = "survey.review-proof";
+export declare const REVIEW_PROOF_SCHEMA_VERSION = 1;
+export declare const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
+export declare const REVIEW_PROOF_CONTRACT_VERSION = "1";
 export interface ReviewProofInput {
     rawSource: RawSource;
     extraction: Extraction;
@@ -13,6 +17,30 @@ export interface ReviewProofInput {
 }
 export interface CanonicalReviewProofPayload {
     schemaVersion: 1;
+    proof: {
+        schema: typeof REVIEW_PROOF_SCHEMA;
+        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION;
+        packageName: typeof REVIEW_PROOF_PACKAGE_NAME;
+        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION;
+        issuer: string;
+        producer: string;
+        issuedAt: string;
+        subject: {
+            claimId: string;
+            candidateSetId: string;
+            candidateId?: string;
+            subjectType: string;
+            subjectId: string;
+            surface: string;
+            claimType: string;
+            fieldOrBehavior: string;
+        };
+        sourcePayload: {
+            id: string;
+            sourceRef: string;
+            checksum?: string;
+        };
+    };
     rawSource: {
         id: string;
         kind: RawSource["kind"];

package/dist/src/review-proof.js

@@ -1,7 +1,38 @@
 import { createHash } from "node:crypto";
+export const REVIEW_PROOF_SCHEMA = "survey.review-proof";
+export const REVIEW_PROOF_SCHEMA_VERSION = 1;
+export const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
+// Version of the review proof contract emitted by this helper. This is intentionally
+// independent from the npm package release version because it participates in hashes.
+export const REVIEW_PROOF_CONTRACT_VERSION = "1";
 export function buildCanonicalReviewProofPayload(input) {
+    assertCandidateConsistency(input);
     return {
-        schemaVersion: 1,
+        schemaVersion: REVIEW_PROOF_SCHEMA_VERSION,
+        proof: {
+            schema: REVIEW_PROOF_SCHEMA,
+            schemaVersion: REVIEW_PROOF_SCHEMA_VERSION,
+            packageName: REVIEW_PROOF_PACKAGE_NAME,
+            packageVersion: REVIEW_PROOF_CONTRACT_VERSION,
+            issuer: input.claim.collectedBy,
+            producer: input.extraction.extractor,
+            issuedAt: input.reviewOutcome?.reviewedAt ?? input.claim.updatedAt ?? input.extraction.extractedAt,
+            subject: {
+                claimId: input.claim.id,
+                candidateSetId: input.claim.candidateSetId,
+                candidateId: input.candidate.id,
+                subjectType: input.claim.subjectType,
+                subjectId: input.claim.subjectId,
+                surface: input.claim.surface,
+                claimType: input.claim.claimType,
+                fieldOrBehavior: input.claim.fieldOrBehavior,
+            },
+            sourcePayload: {
+                id: input.rawSource.id,
+                sourceRef: input.rawSource.sourceRef,
+                checksum: input.rawSource.checksum,
+            },
+        },
         rawSource: {
             id: input.rawSource.id,
             kind: input.rawSource.kind,
@@ -80,6 +111,32 @@ export function buildCanonicalReviewProofPayload(input) {
         },
     };
 }
+function assertCandidateConsistency(input) {
+    if (input.extraction.sourceId !== input.rawSource.id) {
+        throw new Error(`Review proof extraction sourceId "${input.extraction.sourceId}" does not match raw source id "${input.rawSource.id}".`);
+    }
+    if (input.candidate.extractionId !== input.extraction.id) {
+        throw new Error(`Review proof candidate extractionId "${input.candidate.extractionId}" does not match extraction id "${input.extraction.id}".`);
+    }
+    if (!input.candidateSet.candidates.some((candidate) => candidate.id === input.candidate.id)) {
+        throw new Error(`Review proof candidate id "${input.candidate.id}" is not present in candidate set "${input.candidateSet.id}".`);
+    }
+    if (input.candidateSet.selectedCandidateId && input.candidateSet.selectedCandidateId !== input.candidate.id) {
+        throw new Error(`Review proof candidate set selectedCandidateId "${input.candidateSet.selectedCandidateId}" does not match reviewed candidate id "${input.candidate.id}".`);
+    }
+    if (input.claim.candidateSetId !== input.candidateSet.id) {
+        throw new Error(`Review proof claim candidateSetId "${input.claim.candidateSetId}" does not match candidate set id "${input.candidateSet.id}".`);
+    }
+    if (input.claim.candidateId && input.claim.candidateId !== input.candidate.id) {
+        throw new Error(`Review proof claim candidateId "${input.claim.candidateId}" does not match reviewed candidate id "${input.candidate.id}".`);
+    }
+    if (input.reviewOutcome && input.reviewOutcome.candidateSetId !== input.candidateSet.id) {
+        throw new Error(`Review proof review outcome candidateSetId "${input.reviewOutcome.candidateSetId}" does not match candidate set id "${input.candidateSet.id}".`);
+    }
+    if (input.reviewOutcome?.candidateId && input.reviewOutcome.candidateId !== input.candidate.id) {
+        throw new Error(`Review proof review outcome candidateId "${input.reviewOutcome.candidateId}" does not match reviewed candidate id "${input.candidate.id}".`);
+    }
+}
 export function canonicalReviewProofJson(payload) {
     return JSON.stringify(canonicalize(payload));
 }

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

@@ -0,0 +1,111 @@
+import type { CandidateSetStatus, ClaimTarget, Extraction, RawSource, ReviewOutcome } from "./types.js";
+export declare const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";
+export type ReviewResourceApiVersion = typeof reviewResourceApiVersion;
+export type ReviewResourceKind = "ReviewItem" | "ReviewDecision";
+export interface ResourceMetadata {
+    name: string;
+    uid?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+    producer?: Record<string, unknown>;
+}
+export interface ResourceEnvelope<K extends ReviewResourceKind, Spec, Status = Record<string, never>> {
+    apiVersion: ReviewResourceApiVersion;
+    kind: K;
+    metadata: ResourceMetadata;
+    spec: Spec;
+    status?: Status;
+}
+export type CandidateRole = "current" | "proposed" | "alternative" | "source-version" | "computed";
+export interface SourceReference {
+    sourceRef: string;
+    sourceId?: string;
+    kind?: RawSource["kind"];
+    observedAt?: string;
+    fetchedAt?: string;
+    checksum?: string;
+    locatorScheme?: RawSource["locatorScheme"];
+}
+export interface ReviewLocator {
+    scheme: RawSource["locatorScheme"];
+    locator?: string;
+    excerpt?: string;
+}
+export interface ExtractionReference {
+    extractionId?: string;
+    target: string;
+    confidence?: number;
+    extractor?: string;
+    extractedAt?: string;
+}
+export interface ClaimTargetHint {
+    claimId?: string;
+    subjectType: string;
+    subjectId: string;
+    surface: string;
+    claimType: string;
+    fieldOrBehavior: string;
+    impactLevel: ClaimTarget["impactLevel"];
+    evidenceType?: ClaimTarget["evidenceType"];
+    evidenceMethod?: ClaimTarget["evidenceMethod"];
+    collectedBy?: string;
+    derivedFrom?: string[];
+}
+export interface SurveyRecordProjectionHint {
+    rawSourceId?: RawSource["id"];
+    extractionId?: Extraction["id"];
+    candidateSetId?: string;
+    candidateId?: string;
+    reviewOutcomeId?: ReviewOutcome["id"];
+    claimId?: ClaimTarget["id"];
+}
+export interface ReviewCandidate {
+    id: string;
+    role?: CandidateRole;
+    value: unknown;
+    confidence?: number;
+    sourceRank?: number;
+    rejectionReason?: string;
+    source: SourceReference;
+    locator?: ReviewLocator;
+    extraction: ExtractionReference;
+    claimTarget: ClaimTargetHint;
+    projection?: SurveyRecordProjectionHint;
+    producer?: Record<string, unknown>;
+}
+export interface ReviewItemSpec {
+    target: string;
+    candidates: ReviewCandidate[];
+    candidateSetStatus?: CandidateSetStatus;
+    selectedCandidateId?: string;
+    rationale?: string;
+    producerPolicy?: Record<string, unknown>;
+    projection?: SurveyRecordProjectionHint;
+}
+export interface ReviewItemStatus {
+    observedCandidateCount?: number;
+    selectedCandidateId?: string;
+    reviewDecisionName?: string;
+}
+export type ReviewItem = ResourceEnvelope<"ReviewItem", ReviewItemSpec, ReviewItemStatus>;
+export interface ReviewActor {
+    id: string;
+    displayName?: string;
+}
+export interface ReviewDecisionSpec {
+    reviewItemName: string;
+    candidateId?: string;
+    status: ReviewOutcome["status"];
+    actor?: ReviewActor;
+    reviewedAt?: string;
+    rationale?: string;
+    evidenceIds?: string[];
+    withinComfortZone?: boolean;
+    comfortZoneNote?: string;
+    projection?: SurveyRecordProjectionHint;
+}
+export interface ReviewDecisionStatus {
+    appliedToClaimIds?: string[];
+}
+export type ReviewDecision = ResourceEnvelope<"ReviewDecision", ReviewDecisionSpec, ReviewDecisionStatus>;
+export type ReviewResource = ReviewItem | ReviewDecision;

package/dist/src/review-resource.js

@@ -0,0 +1 @@
+export const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";

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`);