@kontourai/lookout 0.2.0 → 0.3.1

package/dist/src/{survey-emission.d.ts → drift-emission.d.ts}

@@ -1,4 +1,3 @@
-import { type SurveyInput } from "@kontourai/survey";
 import type { LookoutSource } from "./registry.js";
 import { type ProposalDiffEvent, type ProposalSetDiff, type ProposalSetDiffInput, type ProposalSetFacts, type ProposalSetObservation } from "./proposal-diff.js";
 import type { ObservationCheckAnchor, ObservationStore, StoredProposalObservationV1 } from "./observation-store.js";
@@ -11,7 +10,7 @@ export interface BaselineEstablishedFact {
     readonly resolution: "observation";
     readonly proposalCount: number;
 }
-export type EmissionFact = BaselineEstablishedFact | {
+export type DriftFact = BaselineEstablishedFact | {
     readonly kind: "proposal-set-facts";
     readonly priorSnapshotRef: string;
     readonly currentSnapshotRef: string;
@@ -19,37 +18,38 @@ export type EmissionFact = BaselineEstablishedFact | {
     readonly resolution: "observation";
     readonly value: ProposalSetFacts;
 };
-export interface EmissionSuccess {
+export interface DriftSuccess {
     readonly sourceId: string;
     readonly events: readonly ProposalDiffEvent[];
-    readonly facts: readonly EmissionFact[];
-    readonly surveyInput: SurveyInput | null;
+    readonly facts: readonly DriftFact[];
+    /** The prior observation this drift was diffed against, or null on a first-ever (baseline) observation. */
+    readonly priorObservationId: string | null;
     readonly committedObservation: StoredProposalObservationV1;
     readonly warnings: readonly string[];
 }
-export type EmissionErrorKind = "invalid-input" | "prior-state-error" | "diff-error" | "authoring-error" | "persistence-error";
-export interface EmissionError {
-    readonly kind: EmissionErrorKind;
+export type DriftErrorKind = "invalid-input" | "prior-state-error" | "diff-error" | "persistence-error" | "serialization-error" | "unexpected";
+export interface DriftError {
+    readonly kind: DriftErrorKind;
     readonly message: string;
     readonly cause?: unknown;
 }
-export type EmissionResult = {
+export type DriftResult = {
     readonly ok: true;
-    readonly value: EmissionSuccess;
+    readonly value: DriftSuccess;
 } | {
     readonly ok: false;
-    readonly error: EmissionError;
+    readonly error: DriftError;
 };
-export interface EmitSurveyInput<E> {
+export interface EmitDriftInput<E> {
     readonly source: LookoutSource;
     readonly current: ProposalSetObservation;
     readonly check: ObservationCheckAnchor;
     readonly callbacks: Omit<ProposalSetDiffInput<E>, "prior" | "current">;
 }
-export interface SurveyEmitter<E> {
-    emit(input: EmitSurveyInput<E>): Promise<EmissionResult>;
+export interface DriftEmitter<E> {
+    emit(input: EmitDriftInput<E>): Promise<DriftResult>;
 }
-export interface CreateSurveyEmitterOptions<E> {
+export interface CreateDriftEmitterOptions<E> {
     readonly store: ObservationStore;
     readonly now?: () => string;
     readonly diff?: (input: ProposalSetDiffInput<E>) => {
@@ -61,8 +61,5 @@ export interface CreateSurveyEmitterOptions<E> {
             readonly message: string;
         };
     };
-    /** Test seam. Production callers must leave this as observation. */
-    readonly resolution?: "observation";
-    readonly transformSurveyInput?: (input: SurveyInput) => SurveyInput;
 }
-export declare function createSurveyEmitter<E>(options: CreateSurveyEmitterOptions<E>): SurveyEmitter<E>;
+export declare function createDriftEmitter<E>(options: CreateDriftEmitterOptions<E>): DriftEmitter<E>;

package/dist/src/drift-emission.js

@@ -0,0 +1,71 @@
+import { diffProposalSets } from "./proposal-diff.js";
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+    return JSON.stringify(value) ?? "undefined";
+}
+function normalizeDiff(value) {
+    const sorted = (items) => [...items].sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
+    return {
+        events: sorted(value.events),
+        facts: {
+            retainedProposalOccurrences: sorted(value.facts.retainedProposalOccurrences),
+            addedProposalOccurrences: sorted(value.facts.addedProposalOccurrences),
+            removedProposalOccurrences: sorted(value.facts.removedProposalOccurrences),
+            provenanceChanges: sorted(value.facts.provenanceChanges),
+            removedEntities: [...value.facts.removedEntities].sort(),
+        },
+    };
+}
+export function createDriftEmitter(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const diff = options.diff ?? diffProposalSets;
+    return {
+        async emit(input) {
+            try {
+                if (!input.source || input.source.id !== input.current?.sourceId || input.check?.currentSnapshotRef !== input.current?.snapshotRef) {
+                    return { ok: false, error: { kind: "invalid-input", message: "Registry source, observation, and check anchor must agree" } };
+                }
+                const loaded = await options.store.loadLatest(input.source.id);
+                if (!loaded.ok)
+                    return { ok: false, error: { kind: "prior-state-error", message: loaded.error.message, cause: loaded.error } };
+                const recordedAt = now();
+                const priorObservationId = loaded.value?.observationId ?? null;
+                let events = [];
+                let facts;
+                if (loaded.value === null) {
+                    facts = [{ kind: "baseline-established", sourceId: input.source.id, snapshotRef: input.current.snapshotRef, observedAt: input.current.observedAt, origin: input.source.kind, resolution: "observation", proposalCount: input.current.proposals.length }];
+                }
+                else {
+                    let derived;
+                    try {
+                        derived = diff({ prior: { sourceId: loaded.value.sourceId, snapshotRef: loaded.value.snapshotRef, observedAt: loaded.value.observedAt, proposals: loaded.value.proposals }, current: input.current, ...input.callbacks });
+                    }
+                    catch (cause) {
+                        return { ok: false, error: { kind: "diff-error", message: "Proposal diff threw", cause } };
+                    }
+                    if (!derived.ok)
+                        return { ok: false, error: { kind: "diff-error", message: derived.error.message, cause: derived.error } };
+                    const normalized = normalizeDiff(derived.value);
+                    events = normalized.events;
+                    facts = [{ kind: "proposal-set-facts", priorSnapshotRef: loaded.value.snapshotRef, currentSnapshotRef: input.current.snapshotRef, origin: input.source.kind, resolution: "observation", value: normalized.facts }];
+                }
+                try {
+                    JSON.stringify({ events, facts });
+                }
+                catch (cause) {
+                    return { ok: false, error: { kind: "serialization-error", message: "Drift result is not serializable", cause } };
+                }
+                const committed = await options.store.commit({ observation: input.current, recordedAt, check: input.check }, loaded.value?.observationId ?? null);
+                if (!committed.ok)
+                    return { ok: false, error: { kind: "persistence-error", message: committed.error.message, cause: committed.error } };
+                return { ok: true, value: { sourceId: input.source.id, events, facts, priorObservationId, committedObservation: committed.value, warnings: committed.warnings ?? [] } };
+            }
+            catch (cause) {
+                return { ok: false, error: { kind: "unexpected", message: "Drift emission failed", cause } };
+            }
+        },
+    };
+}

package/dist/src/index.d.ts

@@ -6,8 +6,10 @@ export type { ChangedResult, CheckResult, CheckResultCommon, ErrorResult, Lookou
 export { defaultProviderResolver } from "./provider-resolution.js";
 export type { ProviderResolver } from "./provider-resolution.js";
 export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError, } from "./registry.js";
-export type { LookoutRegistryDocument, LookoutSource, LookoutSourceKind, RenderPolicy, } from "./registry.js";
-export { createLookoutSnapshotStore } from "./snapshot-store.js";
+export type { ExtractableLookoutSource, LookoutRegistryDocument, LookoutSource, LookoutSourceKind, RenderPolicy, StructuredFileFormat, StructuredFileLookoutSource, } from "./registry.js";
+export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-store.js";
+export type { ResolveLookoutSnapshotOptions } from "./snapshot-store.js";
+export type { SnapshotSourceRefResolution } from "@kontourai/forage/fetch";
 export { canonicalValueKey } from "./canonical-value.js";
 export type { CanonicalValueKey, CanonicalValueFormatVersion, CanonicalValueResult, DiffKernelError, DiffKernelErrorKind, DiffResult, IdentityResult, } from "./canonical-value.js";
 export { compareStructural, diffKeyedMultiset } from "./structural-diff.js";
@@ -16,5 +18,9 @@ export { diffProposalSets, extractionProposalIdentity } from "./proposal-diff.js
 export type { FieldChangedEvent, FieldChangeKind, NewEntityAppearedEvent, ProposalDiffEvent, ProposalEvidence, ProposalIdentity, ProposalOccurrencePair, ProposalSetDiff, ProposalSetDiffInput, ProposalSetFacts, ProposalSetObservation, ProvenanceChangeFact, } from "./proposal-diff.js";
 export { createObservationStore } from "./observation-store.js";
 export type { CreateObservationStoreOptions, ObservationCheckAnchor, ObservationStore, ObservationStoreError, ObservationStoreErrorKind, ObservationStoreResult, ProposalObservationRecordInput, StoredProposalObservationV1 } from "./observation-store.js";
-export { createSurveyEmitter } from "./survey-emission.js";
-export type { BaselineEstablishedFact, CreateSurveyEmitterOptions, EmissionError, EmissionErrorKind, EmissionFact, EmissionResult, EmissionSuccess, EmitSurveyInput, SurveyEmitter } from "./survey-emission.js";
+export { createDriftEmitter } from "./drift-emission.js";
+export type { BaselineEstablishedFact, CreateDriftEmitterOptions, DriftEmitter, DriftError, DriftErrorKind, DriftFact, DriftResult, DriftSuccess, EmitDriftInput } from "./drift-emission.js";
+export { checkSchemaCoverage } from "./coverage.js";
+export type { SchemaCoverageGap, SchemaCoverageResult } from "./coverage.js";
+export { createObserveExtractDiff } from "./observe-extract-diff.js";
+export type { ObserveExtractAcquisition, ObserveExtractAttempt, ObserveExtractDiff, ObserveExtractDiffOptions, ObserveExtractError, ObserveExtractErrorKind, ObserveExtractExtraction, ObserveExtractExtractionInput, ObserveExtractObservation, ObserveExtractObservationIdentity, ObserveExtractOutcome, ObserveExtractProviderFailure, ObserveExtractRecorder, ObserveExtractResult, ObserveExtractSource, ObserveExtractSourceSnapshot, } from "./observe-extract-diff.js";

package/dist/src/index.js

@@ -2,9 +2,11 @@ export { runCli } from "./cli.js";
 export { createCheckRunner } from "./check-runner.js";
 export { defaultProviderResolver } from "./provider-resolution.js";
 export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError, } from "./registry.js";
-export { createLookoutSnapshotStore } from "./snapshot-store.js";
+export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-store.js";
 export { canonicalValueKey } from "./canonical-value.js";
 export { compareStructural, diffKeyedMultiset } from "./structural-diff.js";
 export { diffProposalSets, extractionProposalIdentity } from "./proposal-diff.js";
 export { createObservationStore } from "./observation-store.js";
-export { createSurveyEmitter } from "./survey-emission.js";
+export { createDriftEmitter } from "./drift-emission.js";
+export { checkSchemaCoverage } from "./coverage.js";
+export { createObserveExtractDiff } from "./observe-extract-diff.js";

package/dist/src/observe-extract-diff.d.ts

@@ -0,0 +1,90 @@
+import type { ExtractionPartial, ExtractionProviderFailure, ExtractionResult, PreparedArtifact } from "@kontourai/traverse";
+import type { CheckResult } from "./check-result.js";
+import type { ProposalSetObservation } from "./proposal-diff.js";
+import type { LookoutSource } from "./registry.js";
+/** Acquisition is supplied by the caller; Lookout does not add another fetcher. */
+export interface ObserveExtractAcquisition {
+    check(source: LookoutSource): Promise<CheckResult>;
+}
+/**
+ * Extraction is supplied by the caller. The input carries only immutable source
+ * identity, leaving snapshot resolution, preparation, and provider selection
+ * outside Lookout.
+ */
+export interface ObserveExtractExtraction {
+    extract(input: ObserveExtractExtractionInput): Promise<ExtractionResult>;
+}
+export interface ObserveExtractExtractionInput {
+    readonly source: LookoutSource;
+    readonly snapshotRef: string;
+}
+export interface ObserveExtractAttempt {
+    readonly extractedAt: string;
+    readonly providerCalls: number;
+    readonly totalTokensUsed: number;
+    readonly partial?: ExtractionPartial;
+    readonly providerFailures?: readonly ObserveExtractProviderFailure[];
+}
+/** Provider-neutral durable classification; diagnostic payloads stay at the capability boundary. */
+export interface ObserveExtractProviderFailure {
+    readonly kind: ExtractionProviderFailure["kind"];
+    readonly retryable: boolean;
+}
+export interface ObserveExtractSourceSnapshot {
+    readonly priorSnapshotRef: string | null;
+    readonly currentSnapshotRef: string;
+}
+export interface ObserveExtractSource {
+    readonly id: string;
+    readonly url: string;
+    readonly kind: LookoutSource["kind"];
+}
+export type ObserveExtractOutcome = "acquisition-error" | "unchanged" | "completed" | "partial" | "partial-provider-failure" | "provider-failure" | "extraction-failure";
+/**
+ * One source observation, ready for caller-owned durable recording. Raw
+ * provider responses and source bodies are intentionally not copied here.
+ */
+export interface ObserveExtractObservation {
+    readonly source: ObserveExtractSource;
+    readonly check: CheckResult;
+    readonly outcome: ObserveExtractOutcome;
+    readonly sourceSnapshot: ObserveExtractSourceSnapshot | null;
+    readonly preparedArtifact: PreparedArtifact | null;
+    readonly proposalSet: ProposalSetObservation | null;
+    readonly attempt: ObserveExtractAttempt | null;
+}
+export interface ObserveExtractObservationIdentity {
+    readonly observationId: string;
+    readonly priorObservationId: string | null;
+}
+/**
+ * Lookout passes each completed observation to a caller-owned recorder. The
+ * recorder controls durable storage and continuity while this composition never
+ * supplies or configures the injected acquisition or extraction capabilities.
+ */
+export interface ObserveExtractRecorder {
+    record(observation: ObserveExtractObservation): Promise<ObserveExtractObservationIdentity>;
+}
+export interface ObserveExtractDiffOptions {
+    readonly acquisition: ObserveExtractAcquisition;
+    readonly extraction: ObserveExtractExtraction;
+    readonly recorder: ObserveExtractRecorder;
+}
+export type ObserveExtractErrorKind = "acquisition-threw" | "recording-failed" | "dependency-contract";
+export interface ObserveExtractError {
+    readonly kind: ObserveExtractErrorKind;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export type ObserveExtractResult = {
+    readonly ok: true;
+    readonly value: ObserveExtractObservation & ObserveExtractObservationIdentity;
+} | {
+    readonly ok: false;
+    readonly error: ObserveExtractError;
+    readonly observation?: ObserveExtractObservation;
+};
+export interface ObserveExtractDiff {
+    observe(source: LookoutSource): Promise<ObserveExtractResult>;
+}
+export declare function createObserveExtractDiff(options: ObserveExtractDiffOptions): ObserveExtractDiff;

package/dist/src/observe-extract-diff.js

@@ -0,0 +1,154 @@
+import { validatePreparedArtifact } from "@kontourai/traverse";
+export function createObserveExtractDiff(options) {
+    return {
+        async observe(source) {
+            try {
+                let check;
+                try {
+                    check = await options.acquisition.check(source);
+                }
+                catch (cause) {
+                    return { ok: false, error: error("acquisition-threw", "Acquisition capability threw", cause) };
+                }
+                if (!isCheckResult(check)) {
+                    return { ok: false, error: error("dependency-contract", "Acquisition capability returned an invalid check result") };
+                }
+                if (check.sourceId !== source.id || check.sourceUrl !== source.url) {
+                    return { ok: false, error: error("dependency-contract", "Acquisition result does not identify the requested source") };
+                }
+                if (check.kind === "error") {
+                    return record(options.recorder, baseObservation(source, check, "acquisition-error", null, null, null, null));
+                }
+                if (check.kind === "unchanged-304" || check.kind === "unchanged-hash") {
+                    return record(options.recorder, baseObservation(source, check, "unchanged", snapshotFor(check), null, null, null));
+                }
+                const sourceSnapshot = snapshotFor(check);
+                let extraction;
+                try {
+                    extraction = await options.extraction.extract({ source, snapshotRef: sourceSnapshot.currentSnapshotRef });
+                }
+                catch {
+                    return record(options.recorder, baseObservation(source, check, "extraction-failure", sourceSnapshot, null, null, null));
+                }
+                if (!isExtractionResult(extraction)) {
+                    return { ok: false, error: error("dependency-contract", "Extraction capability returned an invalid extraction result") };
+                }
+                const attempt = attemptFor(extraction);
+                const proposalSet = {
+                    sourceId: source.id,
+                    snapshotRef: sourceSnapshot.currentSnapshotRef,
+                    observedAt: extraction.extractedAt,
+                    proposals: extraction.proposals,
+                };
+                const outcome = outcomeFor(extraction);
+                if (outcome !== "extraction-failure") {
+                    if (extraction.preparedArtifact === undefined) {
+                        return { ok: false, error: error("dependency-contract", "Extraction result is missing its prepared artifact") };
+                    }
+                }
+                if (extraction.preparedArtifact !== undefined) {
+                    const validation = validatePreparedArtifact(extraction.preparedArtifact);
+                    if (validation.status !== "valid") {
+                        return { ok: false, error: error("dependency-contract", `Extraction result has an invalid prepared artifact: ${validation.status}`) };
+                    }
+                    if (validation.artifact.sourceSnapshotRef !== sourceSnapshot.currentSnapshotRef) {
+                        return { ok: false, error: error("dependency-contract", "Prepared artifact does not identify the current source snapshot") };
+                    }
+                }
+                return record(options.recorder, baseObservation(source, check, outcome, sourceSnapshot, extraction.preparedArtifact ?? null, proposalSet, attempt));
+            }
+            catch (cause) {
+                return { ok: false, error: error("dependency-contract", "Observe-extract composition could not inspect a capability result", cause) };
+            }
+        },
+    };
+}
+function baseObservation(source, check, outcome, sourceSnapshot, preparedArtifact, proposalSet, attempt) {
+    return {
+        source: { id: source.id, url: source.url, kind: source.kind },
+        check,
+        outcome,
+        sourceSnapshot,
+        preparedArtifact,
+        proposalSet,
+        attempt,
+    };
+}
+async function record(recorder, observation) {
+    try {
+        const identity = await recorder.record(observation);
+        if (!isIdentity(identity)) {
+            return { ok: false, error: error("dependency-contract", "Observation recorder returned an invalid identity"), observation };
+        }
+        return {
+            ok: true,
+            value: {
+                ...observation,
+                observationId: identity.observationId,
+                priorObservationId: identity.priorObservationId,
+            },
+        };
+    }
+    catch (cause) {
+        return { ok: false, error: error("recording-failed", "Observation recorder failed", cause), observation };
+    }
+}
+function snapshotFor(check) {
+    if (check.kind === "unchanged-304")
+        return { priorSnapshotRef: check.snapshotRef, currentSnapshotRef: check.snapshotRef };
+    return { priorSnapshotRef: check.priorSnapshotRef, currentSnapshotRef: check.currentSnapshotRef };
+}
+function attemptFor(result) {
+    return {
+        extractedAt: result.extractedAt,
+        providerCalls: result.providerCalls,
+        totalTokensUsed: result.totalTokensUsed,
+        ...(result.partial === undefined ? {} : { partial: result.partial }),
+        ...(result.providerFailures === undefined ? {} : {
+            providerFailures: result.providerFailures.map(({ kind, retryable }) => ({ kind, retryable })),
+        }),
+    };
+}
+function outcomeFor(result) {
+    const hasProviderFailures = (result.providerFailures?.length ?? 0) > 0;
+    if (result.partial !== undefined && hasProviderFailures)
+        return "partial-provider-failure";
+    if (hasProviderFailures)
+        return "provider-failure";
+    if (result.error !== undefined)
+        return "extraction-failure";
+    return result.partial === undefined ? "completed" : "partial";
+}
+function isCheckResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const result = value;
+    if (typeof result.sourceId !== "string" || typeof result.sourceUrl !== "string" ||
+        typeof result.checkedAt !== "string" || !Array.isArray(result.warnings))
+        return false;
+    if (result.kind === "unchanged-304")
+        return typeof result.snapshotRef === "string";
+    if (result.kind === "unchanged-hash")
+        return typeof result.priorSnapshotRef === "string" && typeof result.currentSnapshotRef === "string";
+    if (result.kind === "changed")
+        return (result.priorSnapshotRef === null || typeof result.priorSnapshotRef === "string") &&
+            typeof result.currentSnapshotRef === "string" && (result.changeBasis === "initial" || result.changeBasis === "hash");
+    return result.kind === "error" && (result.origin === "forage" || result.origin === "lookout") && result.error !== undefined;
+}
+function isExtractionResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const result = value;
+    return Array.isArray(result.proposals) && typeof result.extractedAt === "string" &&
+        Number.isFinite(result.providerCalls) && Number.isFinite(result.totalTokensUsed);
+}
+function isIdentity(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const identity = value;
+    return typeof identity.observationId === "string" && identity.observationId !== "" &&
+        (identity.priorObservationId === null || (typeof identity.priorObservationId === "string" && identity.priorObservationId !== ""));
+}
+function error(kind, text, cause) {
+    return { kind, message: text, ...(cause === undefined ? {} : { cause }) };
+}

package/dist/src/registry.d.ts

@@ -1,14 +1,25 @@
 import type { TargetFieldSchema } from "@kontourai/traverse";
-export type LookoutSourceKind = "web-page" | "api-record";
+export type LookoutSourceKind = "web-page" | "api-record" | "structured-file";
+export type StructuredFileFormat = "yaml" | "json" | "csv";
 export type RenderPolicy = "never" | "on-shell-warning" | "always";
-export interface LookoutSource {
+interface LookoutSourceBase {
     id: string;
-    kind: LookoutSourceKind;
     url: string;
-    targetSchema: TargetFieldSchema[];
     cadenceHint: string;
+}
+export interface ExtractableLookoutSource extends LookoutSourceBase {
+    kind: "web-page" | "api-record";
+    targetSchema: TargetFieldSchema[];
     renderPolicy: RenderPolicy;
+    format?: never;
+}
+export interface StructuredFileLookoutSource extends LookoutSourceBase {
+    kind: "structured-file";
+    format: StructuredFileFormat;
+    targetSchema?: never;
+    renderPolicy?: never;
 }
+export type LookoutSource = ExtractableLookoutSource | StructuredFileLookoutSource;
 export interface LookoutRegistryDocument {
     version: 1;
     sources: LookoutSource[];
@@ -27,3 +38,4 @@ export declare class LookoutRegistry {
 }
 export declare function loadRegistry(registryPath?: string): Promise<LookoutRegistry>;
 export declare function parseRegistry(value: unknown): LookoutRegistry;
+export {};

package/dist/src/registry.js

@@ -49,55 +49,120 @@ export function parseRegistry(value) {
     const ids = new Map();
     const sources = [];
     value.sources.forEach((candidate, index) => {
-        const context = `sources[${index}]`;
-        if (!isRecord(candidate)) {
-            issues.push(`${context} must be an object`);
-            return;
-        }
-        const id = candidate.id;
-        const label = typeof id === "string" && id.trim() ? `${context} (id "${id}")` : context;
-        if (typeof id !== "string" || id.trim() === "") {
-            issues.push(`${context}.id must be a non-empty string`);
-        }
-        else {
-            const first = ids.get(id);
-            if (first !== undefined)
-                issues.push(`${label}.id duplicates sources[${first}].id`);
-            else
-                ids.set(id, index);
-        }
-        if (candidate.kind !== "web-page" && candidate.kind !== "api-record") {
-            issues.push(`${label}.kind must be "web-page" or "api-record"`);
-        }
-        if (!isHttpUrl(candidate.url)) {
-            issues.push(`${label}.url must be an absolute HTTP(S) URL`);
-        }
-        if (typeof candidate.cadenceHint !== "string" || candidate.cadenceHint.trim() === "") {
-            issues.push(`${label}.cadenceHint must be a non-empty string`);
-        }
-        if (candidate.renderPolicy !== "never" &&
-            candidate.renderPolicy !== "on-shell-warning" &&
-            candidate.renderPolicy !== "always") {
-            issues.push(`${label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
-        }
-        validateTargetSchema(candidate.targetSchema, label, issues);
-        if (typeof id === "string" && id.trim() !== "" &&
-            (candidate.kind === "web-page" || candidate.kind === "api-record") &&
-            isHttpUrl(candidate.url) &&
-            typeof candidate.cadenceHint === "string" && candidate.cadenceHint.trim() !== "" &&
-            (candidate.renderPolicy === "never" || candidate.renderPolicy === "on-shell-warning" || candidate.renderPolicy === "always") &&
-            Array.isArray(candidate.targetSchema)) {
-            sources.push(candidate);
-        }
+        const source = parseSource(candidate, index, ids, issues);
+        if (source !== undefined)
+            sources.push(source);
     });
     if (issues.length > 0)
         throw new RegistryValidationError(issues);
     return new LookoutRegistry(sources);
 }
+function parseSource(candidate, index, ids, issues) {
+    const context = `sources[${index}]`;
+    if (!isRecord(candidate)) {
+        issues.push(`${context} must be an object`);
+        return undefined;
+    }
+    const firstIssue = issues.length;
+    const common = validateCommonSource(candidate, index, ids, issues);
+    const source = candidate.kind === "structured-file"
+        ? parseStructuredFileSource(candidate, common, issues)
+        : candidate.kind === "web-page" || candidate.kind === "api-record"
+            ? parseExtractableSource(candidate, candidate.kind, common, issues)
+            : invalidSourceKind(candidate, common.label, issues);
+    return issues.length === firstIssue ? source : undefined;
+}
+function validateCommonSource(candidate, index, ids, issues) {
+    const context = `sources[${index}]`;
+    const id = typeof candidate.id === "string" && candidate.id.trim() !== "" ? candidate.id : undefined;
+    const label = id === undefined ? context : `${context} (id "${id}")`;
+    if (id === undefined) {
+        issues.push(`${context}.id must be a non-empty string`);
+    }
+    else {
+        const first = ids.get(id);
+        if (first !== undefined)
+            issues.push(`${label}.id duplicates sources[${first}].id`);
+        else
+            ids.set(id, index);
+    }
+    const url = isHttpUrl(candidate.url) ? candidate.url : undefined;
+    if (url === undefined) {
+        issues.push(`${label}.url must be an absolute HTTP(S) URL`);
+    }
+    const cadenceHint = typeof candidate.cadenceHint === "string" && candidate.cadenceHint.trim() !== ""
+        ? candidate.cadenceHint
+        : undefined;
+    if (cadenceHint === undefined) {
+        issues.push(`${label}.cadenceHint must be a non-empty string`);
+    }
+    return { id, url, cadenceHint, label };
+}
+function parseStructuredFileSource(candidate, common, issues) {
+    if (!isStructuredFileFormat(candidate.format)) {
+        issues.push(`${common.label}.format must be "yaml", "json", or "csv"`);
+    }
+    if (candidate.targetSchema !== undefined) {
+        issues.push(`${common.label}.targetSchema is not allowed for structured-file sources`);
+    }
+    if (candidate.renderPolicy !== undefined) {
+        issues.push(`${common.label}.renderPolicy is not allowed for structured-file sources`);
+    }
+    if (common.id === undefined || common.url === undefined || common.cadenceHint === undefined ||
+        !isStructuredFileFormat(candidate.format))
+        return undefined;
+    return {
+        id: common.id,
+        kind: "structured-file",
+        format: candidate.format,
+        url: common.url,
+        cadenceHint: common.cadenceHint,
+    };
+}
+function parseExtractableSource(candidate, kind, common, issues) {
+    if (!isRenderPolicy(candidate.renderPolicy)) {
+        issues.push(`${common.label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
+    }
+    const targetSchema = validateTargetSchema(candidate.targetSchema, common.label, issues)
+        ? candidate.targetSchema
+        : undefined;
+    if (candidate.format !== undefined) {
+        issues.push(`${common.label}.format is only allowed for structured-file sources`);
+    }
+    if (common.id === undefined || common.url === undefined || common.cadenceHint === undefined ||
+        !isRenderPolicy(candidate.renderPolicy) || targetSchema === undefined)
+        return undefined;
+    return {
+        id: common.id,
+        kind,
+        url: common.url,
+        targetSchema,
+        cadenceHint: common.cadenceHint,
+        renderPolicy: candidate.renderPolicy,
+    };
+}
+function invalidSourceKind(candidate, label, issues) {
+    issues.push(`${label}.kind must be "web-page", "api-record", or "structured-file"`);
+    if (!isRenderPolicy(candidate.renderPolicy)) {
+        issues.push(`${label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
+    }
+    validateTargetSchema(candidate.targetSchema, label, issues);
+    if (candidate.format !== undefined) {
+        issues.push(`${label}.format is only allowed for structured-file sources`);
+    }
+    return undefined;
+}
+function isStructuredFileFormat(value) {
+    return value === "yaml" || value === "json" || value === "csv";
+}
+function isRenderPolicy(value) {
+    return value === "never" || value === "on-shell-warning" || value === "always";
+}
 function validateTargetSchema(value, context, issues) {
+    const firstIssue = issues.length;
     if (!Array.isArray(value)) {
         issues.push(`${context}.targetSchema must be an array`);
-        return;
+        return false;
     }
     const allowedTypes = new Set(["string", "number", "boolean", "date", "enum", "array", "object"]);
     value.forEach((field, index) => {
@@ -124,6 +189,7 @@ function validateTargetSchema(value, context, issues) {
             issues.push(`${label}.inferenceType must be "explicit" or "inferred"`);
         }
     });
+    return issues.length === firstIssue;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/src/snapshot-store.d.ts

@@ -1,2 +1,12 @@
-import type { SnapshotStore } from "@kontourai/traverse/fetch";
+import type { SnapshotStore } from "@kontourai/forage";
+import { type SnapshotSourceRefResolution } from "@kontourai/forage/fetch";
 export declare function createLookoutSnapshotStore(root?: string): SnapshotStore;
+export type ResolveLookoutSnapshotOptions = {
+    store: SnapshotStore;
+    root?: never;
+} | {
+    store?: never;
+    root?: string;
+};
+/** Replay one Lookout-emitted durable reference without any network access. */
+export declare function resolveLookoutSnapshot(reference: string, options?: ResolveLookoutSnapshotOptions): Promise<SnapshotSourceRefResolution>;