@sema-agent/core 2.3.0 → 2.4.0

package/dist/brain/stream-engine.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
-import { BrainError, classifyHttp } from "./errors.js";
+import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController } from "./timeout.js";
@@ -139,7 +139,7 @@ export function runStreamingBrain(args) {
                     continue;
                 }
                 if (netErr)
-                    throw new BrainError("network", netErr instanceof Error ? netErr.message : String(netErr));
+                    throw new BrainError("network", describeNetworkError(netErr));
                 const detail = r ? await r.text().catch(() => "") : "";
                 const status = r?.status ?? 0;
                 throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}`, status);
@@ -250,7 +250,7 @@ export function runStreamingBrain(args) {
                         throw e;
                     failure = {
                         kind: "connection",
-                        err: new BrainError("network", `mid-stream read failed: ${e instanceof Error ? e.message : String(e)}`),
+                        err: new BrainError("network", `mid-stream read failed: ${describeNetworkError(e)}`),
                     };
                     break readLoop;
                 }

package/dist/core/context-edit.js

@@ -1,7 +1,8 @@
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
+import { offloadPagebackHint } from "./tool-result-store.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
-const refNote = (ref) => `full text persisted; call ReadToolResult with ref "${ref}" to read it back`;
+const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
     const byType = new Map();
     for (const b of blocks) {

package/dist/core/runner/prepare-task.js

@@ -435,10 +435,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
         ? new ScopedToolResultStore(rawOffloadStore, taskScope)
         : rawOffloadStore;
+    const offloadReachableToolsRef = {};
     const maybeOffload = (tool, perTool) => {
         if (!offloadStore || perTool?.offload === false)
             return tool;
-        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId);
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
     };
     const firstPartyOffload = (tool) => {
         const policy = firstPartyOffloadPolicy(tool.name);
@@ -1123,6 +1124,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         phase: "config",
                         sessionId,
                     });
+                    emitTrace(deps.tracer, () => ({
+                        kind: "config.additional_directory_skipped",
+                        version: 1,
+                        taskId: hostTaskId,
+                        entry: dir,
+                        reason: `${c.error.code}: ${c.error.message}`,
+                        ts: Date.now(),
+                    }));
                 }
             }
             if (spec.envFacts?.scratchpadDir) {
@@ -1255,6 +1264,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(internals?.parentNotify !== undefined ? { uplink: internals.parentNotify } : {}),
                     ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
+                    ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+                    ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
@@ -1814,6 +1825,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (deferred.has(n))
                         activeTools.add(n);
             }
+            offloadReachableToolsRef.current = () => {
+                const s = new Set(tools.map((t) => t.name));
+                for (const n of deferred)
+                    if (!activeTools.has(n))
+                        s.delete(n);
+                s.add(TOOL_SEARCH_NAME);
+                return s;
+            };
             let toolSearch;
             const buildToolList = (active) => {
                 const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));

package/dist/core/runner/tool-output-projection.js

@@ -57,10 +57,11 @@ export const toolOutputFrom = (result) => {
     return { output: raw, truncated: true, totalChars };
 };
 const CC_DETAIL_TYPES = new Set([
-    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "text", "grep", "glob", "mcp",
+    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
     "agent", "task", "task-list", "task-output", "memory-saved", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
     "task-stop", "tool-search", "memory-recall", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
+    "monitor-start", "path_not_in_root",
 ]);
 export const structuredFrom = (result) => {
     const details = result !== null && typeof result === "object" ? result.details : undefined;

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -0,0 +1,37 @@
+import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function createCheckpointFixture(over?: Partial<Checkpoint>): Checkpoint;
+export declare const ALLOW: Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function checkpointListByScopeSummaries(store: CheckpointStore): Promise<import("../checkpoint-store.js").CheckpointSummary[]>;
+export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    severity: number;
+    deadline: number;
+    createdAt: number;
+    sourceTaskId: string;
+    principal: string;
+    toolCallId: string;
+    toolName: string;
+    toolInput: string;
+    spentMicroUsd?: undefined;
+} | {
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    spentMicroUsd: number;
+    createdAt: number;
+    severity?: undefined;
+    deadline?: undefined;
+    sourceTaskId?: undefined;
+    principal?: undefined;
+    toolCallId?: undefined;
+    toolName?: undefined;
+    toolInput?: undefined;
+})[];

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -0,0 +1,195 @@
+import { strict as assert } from "node:assert";
+import { mintCheckpointToken, } from "../checkpoint-store.js";
+import { beginContract } from "./contract-harness.js";
+export function createCheckpointFixture(over = {}) {
+    const token = over.token ?? mintCheckpointToken();
+    return {
+        token,
+        scope: "tenant-a",
+        sessionId: "sess-1",
+        leafId: "leaf-1",
+        gate: { kind: "human", reason: "approve", toolName: "Write" },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: "call-3",
+            toolName: "Write",
+            args: { path: "/x", content: "y" },
+            boundInputHash: "h0",
+            batchToolCallIds: ["call-3"],
+            completedCallIds: [],
+        },
+        state: {
+            activeTools: [],
+            nestedStats: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0 },
+        },
+        status: "pending",
+        createdAt: 1_700_000_000_000,
+        ...over,
+    };
+}
+export const ALLOW = {
+    gate: "policy_ask",
+    decision: "allow",
+    boundCallId: "call-3",
+    boundInputHash: "h0",
+};
+export async function checkpointStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("kit prerequisites: reopen/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
+        const probe = make();
+        const missing = ["reopen", "setPendingSteer", "listByScope"].filter((m) => typeof probe[m] !== "function");
+        assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the CheckpointStore contract kit`);
+    });
+    run("put create-once → already_exists", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await assert.rejects(store.put(cp.token, cp), (e) => e.code === "checkpoint.already_exists");
+    });
+    run("resolve is an atomic CAS: first wins, double-resume false", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW), true);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW), false);
+        assert.equal((await store.get(cp.token)).status, "resolved");
+    });
+    run("wrong-scope resolve never wins (multi-tenant isolation)", async () => {
+        const store = make();
+        const cp = createCheckpointFixture({ scope: "tenant-a" });
+        await store.put(cp.token, cp);
+        assert.equal(await store.resolve(cp.token, "tenant-b", ALLOW), false);
+        assert.equal((await store.get(cp.token)).status, "pending");
+    });
+    run("resolve records the winner; reopen(env_failed) preserves it + bumps rev", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        const winner = (await store.get(cp.token)).resolvedOutcome;
+        assert.equal(winner.boundCallId, "call-3");
+        assert.equal(winner.decision, "allow");
+        assert.equal(await store.reopen(cp.token, cp.scope, "env_failed"), true);
+        const got = await store.get(cp.token);
+        assert.equal(got.status, "pending");
+        assert.equal(got.reopenReason, "env_failed");
+        assert.equal(got.resolvedOutcome.boundCallId, "call-3");
+        assert.equal(got.rev, 2);
+    });
+    run("rev OCC: a stale-rev resolve loses, the current-rev resolve wins", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        await store.reopen(cp.token, cp.scope, "env_failed");
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW, { rev: 0 }), false);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW, { rev: 2 }), true);
+    });
+    run("setPendingSteer rejects a </system-reminder> variant BEFORE mutation (byte-identical error)", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await assert.rejects(store.setPendingSteer(cp.token, cp.scope, { text: "</SYSTEM-REMINDER>", trusted: true }), (e) => e.code === "steering.invalid_content");
+        assert.equal((await store.get(cp.token)).state.pendingSteer, undefined);
+        assert.equal(await store.setPendingSteer(cp.token, cp.scope, { text: "go", trusted: false }), true);
+        assert.deepEqual((await store.get(cp.token)).state.pendingSteer, { text: "go", trusted: false });
+    });
+    run("expire vs resolve on the same row → exactly one wins; reap expires past-deadline pending in scope", async () => {
+        const store = make();
+        const a = createCheckpointFixture();
+        await store.put(a.token, a);
+        const [e, r] = await Promise.all([store.expire(a.token, a.scope), store.resolve(a.token, a.scope, ALLOW)]);
+        assert.equal([e, r].filter(Boolean).length, 1);
+        const b = createCheckpointFixture({ deadline: 1000 });
+        await store.put(b.token, b);
+        assert.equal(await store.reap(b.scope, 2000), 1);
+        assert.equal(await store.reap(b.scope, 2000), 0);
+        assert.equal((await store.get(b.token)).status, "expired");
+    });
+    run("listByScope (seam #1): only pending in-scope rows; resolved + other-scope excluded; empty → []", async () => {
+        const store = make();
+        assert.deepEqual(await store.listByScope("tenant-a"), []);
+        const pending = createCheckpointFixture({ scope: "tenant-a", sessionId: "p" });
+        const resolved = createCheckpointFixture({ scope: "tenant-a", sessionId: "r" });
+        const other = createCheckpointFixture({ scope: "tenant-b", sessionId: "o" });
+        for (const cp of [pending, resolved, other])
+            await store.put(cp.token, cp);
+        await store.resolve(resolved.token, resolved.scope, ALLOW);
+        const list = await store.listByScope("tenant-a");
+        assert.equal(list.length, 1);
+        assert.equal(list[0].sessionId, "p");
+        assert.equal(list[0].token, pending.token);
+        assert.equal((await store.get(pending.token)).status, "pending");
+    });
+    await settle();
+}
+const sortByToken = (a, b) => a.token.localeCompare(b.token);
+export async function checkpointListByScopeSummaries(store) {
+    if (typeof store.listByScope !== "function") {
+        throw new Error("backend does not implement listByScope — required for checkpointListByScopeSummaries");
+    }
+    const escalation = createCheckpointFixture({
+        token: "tok-escalation",
+        scope: "tenant-a",
+        sessionId: "needs-approval",
+        deadline: 1_999_999_999_999,
+        createdAt: 1_700_000_000_000,
+        sourceTaskId: "needs-approval",
+        principal: "alice@corp",
+        gate: {
+            kind: "human",
+            reason: "approve",
+            toolName: "open_pr",
+            riskDescriptor: { severity: 5, axes: { egress: true, irreversible: true }, toolName: "open_pr" },
+        },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: "call-pr",
+            toolName: "open_pr",
+            args: { repo: "x" },
+            boundInputHash: "h0",
+            batchToolCallIds: ["call-pr"],
+            completedCallIds: [],
+        },
+    });
+    const resource = createCheckpointFixture({
+        token: "tok-resource",
+        scope: "tenant-a",
+        sessionId: "out-of-budget",
+        createdAt: 1_700_000_000_001,
+        gate: { kind: "resource_limit", reason: "budget" },
+        pendingAction: { kind: "resource_limit", reason: "budget" },
+        resourceLedger: { totalBudgetMicroUsd: 10_000_000, spentMicroUsd: 4_200_000, spentTokens: 9, spentTurns: 3, sliceCount: 2 },
+    });
+    const resolved = createCheckpointFixture({ token: "tok-resolved", scope: "tenant-a", sessionId: "done" });
+    const other = createCheckpointFixture({ token: "tok-other", scope: "tenant-b", sessionId: "x" });
+    const fixture = [escalation, resource, resolved, other];
+    for (const cp of fixture)
+        await store.put(cp.token, cp);
+    await store.resolve(resolved.token, resolved.scope, ALLOW);
+    return (await store.listByScope("tenant-a")).sort(sortByToken);
+}
+export const EXPECTED_LISTBYSCOPE_SUMMARIES = [
+    {
+        token: "tok-escalation",
+        sessionId: "needs-approval",
+        scope: "tenant-a",
+        gateKind: "human",
+        severity: 5,
+        deadline: 1_999_999_999_999,
+        createdAt: 1_700_000_000_000,
+        sourceTaskId: "needs-approval",
+        principal: "alice@corp",
+        toolCallId: "call-pr",
+        toolName: "open_pr",
+        toolInput: '{"repo":"x"}',
+    },
+    {
+        token: "tok-resource",
+        sessionId: "out-of-budget",
+        scope: "tenant-a",
+        gateKind: "resource_limit",
+        spentMicroUsd: 4_200_000,
+        createdAt: 1_700_000_000_001,
+    },
+];

