@kontourai/lookout 0.5.0 → 0.5.2

package/README.md

@@ -256,6 +256,23 @@ latest two valid observations. The emitted `events` are already
 Hachure-evidence-shaped; a consumer or product lifts them into a Hachure
 `TrustBundle` with `@kontourai/surface`'s `TrustBundleBuilder` when it wants
 Surface projection — lookout itself authors nothing in the trust layer.
+
+### Verified proposal head witnesses
+
+The concrete filesystem observation store additionally exposes
+`readVerifiedHead(sourceId, limits)` and `compareHeadWitness(witness, limits)`.
+The first returns an authenticated observation id and snapshot reference with an
+opaque, versioned witness; the second reads only bounded head metadata and
+returns `matches`, `changed`, `missing`, `unavailable`, `corrupt`, or
+`unsupported`. It never reads proposal bytes during comparison.
+
+A witness is an as-of fence, not a freshness guarantee: it binds the source,
+current head, store scope, pointer, and filesystem metadata observed at capture.
+It detects ordinary older writers without requiring them to write a sidecar.
+Restarting the same store preserves a witness; copying or restoring the store
+can invalidate it. It does not prove proposal-body bit-rot or provide an atomic
+transaction across stores. Limits are finite hard caps on enumeration, pointer,
+and authenticated-record reads; callers may only narrow the defaults.
 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.

package/dist/src/index.d.ts

@@ -13,6 +13,8 @@ export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-
 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";
@@ -21,7 +23,7 @@ export type { KeyedMultisetFacts, KeyedMultisetOptions, StructuralComparison, St
 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 type { CreateObservationStoreOptions, HeadWitnessComparison, ObservationCheckAnchor, ObservationStore, ObservationStoreError, ObservationStoreErrorKind, ObservationStoreResult, ProposalHeadWitnessV1, ProposalObservationRecordInput, StoredProposalObservationV1, VerifiedHeadLimits, VerifiedHeadObservationStore, VerifiedHeadRead } from "./observation-store.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";

package/dist/src/index.js

@@ -5,6 +5,7 @@ export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError,
 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

@@ -30,6 +30,15 @@ export type ObservationAdmissionResult = {
     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;
@@ -45,3 +54,6 @@ export interface AdmitProposalObservationInput {
  * 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

@@ -1,4 +1,32 @@
 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
@@ -72,13 +100,14 @@ function captureInvocation(input) {
         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 };
+        const snapshotStore = captureExactSnapshotReader(input.snapshotStore);
+        return snapshotStore === null ? null : { ...image, snapshotStore };
     }
     catch {
         return null;
     }
 }
-function normalizedHttpUrl(value) {
+export function normalizedHttpUrl(value) {
     try {
         const url = new URL(value);
         if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password)
@@ -91,19 +120,15 @@ function normalizedHttpUrl(value) {
     }
 }
 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))
