@kontourai/lookout 0.4.0 → 0.5.0

package/README.md

@@ -228,7 +228,7 @@ item, or hard failure — is the consumer's call.
 ```
 lookout check <id> [--registry <path>] [--snapshot-root <path>]
 lookout check --all [--registry <path>] [--snapshot-root <path>]
-lookout emit-drift <id> --observation <path|-> [--registry <path>] [--observation-root <path>]
+lookout emit-drift <id> --observation <path|-> [--registry <path>] [--observation-root <path>] [--snapshot-root <path>]
 ```
 
 - Emits **exactly one compact JSON object per checked source, per stdout line**
@@ -260,6 +260,12 @@ Store paths refuse symbolic links. An existing source lock is not automatically
 broken: after confirming no writer is active, an operator may remove an
 abandoned `.lock` file and retry.
 
+Before an observation can be diffed or committed, `emit-drift` resolves its
+current and selected-prior Forage snapshot references against the configured
+snapshot store. This is an explicit capability (`--snapshot-root` defaults to
+`.kontourai/lookout/snapshots`); missing, corrupt, malformed, or insufficiently
+bound captures produce no facts and no continuity commit.
+
 ## Library
 
 ```ts

package/dist/src/cli.d.ts

@@ -9,6 +9,6 @@ export interface RunCliOptions {
     loadRegistry?(path?: string): Promise<SourceStore>;
     runner?: CheckRunner;
     readObservation?: (path: string) => Promise<unknown>;
-    emitDrift?(sourceId: string, value: unknown, store: SourceStore, observationRoot?: string): Promise<DriftResult>;
+    emitDrift?(sourceId: string, value: unknown, store: SourceStore, observationRoot?: string, snapshotRoot?: string): Promise<DriftResult>;
 }
 export declare function runCli(options?: RunCliOptions): Promise<number>;

package/dist/src/cli.js

@@ -35,7 +35,7 @@ export async function runCli(options = {}) {
             stderr.write(`Could not read observation: ${error instanceof Error ? error.message : String(error)}\n`);
             return 1;
         }
-        const result = await (options.emitDrift ?? emitDrift)(parsed.id, value, store, parsed.observationRoot);
+        const result = await (options.emitDrift ?? emitDrift)(parsed.id, value, store, parsed.observationRoot, parsed.snapshotRoot);
         if (!result.ok) {
             stderr.write(`${result.error.kind}: ${result.error.message}\n`);
             return 1;
@@ -104,9 +104,10 @@ function parseEmitArgs(argv) {
     let observationPath;
     let registryPath;
     let observationRoot;
+    let snapshotRoot;
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
-        if (arg === "--registry" || arg === "--observation" || arg === "--observation-root") {
+        if (arg === "--registry" || arg === "--observation" || arg === "--observation-root" || arg === "--snapshot-root") {
             const value = argv[++index];
             if (!value || (value.startsWith("--") && value !== "-"))
                 return `${arg} requires a path`;
@@ -114,8 +115,10 @@ function parseEmitArgs(argv) {
                 registryPath = value;
             else if (arg === "--observation")
                 observationPath = value;
-            else
+            else if (arg === "--observation-root")
                 observationRoot = value;
+            else
+                snapshotRoot = value;
         }
         else if (arg.startsWith("--"))
             return `Unknown option: ${arg}`;
@@ -128,7 +131,7 @@ function parseEmitArgs(argv) {
         return "emit-drift requires a source id";
     if (!observationPath)
         return "emit-drift requires --observation <path|->";
-    return { command: "emit-drift", id, observationPath, registryPath, observationRoot };
+    return { command: "emit-drift", id, observationPath, registryPath, observationRoot, snapshotRoot };
 }
 async function readObservation(file) {
     const maxBytes = 1024 * 1024;
@@ -164,10 +167,10 @@ function cliEntities(observation) {
     }
     return [...grouped].map(([key, proposals]) => ({ key, proposals }));
 }
-async function emitDrift(sourceId, value, store, observationRoot) {
+async function emitDrift(sourceId, value, store, observationRoot, snapshotRoot) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return { ok: false, error: { kind: "invalid-input", message: "Observation document must be an object" } };
     const document = value;
     const source = (await store.get(sourceId));
-    return createDriftEmitter({ store: createObservationStore({ root: observationRoot }) }).emit({ source, current: document.observation, check: document.check, callbacks: { selectEntities: cliEntities, entityIdentity: (entity) => entity.key, proposalsFor: (entity) => entity.proposals, fieldIdentity: (_entity, proposal) => proposal.fieldPath } });
+    return createDriftEmitter({ store: createObservationStore({ root: observationRoot }), snapshotStore: createLookoutSnapshotStore(snapshotRoot) }).emit({ source, current: document.observation, check: document.check, callbacks: { selectEntities: cliEntities, entityIdentity: (entity) => entity.key, proposalsFor: (entity) => entity.proposals, fieldIdentity: (_entity, proposal) => proposal.fieldPath } });
 }

package/dist/src/drift-emission.d.ts

@@ -1,6 +1,7 @@
 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";
+import type { SnapshotStore } from "@kontourai/forage";
 export interface BaselineEstablishedFact {
     readonly kind: "baseline-established";
     readonly sourceId: string;
@@ -51,6 +52,8 @@ export interface DriftEmitter<E> {
 }
 export interface CreateDriftEmitterOptions<E> {
     readonly store: ObservationStore;
+    /** Required explicit capability for authenticating durable snapshot references. */
+    readonly snapshotStore: SnapshotStore;
     readonly now?: () => string;
     readonly diff?: (input: ProposalSetDiffInput<E>) => {
         readonly ok: true;

package/dist/src/drift-emission.js

@@ -1,4 +1,5 @@
 import { diffProposalSets } from "./proposal-diff.js";
+import { admitProposalObservation } from "./observation-admission.js";
 function stableJson(value) {
     if (Array.isArray(value))
         return `[${value.map(stableJson).join(",")}]`;
@@ -27,23 +28,40 @@ export function createDriftEmitter(options) {
     return {
         async emit(input) {
             try {
-                if (!input.source || input.source.id !== input.current?.sourceId || input.check?.currentSnapshotRef !== input.current?.snapshotRef) {
+                // Copy the complete caller image before the first await. Callers retain
+                // their objects, so resolving a snapshot must not create a time window
+                // in which a mutated ref/proposal is later committed under an admitted one.
+                const invocation = captureInvocation(input);
+                if (!invocation || !invocation.source || invocation.source.id !== invocation.current?.sourceId || invocation.check?.currentSnapshotRef !== invocation.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);
+                // Admit the current reference before continuity I/O.  In particular,
+                // Forage rejects a malformed digest before findExact/loadLatest runs.
+                const currentAdmission = await admitProposalObservation({ source: invocation.source, current: invocation.current, check: invocation.check, prior: null, snapshotStore: options.snapshotStore });
+                if (!currentAdmission.ok)
+                    return { ok: false, error: { kind: "invalid-input", message: "Current observation could not be admitted" } };
+                const loaded = await options.store.loadLatest(invocation.source.id);
                 if (!loaded.ok)
                     return { ok: false, error: { kind: "prior-state-error", message: loaded.error.message, cause: loaded.error } };
+                const prior = loaded.value === null ? null : capture(loaded.value);
+                if (loaded.value !== null && prior === null)
+                    return { ok: false, error: { kind: "prior-state-error", message: "Prior observation could not be captured" } };
+                const admission = await admitProposalObservation({ source: invocation.source, current: invocation.current, check: invocation.check, prior, snapshotStore: options.snapshotStore });
+                if (!admission.ok)
+                    return { ok: false, error: { kind: admission.error.kind === "prior-unresolved" ? "prior-state-error" : "invalid-input", message: "Observation could not be admitted" } };
                 const recordedAt = now();
-                const priorObservationId = loaded.value?.observationId ?? null;
+                const priorObservationId = prior?.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 }];
+                if (prior === null) {
+                    facts = [{ kind: "baseline-established", sourceId: invocation.source.id, snapshotRef: invocation.current.snapshotRef, observedAt: invocation.current.observedAt, origin: invocation.source.kind, resolution: "observation", proposalCount: invocation.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 });
+                        // Diff callbacks receive their own clone, never the image used for
+                        // durable commit below.
+                        derived = diff({ prior: { sourceId: prior.sourceId, snapshotRef: prior.snapshotRef, observedAt: prior.observedAt, proposals: capture(prior.proposals) ?? [] }, current: capture(invocation.current), ...invocation.callbacks });
                     }
                     catch (cause) {
                         return { ok: false, error: { kind: "diff-error", message: "Proposal diff threw", cause } };
@@ -52,7 +70,7 @@ export function createDriftEmitter(options) {
                         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 }];
+                    facts = [{ kind: "proposal-set-facts", priorSnapshotRef: prior.snapshotRef, currentSnapshotRef: invocation.current.snapshotRef, origin: invocation.source.kind, resolution: "observation", value: normalized.facts }];
                 }
                 try {
                     JSON.stringify({ events, facts });
@@ -60,10 +78,10 @@ export function createDriftEmitter(options) {
                 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);
+                const committed = await options.store.commit({ observation: invocation.current, recordedAt, check: invocation.check }, prior?.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 ?? [] } };
+                return { ok: true, value: { sourceId: invocation.source.id, events, facts, priorObservationId, committedObservation: committed.value, warnings: committed.warnings ?? [] } };
             }
             catch (cause) {
                 return { ok: false, error: { kind: "unexpected", message: "Drift emission failed", cause } };
@@ -71,3 +89,22 @@ export function createDriftEmitter(options) {
         },
     };
 }
+function capture(value) { try {
+    return structuredClone(value);
+}
+catch {
+    return null;
+} }
+function captureInvocation(input) {
+    try {
+        if (!input || typeof input !== "object")
+            return null;
+        const image = capture({ source: input.source, current: input.current, check: input.check });
+        if (image === null || !input.callbacks || typeof input.callbacks !== "object")
+            return null;
+        return { ...image, callbacks: { ...input.callbacks } };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/index.d.ts

@@ -11,6 +11,8 @@ export type { SourceStore } from "./source-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 { admitProposalObservation } from "./observation-admission.js";
+export type { AdmitProposalObservationInput, AdmittedProposalObservation, AdmittedSnapshotIdentity, ObservationAdmissionError, ObservationAdmissionErrorKind, ObservationAdmissionResult } from "./observation-admission.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";

package/dist/src/index.js

@@ -4,6 +4,7 @@ export { defaultProviderResolver } from "./provider-resolution.js";
 export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError, } from "./registry.js";
 export { inMemorySourceStore } from "./source-store.js";
 export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-store.js";
+export { admitProposalObservation } from "./observation-admission.js";
 export { canonicalValueKey } from "./canonical-value.js";
 export { compareStructural, diffKeyedMultiset } from "./structural-diff.js";
 export { diffProposalSets, extractionProposalIdentity } from "./proposal-diff.js";

package/dist/src/observation-admission.d.ts

@@ -0,0 +1,47 @@
+import type { SnapshotStore } from "@kontourai/forage";
+import type { LookoutSource } from "./registry.js";
+import type { StoredProposalObservationV1, ObservationCheckAnchor } from "./observation-store.js";
+import type { ProposalSetObservation } from "./proposal-diff.js";
+/** A resolved snapshot identity suitable for durable observation metadata. */
+export interface AdmittedSnapshotIdentity {
+    readonly sourceId: string;
+    readonly snapshotRef: string;
+    readonly url: string;
+    readonly bodyHash: string;
+    readonly fetchedAt: string;
+    /** Present only for Forage envelope-integrity references; never synthesized for legacy refs. */
+    readonly snapshotDigest?: string;
+    readonly integrity: "snapshot-envelope" | "body-and-identity";
+}
+export interface AdmittedProposalObservation {
+    readonly current: AdmittedSnapshotIdentity;
+    readonly prior: AdmittedSnapshotIdentity | null;
+}
+export type ObservationAdmissionErrorKind = "invalid-input" | "current-unresolved" | "prior-unresolved" | "insufficient-binding";
+export interface ObservationAdmissionError {
+    readonly kind: ObservationAdmissionErrorKind;
+    readonly classification: "invalid-reference" | "not-found" | "mismatch" | "corrupt" | "store" | "source-identity" | "url-binding" | "redirect-binding";
+    readonly message: string;
+}
+export type ObservationAdmissionResult = {
+    readonly ok: true;
+    readonly value: AdmittedProposalObservation;
+} | {
+    readonly ok: false;
+    readonly error: ObservationAdmissionError;
+};
+export interface AdmitProposalObservationInput {
+    readonly source: LookoutSource;
+    readonly current: ProposalSetObservation;
+    readonly check: ObservationCheckAnchor;
+    /** The already-selected observation-store record; admission never selects or persists continuity. */
+    readonly prior: StoredProposalObservationV1 | null;
+    /** Explicit capability: admission never chooses a snapshot root or storage implementation. */
+    readonly snapshotStore: SnapshotStore;
+}
+/**
+ * Authenticate proposal-observation snapshot references before they can be
+ * diffed or committed.  It is deliberately metadata-only: it neither exposes
+ * snapshot bodies nor reads/writes the observation store.
+ */
+export declare function admitProposalObservation(input: AdmitProposalObservationInput): Promise<ObservationAdmissionResult>;

package/dist/src/observation-admission.js

@@ -0,0 +1,119 @@
+import { resolveLookoutSnapshot } from "./snapshot-store.js";
+/**
+ * Authenticate proposal-observation snapshot references before they can be
+ * diffed or committed.  It is deliberately metadata-only: it neither exposes
+ * snapshot bodies nor reads/writes the observation store.
+ */
+export async function admitProposalObservation(input) {
+    try {
+        // This is a public asynchronous boundary.  Capture every caller-owned
+        // value before admission starts I/O so a caller cannot splice a later
+        // reference, source identity, or anchor into the authenticated result.
+        const invocation = captureInvocation(input);
+        if (invocation === null)
+            return failure("invalid-input", "source-identity", "Observation admission input is malformed");
+        return await admit(invocation);
+    }
+    catch {
+        return failure("invalid-input", "source-identity", "Observation admission input is malformed");
+    }
+}
+async function admit(invocation) {
+    if (!invocation || typeof invocation !== "object" || !invocation.source || typeof invocation.source !== "object" || !invocation.current || typeof invocation.current !== "object" || !invocation.check || typeof invocation.check !== "object" || !invocation.snapshotStore || typeof invocation.snapshotStore !== "object" ||
+        typeof invocation.source.id !== "string" || typeof invocation.source.url !== "string" || typeof invocation.current.sourceId !== "string" || typeof invocation.current.snapshotRef !== "string" || typeof invocation.check.currentSnapshotRef !== "string" ||
+        invocation.source.id !== invocation.current.sourceId || invocation.check.currentSnapshotRef !== invocation.current.snapshotRef) {
+        return failure("invalid-input", "source-identity", "Registry source, observation, and check anchor must agree");
+    }
+    const registeredUrl = normalizedHttpUrl(invocation.source.url);
+    if (registeredUrl === null)
+        return failure("invalid-input", "url-binding", "Registered source URL is not an admissible HTTP URL");
+    // resolveLookoutSnapshot delegates canonical reference validation to Forage;
+    // its resolver validates before calling findExact, so malformed refs perform
+    // no snapshot-store I/O.
+    const current = await resolveLookoutSnapshot(invocation.current.snapshotRef, { store: invocation.snapshotStore });
+    if (!current.ok)
+        return resolutionFailure("current", current.error.kind);
+    if (current.snapshot.sourceId !== invocation.source.id)
+        return failure("invalid-input", "source-identity", "Current snapshot identity does not match the registered source");
+    const currentBinding = bindCurrentSnapshot(current.snapshot.url, current.snapshot.redirects, current.integrity, registeredUrl);
+    if (currentBinding !== null)
+        return currentBinding;
+    if (invocation.prior === null)
+        return { ok: true, value: { current: identity(invocation.current.snapshotRef, current), prior: null } };
+    if (!invocation.prior || typeof invocation.prior !== "object" || typeof invocation.prior.sourceId !== "string" || typeof invocation.prior.snapshotRef !== "string" || !invocation.prior.check || typeof invocation.prior.check !== "object" || typeof invocation.prior.check.currentSnapshotRef !== "string" ||
+        invocation.prior.sourceId !== invocation.source.id || invocation.prior.check.currentSnapshotRef !== invocation.prior.snapshotRef) {
+        return failure("invalid-input", "source-identity", "Prior observation identity is not valid for the registered source");
+    }
+    const prior = await resolveLookoutSnapshot(invocation.prior.snapshotRef, { store: invocation.snapshotStore });
+    if (!prior.ok)
+        return resolutionFailure("prior", prior.error.kind);
+    if (prior.snapshot.sourceId !== invocation.source.id)
+        return failure("invalid-input", "source-identity", "Prior snapshot identity does not match the registered source");
+    // A historical capture may legitimately precede a registry URL change. It
+    // still needs durable identity authentication, but is not rebound to today’s URL.
+    if (prior.snapshot.redirects?.length && prior.integrity !== "snapshot-envelope") {
+        return failure("insufficient-binding", "redirect-binding", "Legacy snapshot references cannot authenticate redirect captures");
+    }
+    if (prior.snapshot.redirects?.length && !validRedirectChain(prior.snapshot.redirects, prior.snapshot.url)) {
+        return failure("insufficient-binding", "redirect-binding", "Snapshot redirect capture is not admissibly bound");
+    }
+    return { ok: true, value: { current: identity(invocation.current.snapshotRef, current), prior: identity(invocation.prior.snapshotRef, prior) } };
+}
+function identity(snapshotRef, resolved) {
+    return { sourceId: resolved.snapshot.sourceId, snapshotRef, url: resolved.snapshot.url, bodyHash: resolved.snapshot.bodyHash, fetchedAt: resolved.snapshot.fetchedAt, ...(resolved.reference.snapshotDigest === undefined ? {} : { snapshotDigest: resolved.reference.snapshotDigest }), integrity: resolved.integrity };
+}
+function resolutionFailure(side, kind) {
+    const classification = { "invalid-reference": "invalid-reference", "snapshot-not-found": "not-found", "snapshot-mismatch": "mismatch", "snapshot-corrupt": "corrupt", "snapshot-store-error": "store" }[kind];
+    return failure(side === "current" ? "current-unresolved" : "prior-unresolved", classification, `${side === "current" ? "Current" : "Prior"} snapshot reference could not be admitted`);
+}
+function failure(kind, classification, message) { return { ok: false, error: { kind, classification, message } }; }
+function captureInvocation(input) {
+    try {
+        if (!input || typeof input !== "object")
+            return null;
+        const image = structuredClone({ source: input.source, current: input.current, check: input.check, prior: input.prior });
+        return { ...image, snapshotStore: input.snapshotStore };
+    }
+    catch {
+        return null;
+    }
+}
+function normalizedHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password)
+            return null;
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        return null;
+    }
+}
+function bindCurrentSnapshot(finalUrl, redirects, integrity, registeredUrl) {
+    const normalizedFinal = normalizedHttpUrl(finalUrl);
+    if (normalizedFinal === null)
+        return failure("insufficient-binding", "url-binding", "Snapshot URL is not an admissible HTTP URL");
+    if (!redirects?.length)
+        return normalizedFinal === registeredUrl ? null : failure("insufficient-binding", "url-binding", "Snapshot URL is not bound to the registered source");
+    if (integrity !== "snapshot-envelope")
+        return failure("insufficient-binding", "redirect-binding", "Legacy snapshot references cannot authenticate redirect captures");
+    if (normalizedHttpUrl(redirects[0]) !== registeredUrl || !validRedirectChain(redirects, finalUrl))
+        return failure("insufficient-binding", "redirect-binding", "Snapshot redirect capture is not admissibly bound");
+    return null;
+}
+/** Forage records visited redirect URLs before the final URL. */
+function validRedirectChain(redirects, finalUrl) {
+    const urls = [...redirects, finalUrl].map(normalizedHttpUrl);
+    if (urls.some((url) => url === null))
+        return false;
+    const concrete = urls;
+    const parsed = concrete.map((url) => new URL(url));
+    const host = parsed[0].host;
+    for (let index = 0; index < parsed.length; index += 1) {
+        const url = parsed[index];
+        if (url.host !== host || (index > 0 && parsed[index - 1].protocol === "https:" && url.protocol !== "https:"))
+            return false;
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/lookout",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A small source registry and drift-check runner built on Forage snapshots.",
   "license": "Apache-2.0",
   "type": "module",