@sema-agent/core 7.53.0 → 7.54.1

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

@@ -0,0 +1,683 @@
+import { strict as assert } from "node:assert";
+import { uuidv7 } from "../../internal/harness.js";
+import { hasSessionFork, isSessionConflict } from "../session.js";
+import { readMember } from "../thrown-value.js";
+import { receiptRefusal, receiveOwnProperties } from "../own-property-receipt.js";
+import { beginContract } from "./contract-harness.js";
+import { registerSessionIncarnationCases } from "./session-store-incarnation-contract.js";
+const AT = "2026-10-18T00:00:00.000Z";
+const AT_MS = Date.parse(AT);
+const STAMP = { api: "openai-completions", provider: "contract-kit", model: "contract-kit-model" };
+const ZERO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+function userEntry(id, parentId, text = `t-${id}`) {
+    return { id, parentId, type: "message", timestamp: AT, message: { role: "user", content: [{ type: "text", text }], timestamp: AT_MS } };
+}
+function assistantEntry(id, parentId, toolCall) {
+    const content = toolCall !== undefined ? [{ type: "toolCall", id: toolCall, name: "Read", arguments: { file_path: "/kit/x" } }] : [{ type: "text", text: `a-${id}` }];
+    return { id, parentId, type: "message", timestamp: AT, message: { role: "assistant", content, ...STAMP, usage: ZERO_USAGE, stopReason: toolCall !== undefined ? "toolUse" : "stop", timestamp: AT_MS } };
+}
+function toolResultEntry(id, parentId, toolCallId) {
+    return { id, parentId, type: "message", timestamp: AT, message: { role: "toolResult", toolCallId, toolName: "Read", content: [{ type: "text", text: "ok" }], isError: false, timestamp: AT_MS } };
+}
+function compactionEntry(id, parentId, firstKeptEntryId) {
+    return { id, parentId, type: "compaction", timestamp: AT, summary: "summary of the turns above the floor", firstKeptEntryId, tokensBefore: 1000 };
+}
+const freshId = () => uuidv7();
+function placementFor(scope, handle = `a${uuidv7().slice(-12)}`) {
+    return { kind: "subagent", scope: scope ?? `kit-${uuidv7().slice(-12)}`, ...(handle !== null ? { handle } : {}) };
+}
+const tick = () => new Promise((resolve) => setTimeout(resolve, 20));
+async function append(session, entry, opts) {
+    await session.getStorage().appendEntry(entry, opts);
+}
+async function pathIds(session, leafId) {
+    const storage = session.getStorage();
+    const leaf = leafId === undefined ? await storage.getLeafId() : leafId;
+    return (await storage.getPathToRoot(leaf)).map((e) => e.id);
+}
+async function entryIds(session) {
+    return (await session.getStorage().getEntries()).map((e) => e.id);
+}
+async function thrownBy(fn, what) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        return err;
+    }
+    assert.fail(`${what}: expected a refusal, got a result`);
+}
+async function rejectsWithCode(fn, code, what) {
+    const err = await thrownBy(fn, what);
+    assert.equal(readMember(err, "code"), code, `${what}: the refusal must carry code ${code}`);
+}
+function conflictMiss(err) {
+    if (isSessionConflict(err))
+        return undefined;
+    return readMember(err, "code") === "conflict"
+        ? `the refusal carries code "conflict" but is not this package's SessionError — a second copy of @sema-agent/core, or a hand-rolled error; the engine's reconcile retry does not recognize it either`
+        : `the refusal must be the engine's session conflict (SessionError "conflict"), got code ${String(readMember(err, "code"))}`;
+}
+async function rejectsWithConflict(fn, what) {
+    const miss = conflictMiss(await thrownBy(fn, what));
+    assert.equal(miss, undefined, `${what}: ${miss}`);
+}
+const LOOP_WALK_BUDGET_MS = 2000;
+async function refusedAsLoop(storage, leafId, loopMembers, what) {
+    let timer;
+    const expiry = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new assert.AssertionError({ message: `${what}: no answer within ${LOOP_WALK_BUDGET_MS} ms — the walk does not end on a parent chain that loops back on itself` })), LOOP_WALK_BUDGET_MS);
+    });
+    const settled = Promise.resolve()
+        .then(() => storage.getPathToRoot(leafId))
+        .then((path) => ({ path }), (err) => ({ err }));
+    const outcome = await Promise.race([settled, expiry]).finally(() => clearTimeout(timer));
+    if ("path" in outcome)
+        assert.fail(`${what}: a parent chain that loops back on itself answered a path of ${outcome.path.length} entries instead of refusing`);
+    assert.equal(readMember(outcome.err, "code"), "invalid_session", `${what}: the refusal must carry code invalid_session`);
+    const sentence = String(readMember(outcome.err, "message"));
+    assert.ok(loopMembers.some((id) => sentence.includes(id)), `${what}: the refusal must name an entry of the loop (${loopMembers.join(" / ")}), got "${sentence}"`);
+}
+function rowOf(rows, sessionId) {
+    return rows.find((r) => r.sessionId === sessionId);
+}
+function assertNewestFirst(rows) {
+    for (let i = 1; i < rows.length; i++) {
+        assert.ok(rows[i - 1].lastActiveAt >= rows[i].lastActiveAt, `list() must be newest-first by lastActiveAt (row ${i - 1} ${rows[i - 1].lastActiveAt} before row ${i} ${rows[i].lastActiveAt})`);
+    }
+}
+function registerUntyped(store, sessionId, owner) {
+    return Reflect.apply(store.register, store, [sessionId, owner]);
+}
+const hasOwnership = (s) => typeof s.ownerOf === "function" && typeof s.register === "function";
+const declaresPlacements = (s) => s.placements?.subagent !== undefined;
+async function honorsRequireExisting(store) {
+    const probe = freshId();
+    await store.acquire(probe);
+    try {
+        await store.acquire(probe, { requireExisting: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readBack(store, sessionId) {
+    return (await store.acquire(sessionId, (await honorsRequireExisting(store)) ? { requireExisting: true } : undefined)).session;
+}
+function assertActivityOrder(rows, newerToOlder, what) {
+    for (let i = 1; i < newerToOlder.length; i++) {
+        const newer = rowOf(rows, newerToOlder[i - 1]);
+        const older = rowOf(rows, newerToOlder[i]);
+        assert.ok(newer !== undefined && older !== undefined, `${what}: both sessions are listed`);
+        assert.ok(newer.lastActiveAt >= older.lastActiveAt, `${what}: ${newerToOlder[i - 1]} was active after ${newerToOlder[i]} (lastActiveAt ${newer.lastActiveAt} < ${older.lastActiveAt})`);
+    }
+}
+const HOOK_WORDS = { subject: "SessionStoreContractHooks", unit: "hook", moment: "at sessionStoreContract" };
+const REQUIRED_HOOKS = ["deleteSession", "reopen"];
+const OPTIONAL_HOOKS = ["replica", "runAssertion", "onOptionalMember"];
+function receiveHooks(make, hooks) {
+    if (typeof make !== "function")
+        throw receiptRefusal(`sessionStoreContract: make must be a function that returns a fresh SessionStore, got ${typeof make}`);
+    if (typeof hooks !== "object" || hooks === null)
+        throw receiptRefusal(`sessionStoreContract: hooks must be a ${HOOK_WORDS.subject} record, got ${hooks === null ? "null" : typeof hooks}`);
+    const got = receiveOwnProperties(hooks, HOOK_WORDS);
+    for (const name of REQUIRED_HOOKS) {
+        const hook = readMember(got, name);
+        if (typeof hook !== "function")
+            throw receiptRefusal(`${HOOK_WORDS.subject}.${name} is required and must be a function, got ${typeof hook}`);
+    }
+    for (const name of OPTIONAL_HOOKS) {
+        const hook = readMember(got, name);
+        if (hook !== undefined && typeof hook !== "function")
+            throw receiptRefusal(`${HOOK_WORDS.subject}.${name} must be a function when present, got ${typeof hook}`);
+    }
+    return got;
+}
+export function sessionStoreContract(make, hooks) {
+    return runSessionStoreContract(make, receiveHooks(make, hooks));
+}
+async function runSessionStoreContract(make, hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const report = (member, status) => hooks.onOptionalMember?.({ member, status });
+    const run = (name, fn) => runRaw(name, async () => {
+        const store = make();
+        const extra = [];
+        const open = async (s) => {
+            const opened = await s;
+            extra.push(opened);
+            return opened;
+        };
+        try {
+            await fn(store, open);
+        }
+        finally {
+            for (const s of extra.reverse())
+                await s.dispose();
+            await store.dispose();
+        }
+    });
+    const FACE_PRESENT = {
+        requireExisting: honorsRequireExisting,
+        forget: (s) => typeof s.forget === "function",
+        fork: hasSessionFork,
+        list: (s) => typeof s.list === "function",
+        noteTaskRun: (s) => typeof s.noteTaskRun === "function",
+        listPlaced: (s) => declaresPlacements(s) && typeof s.listPlaced === "function",
+        placements: declaresPlacements,
+        ownership: hasOwnership,
+        incarnationOf: (s) => typeof s.incarnationOf === "function",
+        replica: () => hooks.replica !== undefined,
+    };
+    const faceRun = (name, needs, fn) => run(name, async (store, open) => {
+        const missing = [];
+        for (const m of needs)
+            if (!(await FACE_PRESENT[m](store)))
+                missing.push(m);
+        if (missing.length > 0) {
+            for (const m of missing)
+                report(m, "absent");
+            return;
+        }
+        await fn(store, open);
+        for (const m of needs)
+            report(m, "verified");
+    });
+    run("[acquire] acquire() with no id mints a fresh, empty session whose id is the one handed back; two calls are two sessions", async (store) => {
+        const first = await store.acquire();
+        assert.equal(typeof first.sessionId, "string");
+        assert.notEqual(first.sessionId, "", "a minted id names a session");
+        assert.equal((await first.session.getMetadata()).id, first.sessionId, "the id acquire hands back is the session's own");
+        assert.equal(await first.session.getStorage().getLeafId(), null, "a fresh session has no leaf");
+        assert.deepEqual(await entryIds(first.session), [], "a fresh session has no entries");
+        const second = await store.acquire();
+        assert.notEqual(second.sessionId, first.sessionId, "two id-less acquires are two sessions");
+    });
+    run("[acquire] acquire(id) creates on a miss and reopens on a hit — the same history, never a wipe", async (store) => {
+        const id = freshId();
+        const created = await store.acquire(id);
+        assert.equal(created.sessionId, id);
+        assert.equal((await created.session.getMetadata()).id, id, "the created session carries the id it was asked for");
+        await append(created.session, userEntry("e1", null));
+        assert.deepEqual(await entryIds((await store.acquire(id)).session), ["e1"], "a re-acquire reopens the history");
+        assert.deepEqual(await entryIds(await readBack(store, id)), ["e1"], "a require-existing reopen (where honored) reads the same history");
+    });
+    run("[acquire] acquire(id, {requireExisting:true}) never creates: on a missing id it rejects not_found — or, on a store that rejects the option, it is refused on every id", async (store) => {
+        const id = freshId();
+        const honored = await honorsRequireExisting(store);
+        if (honored) {
+            await rejectsWithCode(() => store.acquire(id, { requireExisting: true }), "not_found", "require-existing on a missing id");
+            await rejectsWithCode(() => store.acquire(id, { requireExisting: true }), "not_found", "the refused acquire must not have created the session");
+        }
+        else {
+            await thrownBy(() => store.acquire(id, { requireExisting: true }), "a store that rejects the option, on a missing id");
+        }
+        if (typeof store.list === "function")
+            assert.equal(rowOf(await store.list(), id), undefined, "the refused acquire must not surface on the session list");
+        if (typeof store.incarnationOf === "function")
+            assert.equal(await store.incarnationOf(id), undefined, "nor have a row");
+        report("requireExisting", honored ? "verified" : "absent");
+    });
+    run("[acquire] two concurrent acquires of one id are one session: one log, and the second write on the same parent loses the CAS", async (store) => {
+        const id = freshId();
+        const [a, b] = await Promise.all([store.acquire(id), store.acquire(id)]);
+        assert.equal(a.sessionId, id);
+        assert.equal(b.sessionId, id);
+        await append(a.session, userEntry("e1", null), { expectedLeafId: null });
+        await rejectsWithConflict(() => append(b.session, userEntry("e2", null), { expectedLeafId: null }), "a second write on the empty session through the other caller's handle");
+        assert.deepEqual(await entryIds((await readBack(store, id))), ["e1"], "two callers must not have created two sessions (the second wiping the first)");
+    });
+    run("[acquire] a create-capable acquire racing a require-existing acquire of the same missing id still creates (the not_found is the require-existing caller's alone)", async (store) => {
+        for (const order of ["require-first", "create-first"]) {
+            const id = freshId();
+            const calls = order === "require-first" ? [store.acquire(id, { requireExisting: true }), store.acquire(id)] : [store.acquire(id), store.acquire(id, { requireExisting: true })];
+            const settled = await Promise.allSettled(calls);
+            const createCapable = settled[order === "require-first" ? 1 : 0];
+            assert.equal(createCapable.status, "fulfilled", `${order}: the create-capable acquire must create on the miss, never inherit the require-existing caller's not_found`);
+            assert.equal(createCapable.value.sessionId, id);
+        }
+    });
+    run("[tree] a fresh session has no leaf and an empty path; appends advance the leaf and the path walks root → leaf", async (store) => {
+        const { session } = await store.acquire(freshId());
+        const storage = session.getStorage();
+        assert.equal(await storage.getLeafId(), null);
+        assert.deepEqual(await storage.getPathToRoot(null), [], "the path to no leaf is empty");
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        assert.equal(await storage.getLeafId(), "e2", "an append moves the leaf onto the appended entry");
+        const path = await storage.getPathToRoot("e2");
+        assert.deepEqual(path.map((e) => e.id), ["e1", "e2"]);
+        assert.equal(path[0].parentId, null, "an unbounded path starts at a root");
+        assert.equal((await storage.getEntry("e1"))?.id, "e1");
+        assert.equal(await storage.getEntry("kit-never-written"), undefined, "an id the session never held reads as absent");
+    });
+    run("[tree] setLeafId moves the active leaf, a later append branches from it, and the log keeps both branches", async (store) => {
+        const { session } = await store.acquire(freshId());
+        const storage = session.getStorage();
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        await storage.setLeafId("e1");
+        assert.equal(await storage.getLeafId(), "e1");
+        await append(session, userEntry("e3", "e1"));
+        assert.equal(await storage.getLeafId(), "e3");
+        assert.deepEqual(await pathIds(session, "e3"), ["e1", "e3"], "the new branch");
+        assert.deepEqual(await pathIds(session, "e2"), ["e1", "e2"], "the abandoned branch is still in the log");
+        const ids = await entryIds(session);
+        for (const id of ["e1", "e2", "e3"])
+            assert.ok(ids.includes(id), `getEntries keeps ${id}`);
+        assert.ok(ids.indexOf("e1") < ids.indexOf("e2") && ids.indexOf("e2") < ids.indexOf("e3"), "getEntries is oldest-first");
+    });
+    run("[tree] a leaf this session never held is refused — setLeafId and getPathToRoot answer not_found, never an empty path, and the leaf stays", async (store) => {
+        const { session } = await store.acquire(freshId());
+        const storage = session.getStorage();
+        await append(session, userEntry("e1", null));
+        await rejectsWithCode(() => storage.setLeafId("kit-never-written"), "not_found", "setLeafId onto an id the session never held");
+        assert.equal(await storage.getLeafId(), "e1", "a refused setLeafId leaves the leaf where it was");
+        await rejectsWithCode(() => storage.getPathToRoot("kit-never-written"), "not_found", "getPathToRoot from an id the session never held");
+    });
+    run("[tree] a path stops at a root or at the storage's declared floor; a parent missing above the floor reads invalid_session, never a truncated path", async (store) => {
+        const { session } = await store.acquire(freshId());
+        await append(session, userEntry("e1", null));
+        let accepted = true;
+        try {
+            await append(session, userEntry("orphan", "kit-absent-parent"));
+        }
+        catch {
+            accepted = false;
+        }
+        if (accepted) {
+            await rejectsWithCode(() => session.getStorage().getPathToRoot("orphan"), "invalid_session", "the path through an entry whose parent was never written");
+        }
+        const head = (await session.getStorage().getPathToRoot("e1"))[0];
+        assert.ok(head.parentId === null || head.id === session.getStorage().getFloorId?.(), "a path's head is a root or the declared floor");
+    });
+    run("[tree] a parent chain that loops back on itself — an entry that is its own parent, two entries that parent each other, a leaf that walks into such a pair — reads invalid_session naming an entry of the loop, and the walk ends (also for a ring of three)", async (store) => {
+        const { session } = await store.acquire(freshId());
+        await append(session, userEntry("e1", null));
+        const accepted = async (...entries) => {
+            try {
+                for (const e of entries)
+                    await append(session, e);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const storage = session.getStorage();
+        if (await accepted(userEntry("kit-loop-self", "kit-loop-self"))) {
+            await refusedAsLoop(storage, "kit-loop-self", ["kit-loop-self"], "the path from an entry that is its own parent");
+        }
+        if (await accepted(userEntry("kit-loop-p", "kit-loop-q"), userEntry("kit-loop-q", "kit-loop-p"))) {
+            await refusedAsLoop(storage, "kit-loop-q", ["kit-loop-p", "kit-loop-q"], "the path from one of two entries that parent each other");
+            if (await accepted(userEntry("kit-loop-t", "kit-loop-p"))) {
+                await refusedAsLoop(storage, "kit-loop-t", ["kit-loop-p", "kit-loop-q"], "the path from a leaf outside the loop that walks into it");
+            }
+        }
+        if (await accepted(userEntry("kit-ring-1", "kit-ring-3"), userEntry("kit-ring-2", "kit-ring-1"), userEntry("kit-ring-3", "kit-ring-2"))) {
+            await refusedAsLoop(storage, "kit-ring-3", ["kit-ring-1", "kit-ring-2", "kit-ring-3"], "the path from one of three entries that parent each other in a ring");
+        }
+        assert.deepEqual(await pathIds(session, "e1"), ["e1"], "a path that does not touch the loop still reads");
+    });
+    run("[tree] the write CAS: an append or setLeafId whose expectedLeafId is stale is refused with the engine's conflict and writes nothing", async (store) => {
+        const { session } = await store.acquire(freshId());
+        const storage = session.getStorage();
+        await append(session, userEntry("e1", null), { expectedLeafId: null });
+        await rejectsWithConflict(() => append(session, userEntry("e2", null), { expectedLeafId: null }), "an append expecting an empty session after e1 landed");
+        await rejectsWithConflict(() => storage.setLeafId("e1", { expectedLeafId: "kit-stale-leaf" }), "a setLeafId expecting a leaf the session does not have");
+        assert.deepEqual(await entryIds(session), ["e1"], "a refused write leaves no entry behind");
+        assert.equal(await storage.getLeafId(), "e1");
+        await append(session, userEntry("e2", "e1"), { expectedLeafId: "e1" });
+        assert.equal(await storage.getLeafId(), "e2", "a current expectedLeafId writes");
+    });
+    run("[tree] two concurrent appends on one parent: exactly one lands, the other is refused with the engine's conflict", async (store) => {
+        const id = freshId();
+        const { session } = await store.acquire(id);
+        await append(session, userEntry("e1", null));
+        const settled = await Promise.allSettled([append(session, userEntry("x", "e1"), { expectedLeafId: "e1" }), append(session, userEntry("y", "e1"), { expectedLeafId: "e1" })]);
+        const won = settled.flatMap((s, i) => (s.status === "fulfilled" ? [i === 0 ? "x" : "y"] : []));
+        assert.equal(won.length, 1, "two writers on one parent: one wins, never both (a silent fork) and never neither");
+        const lost = settled.find((s) => s.status === "rejected");
+        const miss = conflictMiss(lost.reason);
+        assert.equal(miss, undefined, `the loser: ${miss}`);
+        assert.deepEqual(await pathIds((await readBack(store, id))), ["e1", won[0]], "the log holds the winner's branch");
+    });
+    faceRun("[tree] a handle held across forget and a fresh handle from the re-acquire share one CAS", ["forget"], async (store) => {
+        const id = freshId();
+        const held = (await store.acquire(id)).session;
+        await append(held, userEntry("e1", null));
+        await store.forget(id);
+        const fresh = (await readBack(store, id));
+        await append(held, userEntry("x", "e1"), { expectedLeafId: "e1" });
+        await rejectsWithConflict(() => append(fresh, userEntry("y", "e1"), { expectedLeafId: "e1" }), "the fresh handle writing on the parent the held handle already advanced");
+        assert.deepEqual(await pathIds((await readBack(store, id))), ["e1", "x"]);
+    });
+    faceRun("[tree] a write through one replica and a write through another on the same parent: one lands, the other conflicts", ["replica"], async (store, open) => {
+        const id = freshId();
+        const other = await open(hooks.replica(store));
+        const here = (await store.acquire(id)).session;
+        await append(here, userEntry("e1", null));
+        const there = (await readBack(other, id));
+        await append(here, userEntry("x", "e1"), { expectedLeafId: "e1" });
+        await rejectsWithConflict(() => append(there, userEntry("y", "e1"), { expectedLeafId: "e1" }), "the second replica writing on the parent the first replica already advanced");
+        assert.deepEqual(await pathIds((await readBack(other, id))), ["e1", "x"], "the replica reads the winner's branch");
+    });
+    run("[rows] a session lives in the rows, not in an instance: entries, a branch switch and the leaf read back through require-existing on a reopened store", async (store, open) => {
+        const id = freshId();
+        const { session } = await store.acquire(id);
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        await session.getStorage().setLeafId("e1");
+        await append(session, userEntry("e3", "e1"));
+        const before = await entryIds(session);
+        const second = await open(hooks.reopen(store));
+        const woken = (await readBack(second, id));
+        assert.equal(await woken.getStorage().getLeafId(), "e3", "the leaf a branch switch set survives the reopen");
+        assert.deepEqual(await pathIds(woken), ["e1", "e3"]);
+        const after = await entryIds(woken);
+        for (const e of ["e1", "e2", "e3"])
+            assert.ok(after.includes(e), `the reopened log keeps ${e}`);
+        assert.deepEqual(after.filter((e) => before.includes(e)), before.filter((e) => after.includes(e)), "the reopened log keeps the written order");
+    });
+    run("[rows] a leaf switch persists by itself: setLeafId onto an earlier entry, then onto null, each reads back on a reopened store with nothing appended after it", async (store, open) => {
+        const id = freshId();
+        const { session } = await store.acquire(id);
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        await session.getStorage().setLeafId("e1");
+        const second = await open(hooks.reopen(store));
+        const woken = await readBack(second, id);
+        assert.equal(await woken.getStorage().getLeafId(), "e1", "setLeafId records the active leaf in the rows — a rewind must survive the instance");
+        assert.deepEqual(await pathIds(woken), ["e1"]);
+        await woken.getStorage().setLeafId(null);
+        const third = await open(hooks.reopen(second));
+        assert.equal(await (await readBack(third, id)).getStorage().getLeafId(), null, "a switch to no leaf persists too");
+    });
+    run("[rows] a reopened session builds the context the writer saw; its path is a suffix of the written one that starts at a root or at the declared floor", async (store, open) => {
+        const id = freshId();
+        const { session } = await store.acquire(id);
+        await append(session, userEntry("u1", null));
+        await append(session, assistantEntry("a1", "u1"));
+        await append(session, userEntry("u2", "a1"));
+        await append(session, assistantEntry("a2", "u2"));
+        await append(session, compactionEntry("c1", "a2", "u2"));
+        await append(session, userEntry("u3", "c1"));
+        const written = await pathIds(session);
+        const context = await session.buildContext();
+        const second = await open(hooks.reopen(store));
+        const woken = (await readBack(second, id));
+        const path = await woken.getStorage().getPathToRoot(await woken.getStorage().getLeafId());
+        const floor = woken.getStorage().getFloorId?.() ?? null;
+        assert.ok(path[0].parentId === null || path[0].id === floor, "a woken path's head is a root or the floor the storage declares — a headless window it does not declare is a corrupt log");
+        assert.deepEqual(path.map((e) => e.id), written.slice(written.length - path.length), "the woken path is the written path, or its tail from the floor");
+        assert.deepEqual(await woken.buildContext(), context, "waking from the rows (bounded or whole) rebuilds the same context");
+    });
+    faceRun("[rows] forget drops only the cached view: the history survives and the next acquire reopens it", ["forget"], async (store) => {
+        const id = freshId();
+        await append((await store.acquire(id)).session, userEntry("e1", null));
+        await store.forget(id);
+        assert.deepEqual(await entryIds((await readBack(store, id))), ["e1"], "forget must never delete history");
+    });
+    faceRun("[fork] fork copies the committed history into a new id stamped with its source, and the two logs are independent", ["fork"], async (store) => {
+        const src = freshId();
+        const source = (await store.acquire(src)).session;
+        await append(source, userEntry("e1", null));
+        await append(source, assistantEntry("e2", "e1"));
+        const forkedId = await store.fork(src);
+        assert.ok(forkedId !== null && forkedId !== src, "a fork of an existing session is a new id");
+        const forked = (await readBack(store, forkedId));
+        assert.deepEqual(await pathIds(forked), ["e1", "e2"], "the fork carries the source's committed history");
+        assert.equal((await forked.getMetadata()).forkedFrom, src, "the fork names its source");
+        await append(forked, userEntry("f3", "e2"));
+        await append(source, userEntry("s3", "e2"));
+        assert.deepEqual(await pathIds((await readBack(store, src))), ["e1", "e2", "s3"], "writes to the fork never reach the source");
+        assert.deepEqual(await pathIds((await readBack(store, forkedId))), ["e1", "e2", "f3"], "writes to the source never reach the fork");
+    });
+    faceRun("[fork] fork of a missing source answers null and creates nothing", ["fork"], async (store) => {
+        const missing = freshId();
+        assert.equal(await store.fork(missing), null);
+        if (await honorsRequireExisting(store))
+            await rejectsWithCode(() => store.acquire(missing, { requireExisting: true }), "not_found", "a fork of a missing source must not create it");
+        if (typeof store.incarnationOf === "function")
+            assert.equal(await store.incarnationOf(missing), undefined, "a fork of a missing source must not create it");
+    });
+    faceRun("[fork] a fork never inherits an in-flight assistant turn: a leaf turn whose tool call has no result yet (with or without sibling results already in) is left out", ["fork"], async (store) => {
+        const parallel = freshId();
+        const p = (await store.acquire(parallel)).session;
+        await append(p, userEntry("u1", null));
+        await append(p, assistantEntry("a1", "u1", "call-1"));
+        const pf = await store.fork(parallel);
+        assert.deepEqual(await pathIds((await readBack(store, pf))), ["u1"], "a leaf assistant turn with an unanswered call is in flight");
+        const sequential = freshId();
+        const q = (await store.acquire(sequential)).session;
+        await append(q, userEntry("u1", null));
+        await append(q, assistantEntry("a1", "u1", "call-1"));
+        await append(q, toolResultEntry("r1", "a1", "call-1"));
+        const qf = await store.fork(sequential);
+        assert.deepEqual(await pathIds((await readBack(store, qf))), ["u1"], "a sibling call's committed result does not settle the turn");
+        const settled = freshId();
+        const s = (await store.acquire(settled)).session;
+        await append(s, userEntry("u1", null));
+        await append(s, assistantEntry("a1", "u1"));
+        const sf = await store.fork(settled);
+        assert.deepEqual(await pathIds((await readBack(store, sf))), ["u1", "a1"], "a settled text turn forks whole");
+    });
+    faceRun("[list] list projects each live session once, newest-first by lastActiveAt, and a touch counts as activity", ["list"], async (store) => {
+        const [a, b, c] = [freshId(), freshId(), freshId()];
+        await store.acquire(a);
+        await tick();
+        await store.acquire(b);
+        await tick();
+        await store.acquire(c);
+        let rows = await store.list();
+        assertNewestFirst(rows);
+        for (const id of [a, b, c])
+            assert.equal(rows.filter((r) => r.sessionId === id).length, 1, `session ${id} is listed exactly once`);
+        assertActivityOrder(rows, [c, b, a], "acquire is activity");
+        for (const r of rows)
+            assert.ok(r.createdAt === undefined || (typeof r.createdAt === "string" && r.createdAt !== ""), "createdAt is a real timestamp or absent, never an empty placeholder");
+        const before = rowOf(rows, a).lastActiveAt;
+        await tick();
+        await store.touch(a);
+        rows = await store.list();
+        assertNewestFirst(rows);
+        assert.ok(rowOf(rows, a).lastActiveAt >= before, "a touch never moves a session's activity back");
+        assertActivityOrder(rows, [a, c, b], "a touch makes a session the most recently active");
+    });
+    faceRun("[list] a fork's summary names its source; an unforked session's names none", ["list", "fork"], async (store) => {
+        const src = freshId();
+        await append((await store.acquire(src)).session, userEntry("e1", null));
+        const forkedId = await store.fork(src);
+        const rows = await store.list();
+        assert.equal(rowOf(rows, forkedId)?.forkedFrom, src, "the fork's row carries its lineage");
+        assert.equal(rowOf(rows, src)?.forkedFrom, undefined, "the source is no fork");
+    });
+    faceRun("[list] noteTaskRun lands on the summary and counts as activity; a call without a run id clears lastTaskRunId; an unknown id never throws", ["noteTaskRun"], async (store) => {
+        await store.noteTaskRun(freshId(), "kit-task", "kit-run");
+        if (typeof store.list !== "function")
+            return;
+        const [a, b] = [freshId(), freshId()];
+        await store.acquire(a);
+        await tick();
+        await store.acquire(b);
+        await tick();
+        await store.noteTaskRun(a, "task-1", "run-1");
+        let rows = await store.list();
+        assert.equal(rowOf(rows, a)?.lastTaskId, "task-1");
+        assert.equal(rowOf(rows, a)?.lastTaskRunId, "run-1");
+        assertActivityOrder(rows, [a, b], "a run is activity: the session that just ran is the most recently active");
+        await store.noteTaskRun(a, "task-2");
+        rows = await store.list();
+        assert.equal(rowOf(rows, a)?.lastTaskId, "task-2");
+        assert.equal(rowOf(rows, a)?.lastTaskRunId, undefined, "the two seats describe one run: a newer task with no run id must not keep the older run's id");
+    });
+    faceRun("[placements] a placed session stays off the host list — before and after a restart, also when read back with require-existing", ["placements"], async (store, open) => {
+        const placed = freshId();
+        const plain = freshId();
+        await store.acquire(placed, { placement: placementFor() });
+        await store.acquire(plain);
+        if (typeof store.list !== "function")
+            return;
+        let rows = await store.list();
+        assert.equal(rowOf(rows, placed), undefined, "obligation 2: a placed session is not a host session");
+        assert.ok(rowOf(rows, plain) !== undefined, "an ordinary session is listed");
+        const second = await open(hooks.reopen(store));
+        await second.acquire(placed, { requireExisting: true });
+        await readBack(second, plain);
+        rows = await second.list();
+        assert.equal(rowOf(rows, placed), undefined, "obligation 2 is restart-stable, read-back included");
+    });
+    faceRun("[placements] a claim-form acquire of an existing placed id is refused placement_refused — on a cache hit, after forget, and after a restart", ["placements"], async (store, open) => {
+        const id = freshId();
+        await store.acquire(id, { placement: placementFor() });
+        await rejectsWithCode(() => store.acquire(id), "placement_refused", "obligation 6 on the instance that created it");
+        if (typeof store.forget === "function") {
+            await store.forget(id);
+            await rejectsWithCode(() => store.acquire(id), "placement_refused", "obligation 6 after the cached view was dropped");
+        }
+        const second = await open(hooks.reopen(store));
+        await rejectsWithCode(() => second.acquire(id), "placement_refused", "obligation 6 after a restart");
+    });
+    faceRun("[placements] require-existing re-opens a placed session — with no placement, its own, or a foreign one — on the same history, and rewrites nothing", ["placements"], async (store) => {
+        const id = freshId();
+        const own = placementFor();
+        await append((await store.acquire(id, { placement: own })).session, userEntry("e1", null));
+        assert.deepEqual(await entryIds((await store.acquire(id, { requireExisting: true })).session), ["e1"], "obligation 5: the read form");
+        assert.deepEqual(await entryIds((await store.acquire(id, { requireExisting: true, placement: own })).session), ["e1"]);
+        assert.deepEqual(await entryIds((await store.acquire(id, { requireExisting: true, placement: placementFor() })).session), ["e1"], "a foreign placement on the read form attaches to the same session");
+        await store.acquire(id, { placement: own });
+        await rejectsWithCode(() => store.acquire(id), "placement_refused", "and the session is still placed");
+    });
+    faceRun("[placements] release of a placed id is a real deletion, whatever the evict policy — not_found here and after a restart", ["placements"], async (store, open) => {
+        const id = freshId();
+        await append((await store.acquire(id, { placement: placementFor() })).session, userEntry("e1", null));
+        await store.release(id);
+        await rejectsWithCode(() => store.acquire(id, { requireExisting: true }), "not_found", "obligation 4: the released transcript is gone");
+        const second = await open(hooks.reopen(store));
+        await rejectsWithCode(() => second.acquire(id, { requireExisting: true }), "not_found", "obligation 4 holds on the durable rows, not only in the cache");
+    });
+    faceRun("[placements] an acquire carrying a placement onto an existing ordinary id, or onto one placed under another tuple, is refused placement_refused; the same tuple re-acquires", ["placements"], async (store, open) => {
+        const ordinary = freshId();
+        await store.acquire(ordinary);
+        await rejectsWithCode(() => store.acquire(ordinary, { placement: placementFor() }), "placement_refused", "a placement onto a session that exists outside the partition (cache hit)");
+        if (typeof store.forget === "function") {
+            await store.forget(ordinary);
+            await rejectsWithCode(() => store.acquire(ordinary, { placement: placementFor() }), "placement_refused", "the same after the cached view was dropped");
+        }
+        const tuple = placementFor();
+        const placed = freshId();
+        await store.acquire(placed, { placement: tuple });
+        await rejectsWithCode(() => store.acquire(placed, { placement: { ...tuple, handle: `${tuple.handle}-other` } }), "placement_refused", "a placement whose handle differs from the persisted one");
+        await rejectsWithCode(() => store.acquire(placed, { placement: { ...tuple, scope: `${tuple.scope}-other` } }), "placement_refused", "a placement whose scope differs from the persisted one");
+        await store.acquire(placed, { placement: tuple });
+        const second = await open(hooks.reopen(store));
+        await rejectsWithCode(() => second.acquire(ordinary, { placement: placementFor() }), "placement_refused", "the same after a restart");
+        await second.acquire(placed, { placement: tuple });
+    });
+    faceRun("[placements] a placed creation racing a claim-form acquire of the same id: exactly one of them gets the id, and what it got is what later reads see", ["placements"], async (store) => {
+        const id = freshId();
+        const tuple = placementFor();
+        const [placedCall, claimCall] = await Promise.allSettled([store.acquire(id, { placement: tuple }), store.acquire(id)]);
+        const winners = [placedCall, claimCall].filter((s) => s.status === "fulfilled").length;
+        assert.equal(winners, 1, "the placed creator and the claimant can never both attach (a squat or a claim of a transcript), nor both be refused");
+        if (placedCall.status === "fulfilled") {
+            await rejectsWithCode(() => store.acquire(id), "placement_refused", "the placed creator won: the id is a transcript");
+        }
+        else {
+            assert.equal(readMember(placedCall.reason, "code"), "placement_refused");
+            await rejectsWithCode(() => store.acquire(id, { placement: tuple }), "placement_refused", "the claimant won: the id is an ordinary session");
+        }
+    });
+    run("[placements] a store that does not declare placements still creates the session for an acquire carrying one (ignoring it is legal, refusing the creation is not)", async (store) => {
+        if (declaresPlacements(store))
+            return;
+        const id = freshId();
+        const acquired = await store.acquire(id, { placement: placementFor() });
+        assert.equal(acquired.sessionId, id);
+        await append(acquired.session, userEntry("e1", null));
+        assert.deepEqual(await entryIds((await readBack(store, id))), ["e1"]);
+    });
+    faceRun("[placements] listPlaced returns each placed session with its full (scope, handle) tuple or the honest tupleIncomplete, filters by scope and age, and never lists an ordinary session", ["listPlaced"], async (store) => {
+        const scope = `kit-${uuidv7().slice(-12)}`;
+        const full = placementFor(scope);
+        const [complete, incomplete, ordinary, elsewhere] = [freshId(), freshId(), freshId(), freshId()];
+        await store.acquire(complete, { placement: full });
+        await store.acquire(incomplete, { placement: placementFor(scope, null) });
+        await store.acquire(ordinary);
+        await store.acquire(elsewhere, { placement: placementFor() });
+        const rows = await store.listPlaced("subagent");
+        const row = (id) => rows.find((r) => r.sessionId === id);
+        const c = row(complete);
+        assert.ok(c !== undefined && !("tupleIncomplete" in c), "a placed session with both join halves is a full row");
+        assert.equal(c.scope, full.scope);
+        assert.equal(c.handle, full.handle);
+        assert.equal(typeof c.placedAt, "number");
+        const i = row(incomplete);
+        assert.ok(i !== undefined && "tupleIncomplete" in i && i.tupleIncomplete === true, "a placed session missing a join half is the tupleIncomplete row, never a guessed tuple");
+        assert.equal(row(ordinary), undefined, "an ordinary session is not in the placed partition");
+        assert.ok(row(elsewhere) !== undefined);
+        const scoped = (await store.listPlaced("subagent", { scope })).map((r) => r.sessionId);
+        assert.ok(scoped.includes(complete) && scoped.includes(incomplete) && !scoped.includes(elsewhere), "scope narrows to one tenant");
+        assert.ok(!(await store.listPlaced("subagent", { olderThanMs: 60 * 60 * 1000 })).some((r) => r.sessionId === complete), "a session placed just now is not an hour old");
+    });
+    faceRun("[ownership] ownerOf answers three states that never collapse: an id never registered ⇒ undefined, anonymous ⇒ null, owned ⇒ the owner", ["ownership"], async (store) => {
+        const [unknown, owned, anonymous] = [freshId(), freshId(), freshId()];
+        assert.equal(await store.ownerOf(unknown), undefined, "no ownership row ⇒ undefined, never null");
+        await store.register(owned, "kit-alice");
+        await store.register(anonymous, null);
+        assert.equal(await store.ownerOf(owned), "kit-alice");
+        assert.equal(await store.ownerOf(anonymous), null, "an anonymous row ⇒ null, never undefined");
+    });
+    faceRun("[ownership] register is first-write-wins: later calls neither overwrite nor throw, whatever they carry", ["ownership"], async (store) => {
+        const [owned, anonymous] = [freshId(), freshId()];
+        await store.register(owned, "kit-alice");
+        await store.register(owned, "kit-bob");
+        await store.register(owned, null);
+        await registerUntyped(store, owned, undefined);
+        assert.equal(await store.ownerOf(owned), "kit-alice");
+        await store.register(anonymous, null);
+        await store.register(anonymous, "kit-bob");
+        assert.equal(await store.ownerOf(anonymous), null, "an anonymous row is not claimable by a later register");
+    });
+    faceRun("[ownership] a FIRST register whose owner is neither a string nor null is refused loudly and leaves no row behind", ["ownership"], async (store) => {
+        const id = freshId();
+        await thrownBy(() => registerUntyped(store, id, undefined), "a first register with owner undefined");
+        await thrownBy(() => registerUntyped(store, id, 42), "a first register with a numeric owner");
+        assert.equal(await store.ownerOf(id), undefined, "the refused writes stored nothing");
+        await store.register(id, "kit-carol");
+        assert.equal(await store.ownerOf(id), "kit-carol", "the id is still ownable — no row that reads as 'no row' was minted");
+    });
+    faceRun("[ownership] two concurrent first registers: each caller's own re-read sees the same winner, one of the two", ["ownership"], async (store) => {
+        const id = freshId();
+        const caller = async (owner) => {
+            await store.register(id, owner);
+            return store.ownerOf(id);
+        };
+        const [x, y] = await Promise.all([caller("kit-x"), caller("kit-y")]);
+        assert.equal(x, y, "the loser must see the winner on its own re-read, or both callers attach to one session");
+        assert.ok(x === "kit-x" || x === "kit-y");
+        assert.equal(await store.ownerOf(id), x, "and the row keeps that winner");
+    });
+    faceRun("[ownership] the ownership row outlives the cached view: a registered session that is forgotten still reads its owner", ["ownership", "forget"], async (store) => {
+        const id = freshId();
+        await store.register(id, "kit-alice");
+        await append((await store.acquire(id)).session, userEntry("e1", null));
+        await store.forget(id);
+        assert.equal(await store.ownerOf(id), "kit-alice", "a live session reading undefined would be re-claimable by anyone");
+    });
+    faceRun("[ownership] a fork's ownership agrees with its source: no owner or null ⇒ the source's (an owned copy is never downgraded), an explicit owner ⇒ that owner, an anonymous source ⇒ anonymous", ["ownership", "fork"], async (store) => {
+        const owned = freshId();
+        await store.register(owned, "kit-alice");
+        await append((await store.acquire(owned)).session, userEntry("e1", null));
+        assert.equal(await store.ownerOf((await store.fork(owned))), "kit-alice", "no owner argument ⇒ the source's owner");
+        assert.equal(await store.ownerOf((await store.fork(owned, null))), "kit-alice", "an explicit null never downgrades a copy of an owned history to anonymous");
+        assert.equal(await store.ownerOf((await store.fork(owned, "kit-bob"))), "kit-bob", "an explicit owner scopes the fork");
+        const anonymous = freshId();
+        await store.register(anonymous, null);
+        await append((await store.acquire(anonymous)).session, userEntry("e1", null));
+        assert.equal(await store.ownerOf((await store.fork(anonymous))), null);
+        assert.equal(await store.ownerOf((await store.fork(anonymous, null))), null);
+    });
+    registerSessionIncarnationCases((name, fn) => faceRun(`[incarnation] ${name}`, ["incarnationOf", "requireExisting"], (store) => fn(store)), hooks);
+    await settle();
+}