+    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. */
-function validRedirectChain(redirects, finalUrl) {
+export function validRedirectChain(redirects, finalUrl) {
     const urls = [...redirects, finalUrl].map(normalizedHttpUrl);
     if (urls.some((url) => url === null))
         return false;

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

@@ -39,6 +39,42 @@ export interface ObservationStore {
     loadLatest(sourceId: string): Promise<ObservationStoreResult<StoredProposalObservationV1 | null>>;
     commit(input: ProposalObservationRecordInput, expectedPriorId: string | null): Promise<ObservationStoreResult<StoredProposalObservationV1>>;
 }
+/** Finite caller-controlled ceilings for a verified proposal-head read. */
+export interface VerifiedHeadLimits {
+    readonly maxEntries?: number;
+    readonly maxIndexBytes?: number;
+    readonly maxPointerBytes?: number;
+    readonly maxRecordBytes?: number;
+}
+export interface ProposalHeadWitnessV1 {
+    readonly kind: "lookout.proposal-head-witness/v1";
+    readonly version: 1;
+    readonly sourceId: string;
+    readonly observationId: string;
+    /** Opaque binding of this store scope and its bounded metadata-as-of state. */
+    readonly token: string;
+}
+export type VerifiedHeadRead = {
+    readonly kind: "verified";
+    readonly sourceId: string;
+    readonly observationId: string;
+    readonly snapshotRef: string;
+    readonly witness: ProposalHeadWitnessV1;
+} | {
+    readonly kind: "missing" | "unavailable" | "corrupt" | "unsupported";
+};
+export type HeadWitnessComparison = {
+    readonly kind: "matches";
+    readonly sourceId: string;
+    readonly observationId: string;
+} | {
+    readonly kind: "changed" | "missing" | "unavailable" | "corrupt" | "unsupported";
+};
+/** Additive concrete-store capability. Generic ObservationStore implementations need not provide it. */
+export interface VerifiedHeadObservationStore {
+    readVerifiedHead(sourceId: string, limits?: VerifiedHeadLimits): Promise<VerifiedHeadRead>;
+    compareHeadWitness(witness: ProposalHeadWitnessV1, limits?: VerifiedHeadLimits): Promise<HeadWitnessComparison>;
+}
 export interface ObservationStoreFaults {
     readonly beforeSerialize?: () => void;
     readonly beforeTempWrite?: (kind: "record" | "pointer") => void;
@@ -47,9 +83,13 @@ export interface ObservationStoreFaults {
     readonly beforePointerRename?: () => void;
     readonly beforeDirectorySync?: (kind: "record" | "pointer") => void;
     readonly beforePrune?: () => void;
+    /** Test-only fence hooks; production callers do not supply them. */
+    readonly beforeHeadStrongLoad?: () => void;
+    readonly beforeHeadRecordRead?: () => void;
+    readonly beforeHeadAfterFence?: () => void;
 }
 export interface CreateObservationStoreOptions {
     readonly root?: string;
     readonly faults?: ObservationStoreFaults;
 }
-export declare function createObservationStore(options?: CreateObservationStoreOptions): ObservationStore;
+export declare function createObservationStore(options?: CreateObservationStoreOptions): ObservationStore & VerifiedHeadObservationStore;

package/dist/src/observation-store.js

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
-import { lstat, mkdir, open, readFile, readdir, rename, rm, unlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, unlink } from "node:fs/promises";
 import path from "node:path";
+import { types } from "node:util";
+const VERIFIED_HEAD_MAX = Object.freeze({ maxEntries: 8, maxIndexBytes: 8 * 1024, maxPointerBytes: 8 * 1024, maxRecordBytes: 1024 * 1024 });
 function sourceKey(sourceId) {
     return `${encodeURIComponent(sourceId).replaceAll("%", "_").slice(0, 48)}-${createHash("sha256").update(sourceId).digest("hex").slice(0, 16)}`;
 }
@@ -13,6 +16,200 @@ function stable(value) {
 }
 function canonical(value) { return `${JSON.stringify(stable(value))}\n`; }
 function digest(body) { return createHash("sha256").update(canonical(body)).digest("hex"); }
+function resolveHeadLimits(limits) {
+    try {
+        if (limits !== undefined && (!limits || typeof limits !== "object" || types.isProxy(limits) || Array.isArray(limits)))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let supplied;
+    try {
+        const descriptors = limits === undefined ? {} : Object.getOwnPropertyDescriptors(limits);
+        if (Object.keys(descriptors).some((key) => !Object.hasOwn(VERIFIED_HEAD_MAX, key) || descriptors[key]?.get || descriptors[key]?.set))
+            return null;
+        supplied = Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+    }
+    catch {
+        return null;
+    }
+    const resolved = { ...VERIFIED_HEAD_MAX };
+    for (const key of Object.keys(VERIFIED_HEAD_MAX)) {
+        const value = supplied[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > VERIFIED_HEAD_MAX[key])
+            return null;
+        resolved[key] = value;
+    }
+    return resolved;
+}
+async function lstatHead(file) { return lstat(file, { bigint: true }); }
+function identity(stats) {
+    return { dev: String(stats.dev), ino: String(stats.ino), mode: String(stats.mode), size: String(stats.size), ctimeNs: String(stats.ctimeNs), mtimeNs: String(stats.mtimeNs) };
+}
+function sameIdentity(left, right) { return canonical(left) === canonical(right); }
+function headToken(rootRealpath, sourceId, metadata) {
+    return createHash("sha256").update(canonical({ kind: "lookout.proposal-head-witness/v1", version: 1, rootRealpath, sourceId, metadata })).digest("hex");
+}
+function errno(cause) { return cause?.code; }
+function boundedSourceId(sourceId) {
+    return typeof sourceId === "string" && sourceId.length > 0 && sourceId.length <= 256 && Buffer.byteLength(sourceId) <= 512;
+}
+async function boundedText(file, maximum) {
+    let handle;
+    try {
+        const before = await lstatHead(file);
+        if (before.isSymbolicLink() || !before.isFile())
+            return { kind: "corrupt" };
+        if (before.size > BigInt(maximum))
+            return { kind: "unavailable" };
+        handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() || !sameIdentity(identity(before), identity(opened)) || opened.size > BigInt(maximum))
+            return { kind: "unavailable" };
+        const buffer = Buffer.alloc(Number(opened.size) + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const after = await handle.stat({ bigint: true });
+        if (!sameIdentity(identity(opened), identity(after)) || bytesRead !== Number(opened.size) || bytesRead > maximum)
+            return { kind: "unavailable" };
+        return { kind: "ok", text: buffer.subarray(0, bytesRead).toString("utf8"), identity: identity(after) };
+    }
+    catch (cause) {
+        return errno(cause) === "ENOENT" ? { kind: "unavailable" } : { kind: "unavailable" };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function inspectHead(root, sourceId, limits) {
+    if (!boundedSourceId(sourceId))
+        return { kind: "unsupported" };
+    let key;
+    try {
+        key = sourceKey(sourceId);
+    }
+    catch {
+        return { kind: "unsupported" };
+    }
+    let rootStats;
+    try {
+        rootStats = await lstatHead(root);
+    }
+    catch (cause) {
+        return errno(cause) === "ENOENT" ? { kind: "missing" } : { kind: "unavailable" };
+    }
+    if (rootStats.isSymbolicLink() || !rootStats.isDirectory())
+        return { kind: "corrupt" };
+    let rootRealpath;
+    try {
+        rootRealpath = await realpath(root);
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+    const dir = path.join(root, key);
+    let sourceStats;
+    try {
+        sourceStats = await lstatHead(dir);
+    }
+    catch (cause) {
+        return errno(cause) === "ENOENT" ? { kind: "missing" } : { kind: "unavailable" };
+    }
+    if (sourceStats.isSymbolicLink() || !sourceStats.isDirectory())
+        return { kind: "corrupt" };
+    const names = [];
+    let indexBytes = 0;
+    try {
+        const directory = await opendir(dir, { bufferSize: 1 });
+        try {
+            for await (const entry of directory) {
+                if (names.length >= limits.maxEntries)
+                    return { kind: "unavailable" };
+                indexBytes += Buffer.byteLength(entry.name);
+                if (indexBytes > limits.maxIndexBytes)
+                    return { kind: "unavailable" };
+                if (entry.name === ".lock" || entry.name.includes(".tmp-"))
+                    return { kind: "unavailable" };
+                if (entry.name !== "latest.json" && !/^[a-f0-9]{64}\.json$/.test(entry.name))
+                    return { kind: "corrupt" };
+                const entryStats = await lstatHead(path.join(dir, entry.name));
+                if (entryStats.isSymbolicLink() || !entryStats.isFile())
+                    return { kind: "corrupt" };
+                names.push(entry.name);
+            }
+        }
+        finally {
+            await directory.close().catch(() => undefined);
+        }
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+    names.sort();
+    if (!names.includes("latest.json"))
+        return names.length === 0 ? { kind: "missing" } : { kind: "corrupt" };
+    const pointerRead = await boundedText(path.join(dir, "latest.json"), limits.maxPointerBytes);
+    if (pointerRead.kind !== "ok")
+        return pointerRead;
+    let pointer;
+    try {
+        pointer = JSON.parse(pointerRead.text);
+    }
+    catch {
+        return { kind: "corrupt" };
+    }
+    if (!pointer || typeof pointer !== "object" || Array.isArray(pointer) || pointer.version !== 1 || pointer.sourceId !== sourceId || typeof pointer.observationId !== "string" || !/^[a-f0-9]{64}$/.test(pointer.observationId))
+        return { kind: "corrupt" };
+    const recordName = `${pointer.observationId}.json`;
+    if (!names.includes(recordName))
+        return { kind: "corrupt" };
+    let recordStats;
+    try {
+        recordStats = await lstatHead(path.join(dir, recordName));
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+    if (recordStats.isSymbolicLink() || !recordStats.isFile())
+        return { kind: "corrupt" };
+    if (recordStats.size > BigInt(limits.maxRecordBytes))
+        return { kind: "unavailable" };
+    let finalRoot;
+    let finalSource;
+    try {
+        finalRoot = await lstatHead(root);
+        finalSource = await lstatHead(dir);
+    }
+    catch {
+        return { kind: "unavailable" };
+    }
+    if (!sameIdentity(identity(rootStats), identity(finalRoot)) || !sameIdentity(identity(sourceStats), identity(finalSource)))
+        return { kind: "unavailable" };
+    return { kind: "ready", metadata: { root: identity(rootStats), rootRealpath, source: identity(sourceStats), names, pointer: pointerRead.text, pointerIdentity: pointerRead.identity, observationId: pointer.observationId, record: identity(recordStats) } };
+}
+function snapshotWitness(value) {
+    try {
+        if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value))
+            return { kind: "corrupt" };
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const keys = ["kind", "version", "sourceId", "observationId", "token"];
+        if (Object.keys(descriptors).length !== keys.length || keys.some((key) => !Object.hasOwn(descriptors, key) || descriptors[key]?.get || descriptors[key]?.set))
+            return { kind: "corrupt" };
+        const witness = Object.fromEntries(keys.map((key) => [key, descriptors[key].value]));
+        if (witness.kind !== "lookout.proposal-head-witness/v1" || typeof witness.version !== "number")
+            return { kind: "unsupported" };
+        if (witness.version !== 1)
+            return { kind: "unsupported" };
+        if (!boundedSourceId(witness.sourceId) || typeof witness.observationId !== "string" || !/^[a-f0-9]{64}$/.test(witness.observationId) || typeof witness.token !== "string" || !/^[a-f0-9]{64}$/.test(witness.token))
+            return { kind: "corrupt" };
+        return { kind: "ok", witness: { kind: witness.kind, version: witness.version, sourceId: witness.sourceId, observationId: witness.observationId, token: witness.token } };
+    }
+    catch {
+        return { kind: "corrupt" };
+    }
+}
 function buildRecord(input) {
     try {
         const { observation, check } = input;
@@ -109,7 +306,7 @@ async function atomicWrite(file, bytes, kind, faults) {
     }
 }
 export function createObservationStore(options = {}) {
-    const root = options.root ?? path.join(process.cwd(), ".kontourai", "lookout", "observations");
+    const root = path.resolve(options.root ?? path.join(process.cwd(), ".kontourai", "lookout", "observations"));
     async function loadLatest(sourceId) {
         try {
             const dir = path.join(root, sourceKey(sourceId));
@@ -237,5 +434,53 @@ export function createObservationStore(options = {}) {
             await rm(lockPath, { force: true }).catch(() => undefined);
         }
     }
-    return { loadLatest, commit };
+    async function readVerifiedHead(sourceId, suppliedLimits) {
+        const limits = resolveHeadLimits(suppliedLimits);
+        if (limits === null)
+            return { kind: "unsupported" };
+        const before = await inspectHead(root, sourceId, limits);
+        if (before.kind !== "ready")
+            return before;
+        // This is the only body read in the witness API. It reuses the concrete store's
+        // authenticated record validator and is bracketed by metadata fences below.
+        options.faults?.beforeHeadStrongLoad?.();
+        options.faults?.beforeHeadRecordRead?.();
+        const record = await boundedText(path.join(root, sourceKey(sourceId), `${before.metadata.observationId}.json`), limits.maxRecordBytes);
+        if (record.kind !== "ok")
+            return record;
+        let loaded;
+        try {
+            loaded = validate(JSON.parse(record.text), sourceId);
+        }
+        catch {
+            return { kind: "corrupt" };
+        }
+        if (!loaded.ok || loaded.value.observationId !== before.metadata.observationId)
+            return { kind: "corrupt" };
+        options.faults?.beforeHeadAfterFence?.();
+        const after = await inspectHead(root, sourceId, limits);
+        if (after.kind !== "ready")
+            return after;
+        if (canonical(before.metadata) !== canonical(after.metadata))
+            return { kind: "unavailable" };
+        const token = headToken(before.metadata.rootRealpath, sourceId, before.metadata);
+        return { kind: "verified", sourceId, observationId: loaded.value.observationId, snapshotRef: loaded.value.snapshotRef, witness: { kind: "lookout.proposal-head-witness/v1", version: 1, sourceId, observationId: loaded.value.observationId, token } };
+    }
+    async function compareHeadWitness(witness, suppliedLimits) {
+        const captured = snapshotWitness(witness);
+        if (captured.kind !== "ok")
+            return captured;
+        const limits = resolveHeadLimits(suppliedLimits);
+        if (limits === null)
+            return { kind: "unsupported" };
+        const inspected = await inspectHead(root, captured.witness.sourceId, limits);
+        if (inspected.kind !== "ready")
+            return inspected;
+        if (inspected.metadata.observationId !== captured.witness.observationId)
+            return { kind: "changed" };
+        return headToken(inspected.metadata.rootRealpath, captured.witness.sourceId, inspected.metadata) === captured.witness.token
+            ? { kind: "matches", sourceId: captured.witness.sourceId, observationId: captured.witness.observationId }
+            : { kind: "changed" };
+    }
+    return { loadLatest, commit, readVerifiedHead, compareHeadWitness };
 }

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.5.0",
+  "version": "0.5.2",
   "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": {