@sema-agent/core 2.3.0 → 2.5.0

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>;

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

@@ -0,0 +1,193 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export const MAILBOX_CONTRACT_SCOPE = "default";
+const msg = (content, sentAt = 1000) => ({ content, sentAt });
+async function withStores(mk, fn) {
+    const live = [];
+    const make = () => {
+        const s = mk();
+        live.push(s);
+        return s;
+    };
+    try {
+        await fn(make);
+    }
+    finally {
+        for (const s of live.splice(0))
+            s.close?.();
+    }
+}
+export async function mailboxStoreContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("append 铸单调 seq;claimLease 取全部可见消息(不删);ack 才删;活租约=单消费者", async (make) => {
+        const s = make();
+        assert.equal(await s.append(S, "a1", msg("m1")), 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.content), ["m1", "m2"]);
+        assert.equal(lease.maxSeq, 2);
+        assert.equal(await s.claimLease(S, "a1", "w2", 60_000, 20_000), null);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        await s.ack(S, "a1", "w1", 2);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("X-1 无损:lease 过期/release 后消息按原 seq 回可见;seq 在箱的一生中永不复用", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l1 = await s.claimLease(S, "a1", "w1", 1_000, 10_000);
+        assert.equal(l1.maxSeq, 1);
+        const l2 = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
+        assert.deepEqual(l2.messages.map((m) => m.seq), [1]);
+        await s.releaseLease(S, "a1", "w2");
+        const l3 = await s.claimLease(S, "a1", "w3", 1_000, 20_500);
+        assert.deepEqual(l3.messages.map((m) => m.seq), [1]);
+        await s.ack(S, "a1", "w3", 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+    });
+    run("lease 窗内 append:后到消息在下次 claim 时可见(lease 只覆盖 claim 时刻快照)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.equal(l.maxSeq, 1);
+        await s.append(S, "a1", msg("m2"));
+        await s.ack(S, "a1", "w1", l.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+        const next = await s.claimLease(S, "a1", "w2", 60_000, 20_000);
+        assert.deepEqual(next.messages.map((m) => m.content), ["m2"]);
+    });
+    run("drop 清整箱;reap 按最新消息龄整箱老化", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("old", 1_000));
+        await s.append(S, "a2", msg("fresh", 90_000));
+        assert.equal(await s.reap(S, 100_000, { maxAgeMs: 50_000 }), 1);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.peekCount(S, "a2"), 1);
+        await s.drop(S, "a2");
+        assert.equal(await s.peekCount(S, "a2"), 0);
+    });
+    run("RB-86 空箱 ⇒ null:没消息就不发租约(既不假装投递,也不 fence 掉后来真正的消费者)", async (make) => {
+        const s = make();
+        assert.equal(await s.claimLease(S, "never-written", "o1", 60_000, 1_000), null, "从未写过的箱");
+        await s.append(S, "a1", msg("m1"));
+        const first = await s.claimLease(S, "a1", "o1", 60_000, 1_000);
+        await s.ack(S, "a1", "o1", first.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.claimLease(S, "a1", "o1", 60_000, 2_000), null, "全部 ack 后箱内零可见消息");
+        assert.equal(await s.claimLease(S, "a2", "ghost", 60_000, 3_000), null);
+        await s.append(S, "a2", msg("real", 4_000));
+        const real = await s.claimLease(S, "a2", "o2", 60_000, 4_000);
+        assert.deepEqual(real?.messages.map((m) => m.content), ["real"], "空取不该留下 fence 后来者的幽灵租约");
+    });
+    run("RB-261 守恒律:一条消息在被 ack 消费之前必须至少投递过一次(maxSeq 不得覆盖未投递项)", async (make) => {
+        const s = make();
+        const appended = ["m1", "m2", "m3"];
+        for (const [i, c] of appended.entries())
+            await s.append(S, "a1", msg(c, 1_000 + i));
+        const delivered = new Set();
+        let round = 0;
+        while ((await s.peekCount(S, "a1")) > 0) {
+            round += 1;
+            assert.ok(round < 10, "要么有限轮内收敛,要么就是投递不动了");
+            const owner = `w${round}`;
+            const lease = await s.claimLease(S, "a1", owner, 60_000, 10_000 + round);
+            assert.notEqual(lease, null, "还有可见消息时 claimLease 不得返回 null");
+            for (const m of lease.messages)
+                delivered.add(m.content);
+            await s.ack(S, "a1", owner, lease.maxSeq);
+        }
+        assert.deepEqual([...delivered].sort(), [...appended].sort(), "每条被消费掉的消息都必须先被投递过");
+    });
+    run("releaseLease owner-fenced:非持有者的 release 是 no-op(活租约的单消费者窗口不被外人撬开)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const held = await s.claimLease(S, "a1", "owner-A", 60_000, 10_000);
+        assert.equal(held.messages.length, 1);
+        await s.releaseLease(S, "a1", "not-the-owner");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "A 的活租约必须仍然 fence 住 rival");
+        await s.releaseLease(S, "a1", "owner-A");
+        const after = await s.claimLease(S, "a1", "rival", 60_000, 12_000);
+        assert.deepEqual(after?.messages.map((m) => m.seq), [1], "归还后同一条按原 seq 回可见");
+    });
+    await settle();
+}
+export async function mailboxAckOwnershipContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("a non-holder's ack does not delete messages held under another owner's LIVE lease", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        assert.equal(lease?.messages.length, 2);
+        await s.ack(S, "a1", "stale-actor", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "the messages must survive — this caller never held the lease");
+    });
+    run("angle 4 — internal consistency: releaseLease and ack now apply the SAME owner fence (was the asymmetry that proved this was an oversight)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.claimLease(S, "a1", "real-owner", 60_000, 10_000);
+        await s.releaseLease(S, "a1", "wrong-owner");
+        await s.ack(S, "a1", "wrong-owner", 1);
+        assert.equal(await s.peekCount(S, "a1"), 1, "neither operation should have touched anything");
+    });
+    run("angle 5 — ack with no lease EVER claimed is a no-op, not a silent wipe", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.ack(S, "a1", "nobody", Number.MAX_SAFE_INTEGER);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+    });
+    run("the legitimate holder's own ack still works (regression check — the fix must not break the happy path)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        await s.ack(S, "a1", "consumer-A", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("angle 3 in detail — the real loss sequence (stale owner outlives its own expired lease, a NEW owner has since taken over): the new owner's custody survives", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "ship-the-release", sentAt: 1 });
+        await s.append(S, "a1", { content: "notify-oncall", sentAt: 2 });
+        const leaseA = await s.claimLease(S, "a1", "consumer-A", 1_000, 1_000);
+        assert.equal(leaseA?.messages.length, 2);
+        const leaseB = await s.claimLease(S, "a1", "consumer-B", 60_000, 5_000);
+        assert.equal(leaseB?.messages.length, 2);
+        await s.ack(S, "a1", "consumer-A", leaseA.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "B's live custody must survive A's stale ack");
+        await s.ack(S, "a1", "consumer-B", leaseB.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    await settle();
+}
+export async function mailboxBundledOnlyContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    run("RB-251(黑板 [1937]):handle 含 NUL 被两个后端一致拒绝,且不得跨 (scope,handle) 串箱", async (make) => {
+        const s = make();
+        const NUL = String.fromCharCode(0);
+        await assert.rejects(s.append("s", `a${NUL}b`, msg("secret")));
+        assert.equal(await s.peekCount(`s${NUL}a`, "b"), 0, "歧义键下不得出现串箱可读");
+        await s.append("s", "plain", msg("ok"));
+        assert.equal(await s.peekCount("s", "plain"), 1);
+    });
+    run("多租户:同名 handle 在不同 scope 下是两个互不可见的箱(各自独立铸 seq)", async (make) => {
+        const s = make();
+        assert.equal(await s.append("tenant-a", "shared-handle", msg("for-a")), 1);
+        assert.equal(await s.append("tenant-b", "shared-handle", msg("for-b")), 1, "另一个 scope 的箱独立铸号");
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 1);
+        const a = await s.claimLease("tenant-a", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(a.messages.map((m) => m.content), ["for-a"]);
+        const b = await s.claimLease("tenant-b", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(b.messages.map((m) => m.content), ["for-b"]);
+        await s.ack("tenant-a", "shared-handle", "w", a.maxSeq);
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 0);
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 1, "跨 scope 的 ack 不得越界");
+        await s.drop("tenant-b", "shared-handle");
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 0);
+    });
+    await settle();
+}

