@kontourai/lookout 0.4.0 → 0.5.1

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,10 @@ 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 { admitSourceCapture, admitSourceCheck } from "./source-admission.js";
+export type { AdmittedSourceCapture, AdmittedSourceCheck, SourceAdmissionError, SourceAdmissionResult } from "./source-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,8 @@ 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 { admitSourceCapture, admitSourceCheck } from "./source-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,59 @@
+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;
+};
+/** A stable exact-reader capability, captured before asynchronous admission begins. */
+export declare function captureExactSnapshotReader(store: SnapshotStore): SnapshotStore | null;
+export type SnapshotSourceBinding = "url-binding" | "redirect-binding";
+/**
+ * Bind an authenticated snapshot to a registry source without exposing its
+ * body. Historical direct captures can predate a registry URL change, but a
+ * legacy reference cannot authenticate any redirect capture.
+ */
+export declare function snapshotSourceBinding(registeredUrl: string, finalUrl: string, redirects: readonly string[] | undefined, integrity: "snapshot-envelope" | "body-and-identity", current: boolean): SnapshotSourceBinding | null;
+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>;
+export declare function normalizedHttpUrl(value: string): string | null;
+/** Forage records visited redirect URLs before the final URL. */
+export declare function validRedirectChain(redirects: readonly string[], finalUrl: string): boolean;

package/dist/src/observation-admission.js

