@sema-agent/core 5.65.0 → 7.0.0

package/dist/core/file-snapshot-store.d.ts

@@ -1,165 +0,0 @@
-/** rel path of `child` under `root` in "/" form (win root) / verbatim form (posix root); null when not under.
- *  fold "\" only under a WIN-family root ({@link isWinFormPath}); a POSIX tree may legally
- *  contain literal backslashes in FILE NAMES, and folding them corrupted both the manifest key and the
- *  restore target. */
-declare function relUnder(root: string, child: string): string | null;
-/** Join root + a "/"-form relPath using the ROOT's native separator (keys stay family-consistent). */
-declare function joinUnder(root: string, rel: string): string;
-import type { ExecutionEnv } from "../internal/harness-types.js";
-export interface FileSnapshotError {
-    /** `too_large` = the tree exceeded a bound (fail-CLOSED, NOT a silent partial snapshot); `not_found` = no
-     *  snapshot for that key; `aborted` = the signal fired; the rest = an underlying fs op failed. */
-    code: "too_large" | "enumerate_failed" | "read_failed" | "restore_failed" | "not_found" | "aborted";
-    message: string;
-}
-export type FileSnapshotResult = {
-    ok: true;
-} | {
-    ok: false;
-    error: FileSnapshotError;
-};
-/**
- * Capture/restore a working-tree file set keyed by `(scope, key)` — `scope` = sessionId, `key` =
- * `SessionTreeEntry.id` (same anchor as E18 resume-at). All methods are best-effort and NEVER throw — failures
- * are encoded in the returned {@link FileSnapshotResult} (mirrors the ExecutionEnv FileSystem contract).
- *
- * **v1 fidelity bounds (design/101 §defer):** files only — symlinks are NOT captured and are REMOVED by
- * `restore` (they are a path-escape vector); empty directories are not tracked; `restore` re-enumerates under
- * the SAME bounds, so a tree that grew past a bound since the snapshot cannot be rewound (fail-closed).
- */
-export interface FileSnapshotStore {
-    /** Capture the tree under `root` for `(scope, key)`. CREATE-ONCE: a second call for an existing key is a
-     *  no-op `{ok:true}` (a session entry id is immutable, so its tree state is too). */
-    snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    /** Converge the tree under `root` back to the snapshot for `(scope, key)`: remove obstructions/strays
-     *  (symlinks + files created since), then write every captured file — so the tree MATCHES the snapshot. */
-    restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    /** Whether a snapshot exists for `(scope, key)`. */
-    has(scope: string, key: string): Promise<boolean>;
-    /** GC: drop every snapshot in `scope` whose key is NOT in `keepKeys` (e.g. unreachable branches). Returns the
-     *  number of snapshots removed. */
-    reap(scope: string, keepKeys: string[]): Promise<number>;
-    /** Every snapshot key in `scope` (order unspecified). The enumeration counterpart of {@link reap} (which
-     *  already iterates the same set internally) — exposed for a cross-backend session EXPORT (service 2c
-     *  session-sync): list a session's snapshot keys to move its {entries + file snapshots} to another
-     *  backend. A durable backend implements it as a `SELECT key WHERE scope = ?`. */
-    listKeys(scope: string): Promise<string[]>;
-    /**
-     * 2c session-sync: the manifest (`relPath → blobHash`) for `(scope, key)`, or `null` if absent — to
-     * EXPORT a snapshot's content to another backend. Pairs with {@link getBlob} for CONTENT-ADDRESSED (deduped)
-     * blob transfer: the caller fetches each distinct hash ONCE across all of a session's snapshots. Optional — a
-     * backend that supports cross-backend snapshot export implements it.
-     */
-    exportManifest?(scope: string, key: string): Promise<Map<string, string> | null>;
-    /** 2c session-sync: the content-addressed bytes for `hash` (undefined if absent). */
-    getBlob?(hash: string): Promise<Uint8Array | undefined>;
-    /**
-     * 2c session-sync: STORE a snapshot INTO this store from another store's {@link exportManifest} +
-     * {@link getBlob} output — the import-side mirror that closes the cross-backend transfer loop. For each DISTINCT
-     * blob hash in `manifest`, fetch its bytes via `srcGetBlob`, VERIFY content-address integrity
-     * (`sha256(bytes) === hash`), and store it (content-addressed dedup); THEN record `(scope, key) → manifest`.
-     *
-     * - CREATE-ONCE: a second import for an existing key is a no-op `{ok:true}` (an entry id is immutable).
-     * - FAIL-CLOSED: a missing OR hash-mismatched source blob → `read_failed` and NO manifest is committed (never a
-     *   partial snapshot that a later {@link restore} would silently truncate). The manifest's relPaths are NOT
-     *   re-validated here — `restore` remains the path-escape gate (it already neutralizes unsafe relPaths).
-     * - Pure store→store: does NOT touch an `ExecutionEnv` (unlike `applyManifest`, which converges ONE snapshot to a
-     *   working tree; import preserves ALL historical snapshots in the dst store so a later rewind-to-past finds them).
-     *
-     * Optional — a backend that supports cross-backend snapshot import implements it.
-     */
-    importManifest?(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
-    /**
-     * 2c session-sync: STORE a single content-addressed blob — the symmetric WRITE side of {@link getBlob},
-     * for a two-phase PUSH (upload blobs, THEN import the manifest that references them). VERIFIES content-address
-     * integrity (`sha256(bytes) === hash`) so a corrupt/mismatched upload can never contaminate the store (a later
-     * getBlob/restore would otherwise return wrong content); a mismatch → `read_failed`, nothing stored. IMMUTABLE +
-     * content-addressed: a repeat putBlob for the same hash is a no-op (the bytes are identical by definition).
-     * Returns a {@link FileSnapshotResult} (NOT void) so the integrity failure is encodable under the never-throw
-     * contract. Optional — a backend that supports a two-phase push implements it.
-     *
-     * ⚠️ ORCHESTRATION CAVEAT: a pushed blob is NOT yet referenced by any manifest (the matching
-     * {@link importManifest} runs LATER), so — unlike `snapshot`/`importManifest`, which hold their blobs in an
-     * `inFlight` live-set across the whole store-then-commit — a `putBlob`'d blob is reap-ELIGIBLE in the window
-     * before its manifest is imported. The two-phase pusher MUST NOT `reap` the scope between PUT and import (a
-     * grace-window). This is fail-closed, not corrupting: blobs are content-addressed (re-push is always safe) and
-     * `importManifest` re-verifies+stores every blob before committing, so a reaped blob → `read_failed` with NO
-     * dangling-reference manifest, never wrong content.
-     */
-    putBlob?(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
-}
-/** Bounds for the reference enumerator — a deliberate, fail-CLOSED cost policy (NOT the grep walk's silent caps). */
-export interface FileSnapshotBounds {
-    /** Hard cap on file count; exceeding it REFUSES the snapshot (`too_large`) rather than silently truncating. */
-    maxFiles: number;
-    /** Hard cap on total bytes; exceeding it REFUSES the snapshot. */
-    maxBytes: number;
-    /** Directory BASENAMES skipped anywhere in the tree (cost bound). Default `.git` + `node_modules`. */
-    ignoreDirs: Set<string>;
-}
-export declare const DEFAULT_SNAPSHOT_BOUNDS: FileSnapshotBounds;
-/**
- * Capture the working tree under `root` into a manifest `relPath → sha256`, handing each file's bytes to
- * `putBlob` (the backend stores them content-addressed). **The env-operating + security-critical half a durable
- * backend MUST reuse** (not re-implement — duplication risks re-introducing the symlink-escape / fail-closed
- * bugs the dual-review fixed). Fail-CLOSED: an enumerate/read/bound failure returns an error and the caller must
- * NOT persist a partial manifest. Never throws.
- *
- * vanished-file tolerance: a file that DISAPPEARED between enumerate and read (`not_found`) is OMITTED
- * from the manifest instead of failing the whole capture. This is semantically SAFE — the E19 snapshot runs
- * concurrently with a live tree (the `done` frame is emitted BEFORE the snapshot, so shell-side per-turn
- * markers, `.git/index.lock`, editor swap files etc. legitimately vanish mid-walk), and omitting a
- * just-deleted file yields the CONSISTENT tree state of one instant later — NOT a partial snapshot (which
- * would mean "captured bytes are missing for a file that exists"). No re-stat second check is needed:
- * `not_found` is a stable backend-independent FileErrorCode (locally the SOLE mapping of ENOENT,
- * node-execution-env.ts toFileError) — the read itself IS the authoritative existence probe at capture time,
- * and a re-stat would only re-open the same race one window later. Every OTHER read error (permission_denied/
- * EIO/unknown…) and any enumerate failure keeps the fail-closed whole-capture rejection: those mean "the file
- * is still there but we could not capture it" — omitting it WOULD be a data-lossy partial snapshot.
- * `skippedVanished` reports the count for observability/tests.
- */
-export declare function captureManifest(env: ExecutionEnv, root: string, bounds: FileSnapshotBounds, signal: AbortSignal | undefined, putBlob: (hash: string, bytes: Uint8Array) => void | Promise<void>): Promise<{
-    ok: true;
-    value: Map<string, string>;
-    skippedVanished: number;
-} | {
-    ok: false;
-    error: FileSnapshotError;
-}>;
-/**
- * CONVERGE the tree under `root` to `manifest`, loading each captured file's bytes via `getBlob`. **The
- * env-operating + security-critical half a durable backend MUST reuse.** Order is load-bearing (+
- * Opus M1): PHASE 1 removes every current symlink (neutralizes a `dir -> /outside` ancestor that writeFile would
- * otherwise follow OUT of root) + every file created since; PHASE 2 writes each captured file, clearing a
- * directory that now occupies a file's path first. Never throws.
- */
-export declare function applyManifest(env: ExecutionEnv, root: string, bounds: FileSnapshotBounds, signal: AbortSignal | undefined, manifest: Map<string, string>, getBlob: (hash: string) => Uint8Array | undefined | Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
-/**
- * In-memory, content-addressed reference {@link FileSnapshotStore}. Blobs are deduplicated by sha256 ACROSS all
- * snapshots (a file unchanged between turns is stored once); each snapshot keeps a manifest `relPath → hash`.
- * Single-process (the default-deps reference; a durable/file-backed impl mirrors `src/stores/file/`).
- */
-export declare class InMemoryFileSnapshotStore implements FileSnapshotStore {
-    private readonly blobs;
-    private readonly manifests;
-    private readonly inFlight;
-    private readonly bounds;
-    constructor(bounds?: Partial<FileSnapshotBounds>);
-    snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    has(scope: string, key: string): Promise<boolean>;
-    listKeys(scope: string): Promise<string[]>;
-    exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    putBlob(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
-    importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
-    reap(scope: string, keepKeys: string[]): Promise<number>;
-}
-/** Test-only window (REF-C2 class pins): pure path helpers whose family-awareness carries a fence/
- *  restore invariant. Not re-exported from src/index.ts. */
-export declare const __testables: {
-    joinUnder: typeof joinUnder;
-    relUnder: typeof relUnder;
-    stripTrailSep: (p: string) => string;
-};
-export {};

package/dist/core/file-snapshot-store.js

@@ -1,259 +0,0 @@
-import { createHash } from "node:crypto";
-import { isAbsolutePathForm, isWinFormPath } from "../tools/fs/safety.js";
-const normSlash = (p) => p.replace(/\\/g, "/");
-const stripTrailSep = (p) => (isWinFormPath(p) ? p.replace(/[\\/]+$/, "") : p.replace(/\/+$/, ""));
-const foldDrive = (p) => (/^[A-Za-z]:(\/|$)/.test(p) ? p[0].toLowerCase() + p.slice(1) : p);
-function relUnder(root, child) {
-    const fold = isWinFormPath(root) ? normSlash : (p) => p;
-    const r = foldDrive(fold(stripTrailSep(root)));
-    const c = foldDrive(fold(child));
-    if (c === r)
-        return "";
-    if (!c.startsWith(r + "/"))
-        return null;
-    return fold(child).slice(fold(stripTrailSep(root)).length + 1);
-}
-function joinUnder(root, rel) {
-    const win = isWinFormPath(root);
-    return stripTrailSep(root) + (win ? "\\" : "/") + (win ? rel.replace(/\//g, "\\") : rel);
-}
-function isUnsafeRelPath(relN) {
-    return isAbsolutePathForm(relN) || /^[A-Za-z]:/.test(relN) || relN.split("/").includes("..");
-}
-export const DEFAULT_SNAPSHOT_BOUNDS = {
-    maxFiles: 10000,
-    maxBytes: 256 * 1024 * 1024,
-    ignoreDirs: new Set([".git", "node_modules"]),
-};
-async function enumerateTree(env, root, bounds, signal) {
-    const files = [];
-    const symlinks = [];
-    let totalBytes = 0;
-    const stack = [root];
-    while (stack.length > 0) {
-        if (signal?.aborted)
-            return { ok: false, error: { code: "aborted", message: "aborted" } };
-        const dir = stack.pop();
-        const ls = await env.listDir(dir, signal);
-        if (!ls.ok) {
-            return { ok: false, error: { code: "enumerate_failed", message: `listDir ${dir}: ${ls.error.code}` } };
-        }
-        for (const info of ls.value) {
-            if (info.kind === "symlink") {
-                symlinks.push(info.path);
-            }
-            else if (info.kind === "directory") {
-                if (!bounds.ignoreDirs.has(info.name))
-                    stack.push(info.path);
-            }
-            else if (info.kind === "file") {
-                const relPath = relUnder(root, info.path);
-                if (relPath === null)
-                    return { ok: false, error: { code: "enumerate_failed", message: `path escapes root form: ${info.path}` } };
-                files.push({ relPath, absPath: info.path, size: info.size });
-                totalBytes += info.size;
-                if (files.length > bounds.maxFiles)
-                    return { ok: false, error: { code: "too_large", message: `> ${bounds.maxFiles} files` } };
-                if (totalBytes > bounds.maxBytes)
-                    return { ok: false, error: { code: "too_large", message: `> ${bounds.maxBytes} bytes` } };
-            }
-        }
-    }
-    return { ok: true, value: { files, symlinks } };
-}
-const SEP = String.fromCharCode(0);
-const skey = (scope, key) => `${scope}${SEP}${key}`;
-export async function captureManifest(env, root, bounds, signal, putBlob) {
-    const enumerated = await enumerateTree(env, root, bounds, signal);
-    if (!enumerated.ok)
-        return enumerated;
-    const manifest = new Map();
-    let skippedVanished = 0;
-    for (const f of enumerated.value.files) {
-        if (signal?.aborted)
-            return { ok: false, error: { code: "aborted", message: "aborted" } };
-        const rb = await env.readBinaryFile(f.absPath, signal);
-        if (!rb.ok) {
-            if (rb.error.code === "not_found") {
-                skippedVanished++;
-                continue;
-            }
-            return { ok: false, error: { code: "read_failed", message: `read ${f.relPath}: ${rb.error.code}` } };
-        }
-        const hash = createHash("sha256").update(rb.value).digest("hex");
-        await putBlob(hash, rb.value);
-        manifest.set(f.relPath, hash);
-    }
-    return { ok: true, value: manifest, skippedVanished };
-}
-export async function applyManifest(env, root, bounds, signal, manifest, getBlob) {
-    const cur = await enumerateTree(env, root, bounds, signal);
-    if (!cur.ok)
-        return cur;
-    for (const link of cur.value.symlinks) {
-        if (signal?.aborted)
-            return { ok: false, error: { code: "aborted", message: "aborted" } };
-        const rm = await env.remove(link, { force: true });
-        if (!rm.ok)
-            return { ok: false, error: { code: "restore_failed", message: `remove symlink ${link}: ${rm.error.code}` } };
-    }
-    for (const f of cur.value.files) {
-        if (signal?.aborted)
-            return { ok: false, error: { code: "aborted", message: "aborted" } };
-        if (!manifest.has(f.relPath)) {
-            const rm = await env.remove(f.absPath, { force: true });
-            if (!rm.ok)
-                return { ok: false, error: { code: "restore_failed", message: `remove ${f.relPath}: ${rm.error.code}` } };
-        }
-    }
-    for (const [relPath, hash] of manifest) {
-        if (signal?.aborted)
-            return { ok: false, error: { code: "aborted", message: "aborted" } };
-        const relN = isWinFormPath(root) ? normSlash(relPath) : relPath;
-        if (isUnsafeRelPath(relN)) {
-            return { ok: false, error: { code: "restore_failed", message: `unsafe relPath escapes root: ${relPath}` } };
-        }
-        const blob = await getBlob(hash);
-        if (!blob)
-            return { ok: false, error: { code: "restore_failed", message: `missing blob for ${relPath}` } };
-        const target = joinUnder(root, relN);
-        const fi = await env.fileInfo(target);
-        if (fi.ok && fi.value.kind === "directory") {
-            const rm = await env.remove(target, { recursive: true, force: true });
-            if (!rm.ok)
-                return { ok: false, error: { code: "restore_failed", message: `clear dir ${relPath}: ${rm.error.code}` } };
-        }
-        const w = await env.writeFile(target, blob);
-        if (!w.ok)
-            return { ok: false, error: { code: "restore_failed", message: `write ${relPath}: ${w.error.code}` } };
-    }
-    return { ok: true };
-}
-export class InMemoryFileSnapshotStore {
-    blobs = new Map();
-    manifests = new Map();
-    inFlight = new Map();
-    bounds;
-    constructor(bounds) {
-        this.bounds = {
-            maxFiles: bounds?.maxFiles ?? DEFAULT_SNAPSHOT_BOUNDS.maxFiles,
-            maxBytes: bounds?.maxBytes ?? DEFAULT_SNAPSHOT_BOUNDS.maxBytes,
-            ignoreDirs: new Set(bounds?.ignoreDirs ?? DEFAULT_SNAPSHOT_BOUNDS.ignoreDirs),
-        };
-    }
-    async snapshot(scope, key, env, root, signal) {
-        const sk = skey(scope, key);
-        if (this.manifests.has(sk) || this.inFlight.has(sk))
-            return { ok: true };
-        const written = new Set();
-        this.inFlight.set(sk, written);
-        try {
-            const captured = await captureManifest(env, root, this.bounds, signal, (hash, bytes) => {
-                written.add(hash);
-                if (!this.blobs.has(hash))
-                    this.blobs.set(hash, bytes);
-            });
-            if (!captured.ok)
-                return captured;
-            this.manifests.set(sk, captured.value);
-            return { ok: true };
-        }
-        finally {
-            this.inFlight.delete(sk);
-        }
-    }
-    async restore(scope, key, env, root, signal) {
-        const manifest = this.manifests.get(skey(scope, key));
-        if (!manifest)
-            return { ok: false, error: { code: "not_found", message: `no snapshot for key ${key}` } };
-        return applyManifest(env, root, this.bounds, signal, manifest, (hash) => this.blobs.get(hash));
-    }
-    async has(scope, key) {
-        return this.manifests.has(skey(scope, key));
-    }
-    async listKeys(scope) {
-        const prefix = `${scope}${SEP}`;
-        const keys = [];
-        for (const sk of this.manifests.keys()) {
-            if (sk.startsWith(prefix))
-                keys.push(sk.slice(prefix.length));
-        }
-        return keys;
-    }
-    async exportManifest(scope, key) {
-        const m = this.manifests.get(skey(scope, key));
-        return m ? new Map(m) : null;
-    }
-    async getBlob(hash) {
-        return this.blobs.get(hash);
-    }
-    async putBlob(hash, bytes) {
-        if (createHash("sha256").update(bytes).digest("hex") !== hash) {
-            return { ok: false, error: { code: "read_failed", message: `blob bytes fail content-address integrity for ${hash}` } };
-        }
-        if (!this.blobs.has(hash))
-            this.blobs.set(hash, bytes);
-        return { ok: true };
-    }
-    async importManifest(scope, key, manifest, srcGetBlob) {
-        const sk = skey(scope, key);
-        if (this.manifests.has(sk) || this.inFlight.has(sk))
-            return { ok: true };
-        const written = new Set();
-        this.inFlight.set(sk, written);
-        try {
-            for (const hash of new Set(manifest.values())) {
-                written.add(hash);
-                if (hash === "" || hash === "." || hash === ".." || !/^[A-Za-z0-9_.-]+$/.test(hash)) {
-                    return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
-                }
-                if (this.blobs.has(hash))
-                    continue;
-                let bytes;
-                try {
-                    bytes = await srcGetBlob(hash);
-                }
-                catch (err) {
-                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
-                }
-                if (!bytes)
-                    return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
-                if (createHash("sha256").update(bytes).digest("hex") !== hash) {
-                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fails content-address integrity` } };
-                }
-                this.blobs.set(hash, bytes);
-            }
-            this.manifests.set(sk, new Map(manifest));
-            return { ok: true };
-        }
-        catch (err) {
-            return { ok: false, error: { code: "read_failed", message: `source blob fetch failed: ${err.message}` } };
-        }
-        finally {
-            this.inFlight.delete(sk);
-        }
-    }
-    async reap(scope, keepKeys) {
-        const keep = new Set(keepKeys);
-        const prefix = `${scope}${SEP}`;
-        let removed = 0;
-        for (const sk of [...this.manifests.keys()]) {
-            if (sk.startsWith(prefix) && !keep.has(sk.slice(prefix.length))) {
-                this.manifests.delete(sk);
-                removed++;
-            }
-        }
-        const live = new Set();
-        for (const hs of this.inFlight.values())
-            for (const h of hs)
-                live.add(h);
-        for (const m of this.manifests.values())
-            for (const h of m.values())
-                live.add(h);
-        for (const h of [...this.blobs.keys()])
-            if (!live.has(h))
-                this.blobs.delete(h);
-        return removed;
-    }
-}
-export const __testables = { joinUnder, relUnder, stripTrailSep };

package/dist/core/store-contracts/file-snapshot-store-contract.d.ts

@@ -1,13 +0,0 @@
-import type { FileSnapshotStore } from "../file-snapshot-store.js";
-import { type ContractAssertionRunner } from "./contract-harness.js";
-export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner, options?: {
-    /**
-     * How quickly unreferenced BLOB BYTES become unreadable after a reap. The MANIFEST key is a hard
-     * contract either way (invisible immediately). `"immediate"` (default — the in-memory and file
-     * reference backends): `getBlob` of a just-unreferenced hash is `undefined` right after `reap`
-     * returns. `"eventual"`: a durable/object-storage backend that hands byte GC to an asynchronous
-     * sweeper (so a reap on the request path is never held hostage by external-storage latency) —
-     * the immediate-unreadability assertion is skipped; the backend owns proving its sweeper.
-     */
-    blobGc?: "immediate" | "eventual";
-}): Promise<void>;

package/dist/core/store-contracts/file-snapshot-store-contract.js

@@ -1,134 +0,0 @@
-import { strict as assert } from "node:assert";
-import { createHash } from "node:crypto";
-import { beginContract } from "./contract-harness.js";
-const bytes = (s) => new TextEncoder().encode(s);
-const sha256 = (s) => createHash("sha256").update(bytes(s)).digest("hex");
-const srcBlob = async (hash) => hash === sha256("alpha") ? bytes("alpha") : hash === sha256("beta") ? bytes("beta") : undefined;
-export async function fileSnapshotStoreContract(make, runAssertion, options) {
-    const { run, settle } = beginContract(runAssertion);
-    const blobGc = options?.blobGc ?? "immediate";
-    run("kit prerequisites: exportManifest/getBlob/putBlob/importManifest are implemented (REQUIRED by this kit)", async () => {
-        const probe = make();
-        const missing = ["exportManifest", "getBlob", "putBlob", "importManifest"].filter((m) => typeof probe[m] !== "function");
-        assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the FileSnapshotStore contract kit`);
-    });
-    run("absent everything: has=false, listKeys=[], exportManifest=null, getBlob=undefined", async () => {
-        const store = make();
-        assert.equal(await store.has("sc", "k1"), false);
-        assert.deepEqual(await store.listKeys("sc"), []);
-        assert.equal(await store.exportManifest("sc", "k1"), null);
-        assert.equal(await store.getBlob(sha256("alpha")), undefined);
-    });
-    run("putBlob verifies content-address integrity: mismatched bytes → read_failed, nothing stored", async () => {
-        const store = make();
-        const r = await store.putBlob(sha256("beta"), bytes("alpha"));
-        assert.equal(r.ok, false);
-        if (!r.ok)
-            assert.equal(r.error.code, "read_failed");
-        assert.equal(await store.getBlob(sha256("beta")), undefined);
-    });
-    run("putBlob ok; a repeat putBlob for the same hash is an idempotent no-op; getBlob round-trips the bytes", async () => {
-        const store = make();
-        assert.deepEqual(await store.putBlob(sha256("alpha"), bytes("alpha")), { ok: true });
-        assert.deepEqual(await store.putBlob(sha256("alpha"), bytes("alpha")), { ok: true });
-        assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
-    });
-    run("importManifest commits only after every blob verifies: has=true, exportManifest round-trips", async () => {
-        const store = make();
-        const manifest = new Map([["a.txt", sha256("alpha")], ["b.txt", sha256("beta")]]);
-        assert.deepEqual(await store.importManifest("sc", "k1", manifest, srcBlob), { ok: true });
-        assert.equal(await store.has("sc", "k1"), true);
-        const exported = await store.exportManifest("sc", "k1");
-        assert.deepEqual([...exported.entries()].sort(), [...manifest.entries()].sort());
-    });
-    run("importManifest is create-once: a second import for an existing key is a no-op (ok, zero fetches, manifest unchanged)", async () => {
-        const store = make();
-        const manifest = new Map([["a.txt", sha256("alpha")]]);
-        assert.deepEqual(await store.importManifest("sc", "k1", manifest, srcBlob), { ok: true });
-        const refetched = [];
-        const second = await store.importManifest("sc", "k1", new Map([["z.txt", sha256("beta")]]), async (h) => {
-            refetched.push(h);
-            return srcBlob(h);
-        });
-        assert.deepEqual(second, { ok: true });
-        assert.deepEqual(refetched, []);
-        assert.deepEqual([...(await store.exportManifest("sc", "k1")).entries()], [...manifest.entries()]);
-    });
-    run("importManifest is FAIL-CLOSED: a missing or hash-mismatched source blob → read_failed, no manifest committed", async () => {
-        const store = make();
-        const manifest = new Map([["c.txt", "0".repeat(64)]]);
-        const miss = await store.importManifest("sc", "k2", manifest, async () => undefined);
-        assert.equal(miss.ok, false);
-        if (!miss.ok)
-            assert.equal(miss.error.code, "read_failed");
-        assert.equal(await store.has("sc", "k2"), false);
-        const mism = await store.importManifest("sc", "k2", manifest, async () => bytes("wrong-bytes"));
-        assert.equal(mism.ok, false);
-        if (!mism.ok)
-            assert.equal(mism.error.code, "read_failed");
-        assert.equal(await store.has("sc", "k2"), false);
-    });
-    run("RB-361 a throwing source fetch → read_failed NAMING the blob hash, byte-identical wording (since 2.2.0)", async () => {
-        const store = make();
-        const hash = sha256("x");
-        const r = await store.importManifest("sc", "k3", new Map([["d.txt", hash]]), () => Promise.reject(new Error("transport down")));
-        assert.equal(r.ok, false);
-        if (!r.ok) {
-            assert.equal(r.error.code, "read_failed");
-            assert.equal(r.error.message, `source blob ${hash} fetch failed: transport down`);
-        }
-        assert.equal(await store.has("sc", "k3"), false);
-    });
-    run("RB-361 a path-escaping hash is refused as UNSAFE before any fetch, byte-identical wording (since 2.2.0)", async () => {
-        const store = make();
-        const fetched = [];
-        const r = await store.importManifest("sc", "k4", new Map([["e.txt", "../../escape"]]), async (h) => {
-            fetched.push(h);
-            return undefined;
-        });
-        assert.equal(r.ok, false);
-        if (!r.ok) {
-            assert.equal(r.error.code, "read_failed");
-            assert.equal(r.error.message, `unsafe blob hash "../../escape"`);
-        }
-        assert.deepEqual(fetched, []);
-        assert.equal(await store.has("sc", "k4"), false);
-    });
-    run("restore of a missing key → not_found (never a throw out of the seam)", async () => {
-        const store = make();
-        const stubEnv = {};
-        const r = await store.restore("sc", "nope", stubEnv, "/nonexistent-root");
-        assert.equal(r.ok, false);
-        if (!r.ok)
-            assert.equal(r.error.code, "not_found");
-    });
-    run("listKeys reflects only committed keys and is scope-isolated", async () => {
-        const store = make();
-        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
-        await store.importManifest("sc", "k2", new Map([["c.txt", "0".repeat(64)]]), async () => undefined);
-        assert.deepEqual(((await store.listKeys("sc")) ?? []).slice().sort(), ["k1"]);
-        assert.deepEqual(await store.listKeys("other"), []);
-    });
-    run("reap keeps listed keys and their blobs", async () => {
-        const store = make();
-        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
-        assert.equal(await store.reap("sc", ["k1"]), 0);
-        assert.deepEqual(await store.listKeys("sc"), ["k1"]);
-        assert.deepEqual([...(await store.getBlob(sha256("alpha")))], [...bytes("alpha")]);
-    });
-    run("reap keep-nothing drops the key IMMEDIATELY (every backend)", async () => {
-        const store = make();
-        await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
-        assert.equal(await store.reap("sc", []), 1);
-        assert.equal(await store.has("sc", "k1"), false);
-    });
-    if (blobGc === "immediate") {
-        run("reap keep-nothing GCs the now-unreferenced blob bytes immediately (blobGc: immediate)", async () => {
-            const store = make();
-            await store.importManifest("sc", "k1", new Map([["a.txt", sha256("alpha")]]), srcBlob);
-            assert.equal(await store.reap("sc", []), 1);
-            assert.equal(await store.getBlob(sha256("alpha")), undefined);
-        });
-    }
-    await settle();
-}

package/dist/stores/file/file-snapshot-store.d.ts

@@ -1,58 +0,0 @@
-import type { ExecutionEnv } from "../../internal/harness-types.js";
-import { type FileSnapshotBounds, type FileSnapshotResult, type FileSnapshotStore } from "../../core/file-snapshot-store.js";
-export interface FileFileSnapshotStoreOptions {
-    /**
-     * Disclosure sink for a durable read this store treats as ABSENT (ruled 2026-08-03). Same name and
-     * same `{path, reason}` shape as the sibling file stores' seat — "unreadable read as missing" and
-     * "corrupt read as missing" are one failure grammar, so they get one seat name.
-     *
-     * Fires for: a corrupt/unreadable MANIFEST collapsed to "no snapshot" (the never-throw seam's
-     * documented fail-open — `has`/`restore`/`exportManifest`/`listKeys` all report absence), an
-     * unreadable manifest DIRECTORY that degrades an enumeration to "no keys", and a blob-GC pass that
-     * aborted because its live set could not be completed (blobs are kept — leaked, not lost).
-     *
-     * Never fires on plain ENOENT: a scope with no snapshots yet really is empty. Swallow-guarded.
-     */
-    onCorruptRead?: (info: {
-        path: string;
-        reason: string;
-    }) => void;
-}
-export declare class FileFileSnapshotStore implements FileSnapshotStore {
-    private readonly base;
-    private readonly blobsDir;
-    private readonly manifestsDir;
-    /**
-     * RB-163 (2026-07-26): the in-flight blob set is authority over a DIRECTORY, so it lives with the
-     * directory. On the instance, a second store on the same base ran `reap()` while the first was midway
-     * through `importManifest` — its live set did not include the peer's in-flight blobs, so it collected
-     * blobs the peer had already published, and the import still reported `ok` with a manifest referencing
-     * files that no longer exist. Keyed by {@link canonicalStoreKey} so two spellings of one directory
-     * cannot each keep their own idea of what is in flight.
-     */
-    private get inFlight();
-    private readonly inFlightKey;
-    private readonly bounds;
-    private readonly onCorruptRead;
-    constructor(root: string, bounds?: Partial<FileSnapshotBounds>, opts?: FileFileSnapshotStoreOptions);
-    /** The one delivery point for {@link FileFileSnapshotStoreOptions.onCorruptRead}; swallow-guarded
-     *  here so no call site has to remember (and so the never-throw seam contract cannot be broken by a
-     *  host's sink). */
-    private disclose;
-    private scopeDir;
-    private manifestPath;
-    /** manifestPath, but a key that fails the strict path-component guard → null (so the seam's NEVER-throw
-     *  contract holds for a direct SDK caller; engine keys are uuidv7 so this never fires in practice). */
-    private tryManifestPath;
-    private blobPath;
-    private readManifest;
-    snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
-    listKeys(scope: string): Promise<string[]>;
-    has(scope: string, key: string): Promise<boolean>;
-    exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    putBlob(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
-    importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
-    reap(scope: string, keepKeys: string[]): Promise<number>;
-}