package/dist/core/store-contracts/session-repo-contract.d.ts

@@ -0,0 +1,3 @@
+import type { SessionRepo } from "../../internal/harness-types.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function sessionRepoContract(make: () => SessionRepo, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/session-repo-contract.js

@@ -0,0 +1,36 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+const SESSION_ENTRY = (id, parentId) => ({
+    id,
+    parentId,
+    type: "message",
+    timestamp: "2026-07-30T00:00:00.000Z",
+    message: { role: "user", content: [{ type: "text", text: `t-${id}` }], timestamp: 1785340800000 },
+});
+export async function sessionRepoContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    const A = "0198fa00-0000-7000-8000-00000000000a";
+    run("RB-360 create({id}) on an id that ALREADY has history is an idempotent REOPEN — never a wipe", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+        const again = await repo.create({ id: A });
+        const entries = await again.getStorage().getEntries();
+        assert.deepEqual(entries.map((e) => e.id), ["e1", "e2"]);
+        const exported = (await repo.exportEntries?.(A)) ?? [];
+        assert.deepEqual(exported.map((e) => e.id), ["e1", "e2"]);
+    });
+    run("create({id}) fresh → open() sees appended entries (round-trip floor)", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const opened = await repo.open({ id: A, createdAt: "" });
+        assert.deepEqual((await opened.getStorage().getEntries()).map((e) => e.id), ["e1"]);
+    });
+    run("open(missing) throws not_found — never a silent create", async () => {
+        const repo = make();
+        await assert.rejects(repo.open({ id: "0198fa00-0000-7000-8000-0000000000ff", createdAt: "" }), /not.?found/i);
+    });
+    await settle();
+}