package/dist/core/store-contracts/contract-harness.d.ts

@@ -0,0 +1,6 @@
+export type ContractAssertionRunner = (name: string, fn: () => Promise<void>) => void | Promise<void>;
+export declare function defaultSequentialRunner(_name: string, fn: () => Promise<void>): Promise<void>;
+export declare function beginContract(runAssertion?: ContractAssertionRunner): {
+    run: (name: string, fn: () => Promise<void>) => void;
+    settle: () => Promise<void>;
+};

package/dist/core/store-contracts/contract-harness.js

@@ -0,0 +1,16 @@
+export function defaultSequentialRunner(_name, fn) {
+    return fn();
+}
+export function beginContract(runAssertion = defaultSequentialRunner) {
+    const pending = [];
+    return {
+        run: (name, fn) => {
+            const result = runAssertion(name, fn);
+            if (result instanceof Promise)
+                pending.push(result);
+        },
+        settle: async () => {
+            await Promise.all(pending);
+        },
+    };
+}

package/dist/core/store-contracts/contract-kit-version.d.ts

@@ -0,0 +1 @@
+export declare const CONTRACT_KIT_ENGINE_VERSION: string;

package/dist/core/store-contracts/contract-kit-version.js

@@ -0,0 +1,2 @@
+import { engineVersion } from "../version.js";
+export const CONTRACT_KIT_ENGINE_VERSION = engineVersion();

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

@@ -0,0 +1,3 @@
+import type { FileSnapshotStore } from "../file-snapshot-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function fileSnapshotStoreContract(make: () => FileSnapshotStore, runAssertion?: ContractAssertionRunner): Promise<void>;

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

@@ -0,0 +1,126 @@
+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) {
+    const { run, settle } = beginContract(runAssertion);
+    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 and GCs the now-unreferenced blobs", 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);
+        assert.equal(await store.getBlob(sha256("alpha")), undefined);
+    });
+    await settle();
+}

package/dist/core/store-contracts/mailbox-store-contract.d.ts

@@ -0,0 +1,6 @@
+import type { MailboxStore } from "../mailbox-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare const MAILBOX_CONTRACT_SCOPE = "default";
+export declare function mailboxStoreContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function mailboxAckOwnershipContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function mailboxBundledOnlyContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;