@@ -0,0 +1,144 @@
+import { resolveLookoutSnapshot } from "./snapshot-store.js";
+/** A stable exact-reader capability, captured before asynchronous admission begins. */
+export function captureExactSnapshotReader(store) {
+    try {
+        if (!store || typeof store !== "object" || typeof store.findExact !== "function")
+            return null;
+        const findExact = store.findExact.bind(store);
+        return { findExact };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bind an authenticated snapshot to a registry source without exposing its
+ * body. Historical direct captures can predate a registry URL change, but a
+ * legacy reference cannot authenticate any redirect capture.
+ */
+export function snapshotSourceBinding(registeredUrl, finalUrl, redirects, integrity, current) {
+    const registered = normalizedHttpUrl(registeredUrl);
+    const final = normalizedHttpUrl(finalUrl);
+    if (registered === null || final === null)
+        return "url-binding";
+    if (!redirects?.length)
+        return !current || final === registered ? null : "url-binding";
+    if (integrity !== "snapshot-envelope" || !validRedirectChain(redirects, finalUrl))
+        return "redirect-binding";
+    return !current || normalizedHttpUrl(redirects[0]) === registered ? null : "redirect-binding";
+}
+/**
+ * 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 });
+        const snapshotStore = captureExactSnapshotReader(input.snapshotStore);
+        return snapshotStore === null ? null : { ...image, snapshotStore };
+    }
+    catch {
+        return null;
+    }
+}
+export 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 binding = snapshotSourceBinding(registeredUrl, finalUrl, redirects, integrity, true);
+    if (binding === "url-binding")
+        return failure("insufficient-binding", "url-binding", "Snapshot URL is not bound to the registered source");
+    if (binding === "redirect-binding")
+        return failure("insufficient-binding", "redirect-binding", "Snapshot redirect capture is not admissibly bound");
+    return null;
+}
+/** Forage records visited redirect URLs before the final URL. */
+export 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/dist/src/source-admission.d.ts

@@ -0,0 +1,37 @@
+import type { SnapshotStore } from "@kontourai/forage";
+import type { CheckResult } from "./check-result.js";
+import { type AdmittedSnapshotIdentity } from "./observation-admission.js";
+import { type LookoutSource } from "./registry.js";
+export type SourceAdmissionError = {
+    readonly kind: "invalid-input" | "unresolved" | "insufficient-binding";
+    readonly message: string;
+};
+export type SourceAdmissionResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: SourceAdmissionError;
+};
+export interface AdmittedSourceCapture {
+    readonly capture: AdmittedSnapshotIdentity;
+}
+export interface AdmittedSourceCheck {
+    readonly prior: AdmittedSnapshotIdentity | null;
+    readonly current: AdmittedSnapshotIdentity;
+    readonly checkedAt: string;
+    readonly resultKind: Exclude<CheckResult["kind"], "error">;
+}
+/** Metadata-only capture admission; it neither fetches nor persists. */
+export declare function admitSourceCapture(input: {
+    source: LookoutSource;
+    snapshotRef: string;
+    snapshotStore: SnapshotStore;
+}): Promise<SourceAdmissionResult<AdmittedSourceCapture>>;
+/** Admit a genuine CheckRunner outcome; this validates relationships, not HTTP provenance. */
+export declare function admitSourceCheck(input: {
+    source: LookoutSource;
+    check: CheckResult;
+    expectedPriorSnapshotRef: string | null;
+    snapshotStore: SnapshotStore;
+}): Promise<SourceAdmissionResult<AdmittedSourceCheck>>;

package/dist/src/source-admission.js

@@ -0,0 +1,138 @@
+import { parseSnapshotSourceRef } from "@kontourai/forage/fetch";
+import { captureExactSnapshotReader, normalizedHttpUrl, snapshotSourceBinding, } from "./observation-admission.js";
+import { parseRegistry } from "./registry.js";
+import { resolveLookoutSnapshot } from "./snapshot-store.js";
+/** Metadata-only capture admission; it neither fetches nor persists. */
+export async function admitSourceCapture(input) {
+    const captured = captureCapture(input);
+    if (!captured || !validSource(captured.source) || !canonicalRef(captured.snapshotRef))
+        return fail("invalid-input", "Capture admission input is malformed");
+    const value = await resolve(captured.source, captured.snapshotRef, captured.snapshotStore, true);
+    return value.ok ? { ok: true, value: { capture: value.value } } : value;
+}
+/** Admit a genuine CheckRunner outcome; this validates relationships, not HTTP provenance. */
+export async function admitSourceCheck(input) {
+    const captured = captureCheck(input);
+    if (!captured || !validSource(captured.source) || !validCheck(captured.source, captured.check))
+        return fail("invalid-input", "Check admission input is malformed");
+    const check = captured.check;
+    if (check.kind === "error")
+        return fail("invalid-input", "An error result has no successful capture");
+    const refs = refsFor(check, captured.expectedPriorSnapshotRef);
+    // Validate every durable reference before the first exact lookup: admission
+    // never lets a malformed historical anchor cause partial capability I/O.
+    if (!refs || !canonicalRef(refs.current) || (refs.prior !== null && !canonicalRef(refs.prior)))
+        return fail("invalid-input", "Check references do not match the expected baseline");
+    const current = await resolve(captured.source, refs.current, captured.snapshotStore, true);
+    if (!current.ok)
+        return current;
+    const prior = refs.prior === null ? null : await resolve(captured.source, refs.prior, captured.snapshotStore, false);
+    if (prior !== null && !prior.ok)
+        return prior;
+    if (check.kind === "unchanged-hash" && prior !== null && prior.ok && (prior.value.bodyHash !== current.value.bodyHash || prior.value.url !== current.value.url))
+        return fail("insufficient-binding", "Same-hash result does not bind one resource capture");
+    if (check.kind === "changed" && check.changeBasis === "hash" && prior !== null && prior.ok && prior.value.bodyHash === current.value.bodyHash && prior.value.url === current.value.url)
+        return fail("insufficient-binding", "Changed result does not bind a changed capture");
+    return { ok: true, value: { prior: prior?.ok ? prior.value : null, current: current.value, checkedAt: check.checkedAt, resultKind: check.kind } };
+}
+function refsFor(check, expected) {
+    if (check.kind === "unchanged-304")
+        return expected !== null && check.snapshotRef === expected ? { prior: expected, current: check.snapshotRef } : null;
+    if (check.kind === "unchanged-hash")
+        return check.priorSnapshotRef === expected ? { prior: expected, current: check.currentSnapshotRef } : null;
+    return check.changeBasis === "initial"
+        ? expected === null ? { prior: null, current: check.currentSnapshotRef } : null
+        : check.priorSnapshotRef === expected && expected !== null ? { prior: expected, current: check.currentSnapshotRef } : null;
+}
+function validSource(source) {
+    try {
+        if (!source || typeof source !== "object" || normalizedHttpUrl(source.url) === null)
+            return false;
+        parseRegistry({ version: 1, sources: [source] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validCheck(source, check) {
+    if (!check || typeof check !== "object" || Array.isArray(check))
+        return false;
+    const common = () => check.sourceId === source.id && check.sourceUrl === source.url && validTimestamp(check.checkedAt) && validWarnings(check.warnings);
+    if (check.kind === "unchanged-304")
+        return closed(check, ["sourceId", "sourceUrl", "checkedAt", "warnings", "kind", "snapshotRef"]) && common() && typeof check.snapshotRef === "string";
+    if (check.kind === "unchanged-hash")
+        return closed(check, ["sourceId", "sourceUrl", "checkedAt", "warnings", "kind", "priorSnapshotRef", "currentSnapshotRef"]) && common() && typeof check.priorSnapshotRef === "string" && typeof check.currentSnapshotRef === "string";
+    if (check.kind === "changed")
+        return closed(check, ["sourceId", "sourceUrl", "checkedAt", "warnings", "kind", "priorSnapshotRef", "currentSnapshotRef", "changeBasis"]) && common() && typeof check.currentSnapshotRef === "string" && (check.changeBasis === "initial" || check.changeBasis === "hash") && (check.changeBasis === "initial" ? check.priorSnapshotRef === null : typeof check.priorSnapshotRef === "string");
+    return false;
+}
+function closed(value, keys) {
+    if (Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function validWarnings(value) {
+    if (!Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length !== value.length)
+        return false;
+    for (let index = 0; index < value.length; index++) {
+        if (!Object.hasOwn(value, index) || typeof value[index] !== "string")
+            return false;
+    }
+    return true;
+}
+function validTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const instant = new Date(value);
+    return !Number.isNaN(instant.valueOf()) && instant.toISOString() === value;
+}
+function canonicalRef(value) {
+    if (typeof value !== "string")
+        return false;
+    const parsed = parseSnapshotSourceRef(value);
+    if (!parsed || !/^[a-f0-9]{64}$/.test(parsed.bodyHash) || (parsed.snapshotDigest !== undefined && !/^[a-f0-9]{64}$/.test(parsed.snapshotDigest)))
+        return false;
+    const query = new URLSearchParams({ url: parsed.url, sha256: parsed.bodyHash, fetchedAt: parsed.fetchedAt });
+    if (parsed.snapshotDigest !== undefined)
+        query.set("snapshotSha256", parsed.snapshotDigest);
+    return value === `forage-snapshot:${encodeURIComponent(parsed.sourceId)}?${query.toString()}`;
+}
+function captureCapture(input) {
+    try {
+        if (!input || typeof input !== "object")
+            return null;
+        const snapshotStore = captureExactSnapshotReader(input.snapshotStore);
+        return snapshotStore === null ? null : { ...structuredClone({ source: input.source, snapshotRef: input.snapshotRef }), snapshotStore };
+    }
+    catch {
+        return null;
+    }
+}
+function captureCheck(input) {
+    try {
+        if (!input || typeof input !== "object")
+            return null;
+        const snapshotStore = captureExactSnapshotReader(input.snapshotStore);
+        return snapshotStore === null ? null : { ...structuredClone({ source: input.source, check: input.check, expectedPriorSnapshotRef: input.expectedPriorSnapshotRef }), snapshotStore };
+    }
+    catch {
+        return null;
+    }
+}
+async function resolve(source, ref, store, current) {
+    const resolved = await resolveLookoutSnapshot(ref, { store });
+    if (!resolved.ok || resolved.snapshot.sourceId !== source.id)
+        return fail("unresolved", "Snapshot reference could not be admitted");
+    const binding = snapshotSourceBinding(source.url, resolved.snapshot.url, resolved.snapshot.redirects, resolved.integrity, current);
+    if (binding !== null)
+        return fail("insufficient-binding", binding === "redirect-binding" ? "Snapshot redirect capture is not admissibly bound" : "Snapshot URL is not bound to the registered source");
+    return { ok: true, value: { sourceId: source.id, snapshotRef: ref, url: resolved.snapshot.url, bodyHash: resolved.snapshot.bodyHash, fetchedAt: resolved.snapshot.fetchedAt, ...(resolved.reference.snapshotDigest ? { snapshotDigest: resolved.reference.snapshotDigest } : {}), integrity: resolved.integrity } };
+}
+function fail(kind, message) {
+    return { ok: false, error: { kind, message } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/lookout",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A small source registry and drift-check runner built on Forage snapshots.",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@kontourai/datum": "0.7.0",
-    "@kontourai/forage": "0.6.0",
+    "@kontourai/forage": "0.6.1",
     "@kontourai/traverse": "0.25.1"
   },
   "devDependencies": {