package/dist/core/store-contracts/tool-result-store-contract.d.ts

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

package/dist/core/store-contracts/tool-result-store-contract.js

@@ -0,0 +1,35 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export async function toolResultStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("put/get full + sliced; write-once no-op; unknown → undefined", async () => {
+        const store = make();
+        const ref = "tr_s_c";
+        await store.put(ref, "0123456789");
+        assert.deepEqual(await store.get(ref), { content: "0123456789", offset: 0, totalChars: 10 });
+        assert.deepEqual(await store.get(ref, { offset: 2, limit: 3 }), { content: "234", offset: 2, totalChars: 10 });
+        await store.put(ref, "IGNORED");
+        assert.equal((await store.get(ref)).content, "0123456789");
+        assert.equal(await store.get("tr_unknown"), undefined);
+    });
+    run("RB-266 unsafe refs are rejected at the WRITE by every backend; the read face degrades instead", async () => {
+        const store = make();
+        const NUL = String.fromCharCode(0);
+        const unsafe = ["", ".", "..", "a/b", "../escape", "dir\\ref", `tr_x${NUL}y`];
+        for (const ref of unsafe) {
+            await assert.rejects((async () => store.put(ref, "payload"))(), `put(${JSON.stringify(ref)}) must reject — a durable backend cannot key it`);
+            assert.equal(await store.get(ref), undefined, "get of an unsafe ref degrades to undefined");
+        }
+        await store.put("tr_sess-1_call.7", "ok");
+        assert.equal((await store.get("tr_sess-1_call.7")).content, "ok");
+    });
+    run("RB-273 a ref the contract ACCEPTS round-trips on every backend (no backend is stricter than the rule)", async () => {
+        const store = make();
+        for (const ref of ["tr_sess_call:1", "tr_sess_call%2F1", "tr_sess_call 1", "tr_sess_日本語"]) {
+            await store.put(ref, `payload-${ref}`);
+            assert.equal((await store.get(ref))?.content, `payload-${ref}`, `put(${JSON.stringify(ref)}) must round-trip here`);
+        }
+        assert.equal((await store.get("tr_sess_call:1")).content, "payload-tr_sess_call:1");
+    });
+    await settle();
+}