@sema-agent/core 7.54.1 → 7.56.0

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

@@ -1,10 +1,9 @@
 import { strict as assert } from "node:assert";
 import { uuidv7 } from "../../internal/harness.js";
-import { hasSessionFork, isSessionConflict } from "../session.js";
+import { SESSION_LIST_LIMITS, 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" };
@@ -12,9 +11,9 @@ const ZERO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalToke
 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 assistantEntry(id, parentId, ...toolCalls) {
+    const content = toolCalls.length > 0 ? toolCalls.map((call) => ({ type: "toolCall", id: call, 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: toolCalls.length > 0 ? "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 } };
@@ -89,8 +88,22 @@ function assertNewestFirst(rows) {
 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 hasHead = (s) => typeof s.headOf === "function";
+const hasOwnership = (s) => hasHead(s) && typeof s.register === "function";
 const declaresPlacements = (s) => s.placements?.subagent !== undefined;
+const headOf = (store, sessionId) => store.headOf(sessionId);
+async function ownerOf(store, sessionId, what) {
+    const head = await headOf(store, sessionId);
+    assert.ok(head !== undefined, `${what}: the row exists, so headOf must answer it`);
+    return head.owner;
+}
+async function tokenOf(store, sessionId, what) {
+    const head = await headOf(store, sessionId);
+    assert.ok(head !== undefined, `${what}: the row exists, so headOf must answer it`);
+    assert.equal(typeof head.incarnation, "string", `${what}: a session row created through this store must carry an incarnation`);
+    assert.notEqual(head.incarnation, "", `${what}: an empty token names nobody`);
+    return head.incarnation;
+}
 async function honorsRequireExisting(store) {
     const probe = freshId();
     await store.acquire(probe);
@@ -165,8 +178,8 @@ async function runSessionStoreContract(make, hooks) {
         noteTaskRun: (s) => typeof s.noteTaskRun === "function",
         listPlaced: (s) => declaresPlacements(s) && typeof s.listPlaced === "function",
         placements: declaresPlacements,
+        headOf: hasHead,
         ownership: hasOwnership,
-        incarnationOf: (s) => typeof s.incarnationOf === "function",
         replica: () => hooks.replica !== undefined,
     };
     const faceRun = (name, needs, fn) => run(name, async (store, open) => {
@@ -214,8 +227,8 @@ async function runSessionStoreContract(make, hooks) {
         }
         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");
+        if (hasHead(store))
+            assert.equal(await headOf(store, 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) => {
@@ -438,10 +451,10 @@ async function runSessionStoreContract(make, hooks) {
         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");
+        if (hasHead(store))
+            assert.equal(await headOf(store, 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) => {
+    faceRun("[fork] a fork never inherits an in-flight assistant turn: a turn with a tool call no result answers yet (with or without sibling results already in) is left out; a turn every call of which is answered is kept", ["fork"], async (store) => {
         const parallel = freshId();
         const p = (await store.acquire(parallel)).session;
         await append(p, userEntry("u1", null));
@@ -451,10 +464,18 @@ async function runSessionStoreContract(make, hooks) {
         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, assistantEntry("a1", "u1", "call-1", "call-2"));
         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");
+        assert.deepEqual(await pathIds((await readBack(store, qf))), ["u1"], "a sibling call's committed result does not settle the turn: call-2 has none");
+        const answered = freshId();
+        const t = (await store.acquire(answered)).session;
+        await append(t, userEntry("u1", null));
+        await append(t, assistantEntry("a1", "u1", "call-1", "call-2"));
+        await append(t, toolResultEntry("r1", "a1", "call-2"));
+        await append(t, toolResultEntry("r2", "r1", "call-1"));
+        const tf = await store.fork(answered);
+        assert.deepEqual(await pathIds((await readBack(store, tf))), ["u1", "a1", "r1", "r2"], "a tool turn every call of which has its result is settled: a fork keeps it");
         const settled = freshId();
         const s = (await store.acquire(settled)).session;
         await append(s, userEntry("u1", null));
@@ -462,7 +483,7 @@ async function runSessionStoreContract(make, hooks) {
         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) => {
+    faceRun("[list] list projects each session row 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();
@@ -473,7 +494,7 @@ async function runSessionStoreContract(make, hooks) {
         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");
+        assertActivityOrder(rows, [c, b, a], "a session created later is more recent");
         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;
@@ -492,25 +513,148 @@ async function runSessionStoreContract(make, hooks) {
         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) => {
+    faceRun("[list] noteTaskRun lands on the summary; 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()];
+        const a = 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("[list] the list reads the rows, not a cache: sessions are listed after their cached view is dropped and on a store reopened over the same rows (a restart), newest first", ["list"], async (store, open) => {
+        const [a, b] = [freshId(), freshId()];
+        await append((await store.acquire(a)).session, userEntry("e1", null));
+        await tick();
+        await append((await store.acquire(b)).session, userEntry("e1", null));
+        if (typeof store.forget === "function") {
+            await store.forget(a);
+            assert.ok(rowOf(await store.list({ limit: SESSION_LIST_LIMITS.max }), a) !== undefined, "a session whose cached view was dropped is still a row");
+        }
+        const second = await open(hooks.reopen(store));
+        const rows = await second.list({ limit: SESSION_LIST_LIMITS.max });
+        assertNewestFirst(rows);
+        assertActivityOrder(rows, [b, a], "a restart keeps the activity order the rows recorded");
+    });
+    faceRun("[list] a touch is recorded on the row: the touched session is still the most recent on a store reopened over the same rows (a restart)", ["list"], async (store, open) => {
+        const [a, b] = [freshId(), freshId()];
+        await append((await store.acquire(a)).session, userEntry("e1", null));
+        await tick();
+        await append((await store.acquire(b)).session, userEntry("e1", null));
+        await tick();
+        await store.touch(a);
+        const second = await open(hooks.reopen(store));
+        assertActivityOrder(await second.list({ limit: SESSION_LIST_LIMITS.max }), [a, b], "the touch outlives the process that made it");
+    });
+    faceRun("[list] a cached view of an occupant the listed row does not name lends it nothing: after another instance deleted the row and registered the id to another owner, the row lists without the old occupant's run", ["list", "noteTaskRun", "ownership", "replica"], async (store, open) => {
+        const id = freshId();
+        const other = await open(hooks.replica(store));
+        await store.register(id, "kit-alice");
+        await store.acquire(id);
+        await store.noteTaskRun(id, "alice-task", "alice-run");
+        await other.acquire(id);
+        await hooks.deleteSession(other, id);
+        await other.register(id, "kit-bob");
+        const row = rowOf(await store.list({ owner: "kit-bob", limit: SESSION_LIST_LIMITS.max }), id);
+        assert.ok(row !== undefined, "the new owner's row is listed");
+        assert.equal(row.lastTaskId, undefined, "the previous occupant's run is not lent to the new owner's row");
+        assert.equal(row.lastTaskRunId, undefined);
+    });
+    faceRun("[list] paging survives a dropped cache: a session whose cached view is dropped between two pages is not read again", ["list", "ownership", "forget"], async (store) => {
+        const owner = `kit-forget-${uuidv7().slice(-12)}`;
+        const ids = [freshId(), freshId(), freshId()];
+        for (const id of ids) {
+            await store.register(id, owner);
+            await tick();
+        }
+        for (const id of ids)
+            await store.acquire(id);
+        const first = await store.list({ owner, limit: 1 });
+        assert.equal(first.length, 1);
+        const top = first[0];
+        await store.forget(top.sessionId);
+        const rest = await store.list({ owner, after: { lastActiveAt: top.lastActiveAt, sessionId: top.sessionId } });
+        assert.ok(!rest.some((r) => r.sessionId === top.sessionId), "the first page's row is not on the next page");
+        assert.equal(rest.length, ids.length - 1, "and every other row is");
+    });
+    faceRun("[list] owner filters by the row's owner cell: an owner's rows only; with includeUnowned the unowned rows too; no owner = every owner's rows", ["list", "ownership"], async (store) => {
+        const [alice, bob] = [`kit-alice-${uuidv7().slice(-12)}`, `kit-bob-${uuidv7().slice(-12)}`];
+        const [a1, a2, b1, u1] = [freshId(), freshId(), freshId(), freshId()];
+        await store.register(a1, alice);
+        await store.register(a2, alice);
+        await store.register(b1, bob);
+        await store.acquire(u1);
+        const ids = (rows) => new Set(rows.map((r) => r.sessionId));
+        const own = ids(await store.list({ owner: alice, limit: SESSION_LIST_LIMITS.max }));
+        assert.ok(own.has(a1) && own.has(a2), "the owner's rows are listed");
+        assert.ok(!own.has(b1) && !own.has(u1), "another owner's row and an unowned row are not");
+        const withUnowned = ids(await store.list({ owner: alice, includeUnowned: true, limit: SESSION_LIST_LIMITS.max }));
+        assert.ok(withUnowned.has(a1) && withUnowned.has(a2) && withUnowned.has(u1), "includeUnowned adds the unowned rows");
+        assert.ok(!withUnowned.has(b1), "and never another owner's");
+        const all = ids(await store.list({ limit: SESSION_LIST_LIMITS.max }));
+        for (const id of [a1, a2, b1, u1])
+            assert.ok(all.has(id), `no owner filter lists every owner's rows (${id})`);
+    });
+    faceRun("[list] keyset paging reads each row once: pages cut with limit and the after cursor, concatenated, are the one-page list — ties ordered by session id, descending", ["list", "ownership"], async (store) => {
+        const owner = `kit-pager-${uuidv7().slice(-12)}`;
+        const ids = [freshId(), freshId(), freshId(), freshId(), freshId()];
+        for (const id of ids)
+            await store.register(id, owner);
+        const whole = await store.list({ owner, limit: SESSION_LIST_LIMITS.max });
+        assert.deepEqual(new Set(whole.map((r) => r.sessionId)), new Set(ids), "the owner's five rows");
+        for (let i = 1; i < whole.length; i++) {
+            const [prev, row] = [whole[i - 1], whole[i]];
+            assert.ok(prev.lastActiveAt > row.lastActiveAt || (prev.lastActiveAt === row.lastActiveAt && prev.sessionId > row.sessionId), `row ${i} follows row ${i - 1} in (lastActiveAt, sessionId) descending order`);
+        }
+        const paged = [];
+        let after;
+        for (let pages = 0; pages < 10; pages++) {
+            const page = await store.list({ owner, limit: 2, ...(after !== undefined ? { after } : {}) });
+            assert.ok(page.length <= 2, "a page holds at most limit rows");
+            if (page.length === 0)
+                break;
+            paged.push(...page.map((r) => r.sessionId));
+            const last = page[page.length - 1];
+            after = { lastActiveAt: last.lastActiveAt, sessionId: last.sessionId };
+        }
+        assert.deepEqual(paged, whole.map((r) => r.sessionId), "the pages, in order, are the one-page list: no row twice, none skipped");
+    });
+    faceRun("[list] a query without limit reads the default page; an explicit limit reads that many", ["list", "ownership"], async (store) => {
+        const owner = `kit-page-${uuidv7().slice(-12)}`;
+        const total = SESSION_LIST_LIMITS.default + 1;
+        for (let i = 0; i < total; i++)
+            await store.register(freshId(), owner);
+        assert.equal((await store.list({ owner })).length, SESSION_LIST_LIMITS.default, `no limit = the first ${SESSION_LIST_LIMITS.default} rows`);
+        assert.equal((await store.list({ owner, limit: total })).length, total);
+        assert.equal((await store.list({ owner, limit: 1 })).length, 1);
+    });
+    faceRun("[list] a bad query is refused config.invalid_argument, never read as a default: a limit out of 1..max or not an integer, a member of the wrong type, includeUnowned without owner, a malformed cursor, a member the store does not read", ["list"], async (store) => {
+        const bad = [
+            ["limit 0", { limit: 0 }],
+            ["a negative limit", { limit: -1 }],
+            ["a fractional limit", { limit: 1.5 }],
+            ["a limit past the bound", { limit: SESSION_LIST_LIMITS.max + 1 }],
+            ["a limit spelled as a string", { limit: "10" }],
+            ["a NaN limit", { limit: Number.NaN }],
+            ["an owner that is not a string", { owner: 7 }],
+            ["includeUnowned that is not a boolean", { owner: "kit-x", includeUnowned: "yes" }],
+            ["includeUnowned without owner", { includeUnowned: true }],
+            ["a cursor without a session id", { after: { lastActiveAt: 1 } }],
+            ["a cursor whose time is not a finite number", { after: { lastActiveAt: Number.POSITIVE_INFINITY, sessionId: "x" } }],
+            ["a cursor carrying another member", { after: { lastActiveAt: 1, sessionId: "x", page: 2 } }],
+            ["a member the store does not read", { kitUnreadFilter: "x" }],
+            ["a query that is not an object", 7],
+        ];
+        for (const [what, query] of bad) {
+            await rejectsWithCode(() => Reflect.apply(store.list, store, [query]), "config.invalid_argument", `list(${what})`);
+        }
+    });
     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();
@@ -620,64 +764,230 @@ async function runSessionStoreContract(make, hooks) {
         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");
+    faceRun("[head] headOf answers undefined for an id with no row; for a row, its owner, its occupant and its active leaf — the leaf follows appends and a branch switch", ["headOf"], async (store) => {
+        const id = freshId();
+        assert.equal(await headOf(store, id), undefined, "no row ⇒ undefined");
+        const { session } = await store.acquire(id);
+        assert.deepEqual(await headOf(store, id), { owner: null, incarnation: (await session.getMetadata()).incarnation, leafId: null }, "a row acquire created: no owner, its occupant, no leaf");
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        assert.equal((await headOf(store, id))?.leafId, "e2", "an append moves the head's leaf");
+        await session.getStorage().setLeafId("e1");
+        assert.equal((await headOf(store, id))?.leafId, "e1", "a branch switch moves it back");
+        await session.getStorage().setLeafId(null);
+        assert.equal((await headOf(store, id))?.leafId, null);
+    });
+    faceRun("[head] the head lives in the row: a store reopened over the same rows (a restart) answers the same owner, occupant and leaf", ["headOf"], 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 before = await headOf(store, id);
+        const second = await open(hooks.reopen(store));
+        assert.deepEqual(await headOf(second, id), before, "a head an instance kept for itself would answer differently after every restart");
+    });
+    faceRun("[head] one read, one generation: while an id is deleted and created again under other owners, no head pairs one generation's owner with another's occupant", ["ownership"], async (store) => {
+        const id = freshId();
+        const generations = [];
+        const reads = [];
+        const probe = () => {
+            for (let k = 0; k < 3; k++)
+                reads.push(headOf(store, id));
+        };
+        for (let i = 0; i < 12; i++) {
+            if (i > 0) {
+                probe();
+                await hooks.deleteSession(store, id);
+            }
+            probe();
+            await store.register(id, `kit-gen-${i}`);
+            probe();
+            await store.acquire(id);
+            generations.push((await headOf(store, id)));
+        }
+        const whole = new Set(generations.map((g) => `${g.owner}|${g.incarnation}`));
+        assert.equal(whole.size, generations.length, "each generation is its own owner and occupant");
+        for (const head of await Promise.all(reads)) {
+            if (head === undefined)
+                continue;
+            assert.ok(whole.has(`${head.owner}|${head.incarnation}`), `a head read ${head.owner} with occupant ${head.incarnation}, a pair no generation of the row ever held`);
+        }
+    });
+    faceRun("[ownership] register on an id with no row creates its row recording the owner — a string, or null for anonymous; a row acquire created records null", ["ownership"], async (store) => {
+        const [owned, anonymous, acquired] = [freshId(), freshId(), freshId()];
         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.acquire(acquired);
+        assert.equal(await ownerOf(store, owned, "a registered id"), "kit-alice");
+        assert.equal(await ownerOf(store, anonymous, "an anonymous registration"), null);
+        assert.equal(await ownerOf(store, acquired, "a row acquire created"), null, "acquire names no owner");
+        const token = await tokenOf(store, owned, "a registered row");
+        assert.equal((await (await readBack(store, owned)).getMetadata()).incarnation, token, "the registered row is the session acquire then hands out");
+    });
+    faceRun("[ownership] register on a row that exists does nothing, whatever it carries — an owned row, an anonymous row, a row acquire created, a placed row", ["ownership"], async (store) => {
+        const [owned, anonymous, acquired] = [freshId(), 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");
+        assert.equal(await ownerOf(store, owned, "an owned row"), "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");
+        assert.equal(await ownerOf(store, anonymous, "an anonymous row"), null, "an anonymous row is not claimable by a later register");
+        await store.acquire(acquired);
+        await store.register(acquired, "kit-carol");
+        assert.equal(await ownerOf(store, acquired, "a row acquire created"), null, "there is no claiming of a row that exists");
+        if (declaresPlacements(store)) {
+            for (const owner of [`kit-claimant-${freshId()}`, null]) {
+                const placed = freshId();
+                await store.acquire(placed, { placement: placementFor() });
+                const recorded = await ownerOf(store, placed, "a placed row");
+                await store.register(placed, owner);
+                assert.equal(await ownerOf(store, placed, "a placed row after a register"), recorded, `a register carrying ${owner === null ? "null" : "an owner"} left the placed row's owner as its placing write recorded it`);
+            }
+            const sequenced = freshId();
+            await store.acquire(sequenced, { placement: placementFor() });
+            const recordedSeq = await ownerOf(store, sequenced, "a placed row (sequence)");
+            await store.register(sequenced, null);
+            await store.register(sequenced, `kit-claimant-${freshId()}`);
+            assert.equal(await ownerOf(store, sequenced, "a placed row after two registers"), recordedSeq, "two registers in sequence (null, then a name) left the placed row's owner as its placing write recorded it");
+        }
     });
-    faceRun("[ownership] a FIRST register whose owner is neither a string nor null is refused loudly and leaves no row behind", ["ownership"], async (store) => {
+    faceRun("[ownership] a FIRST register whose owner is neither a principal name nor null is refused loudly and leaves no row behind — a blank string, or one holding a control or invisible character, names nobody", ["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 thrownBy(() => registerUntyped(store, id, ""), "a first register with the empty string as owner");
+        await thrownBy(() => registerUntyped(store, id, " \t "), "a first register with a blank string as owner");
+        await thrownBy(() => registerUntyped(store, id, "ali\u0000ce"), "a first register with a control character inside the owner");
+        await thrownBy(() => registerUntyped(store, id, "\u200b"), "a first register with an invisible character as owner");
+        assert.equal(await headOf(store, 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");
+        assert.equal(await ownerOf(store, id, "the first well-formed register"), "kit-carol", "the id is still ownable");
     });
     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);
+            return ownerOf(store, id, "after a register");
         };
         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");
+        assert.equal(await ownerOf(store, id, "the settled row"), 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] the owner is a cell of the row: it reads back after the cached view is dropped and on a store reopened over the same rows (a restart)", ["ownership"], async (store, open) => {
+        const [owned, acquired] = [freshId(), freshId()];
+        await store.register(owned, "kit-alice");
+        await append((await store.acquire(owned)).session, userEntry("e1", null));
+        await store.acquire(acquired);
+        if (typeof store.forget === "function") {
+            await store.forget(owned);
+            assert.equal(await ownerOf(store, owned, "a forgotten session"), "kit-alice", "a live session must never lose its owner with the cached view");
+        }
+        const second = await open(hooks.reopen(store));
+        assert.equal(await ownerOf(second, owned, "after a restart"), "kit-alice", "an owner an instance kept for itself is lost on every restart, and the session is then anyone's");
+        assert.equal(await ownerOf(second, acquired, "after a restart"), null);
+        await second.register(owned, "kit-bob");
+        assert.equal(await ownerOf(second, owned, "a register after a restart"), "kit-alice", "a restart opens no claiming window");
     });
-    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) => {
+    faceRun("[ownership] a fork records its owner in its own row: 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");
+        assert.equal(await ownerOf(store, (await store.fork(owned)), "a fork"), "kit-alice", "no owner argument ⇒ the source's owner");
+        assert.equal(await ownerOf(store, (await store.fork(owned, null)), "a fork"), "kit-alice", "an explicit null never downgrades a copy of an owned history to anonymous");
+        assert.equal(await ownerOf(store, (await store.fork(owned, "kit-bob")), "a fork"), "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);
+        assert.equal(await ownerOf(store, (await store.fork(anonymous)), "a fork"), null);
+        assert.equal(await ownerOf(store, (await store.fork(anonymous, null)), "a fork"), null);
+    });
+    faceRun("[ownership] an id registered first is an ordinary row: a placement-carrying acquire of it is refused placement_refused", ["ownership", "placements"], async (store) => {
+        const id = freshId();
+        await store.register(id, "kit-alice");
+        await rejectsWithCode(() => store.acquire(id, { placement: placementFor() }), "placement_refused", "a placed creation onto an id a register already created");
+        assert.equal(await ownerOf(store, id, "the registered row"), "kit-alice", "the refused acquire rewrote nothing");
+    });
+    faceRun("[ownership] acquire serves only the occupant the row holds: after another instance deleted the row and registered the id to another owner, this instance's next acquire serves the new occupant, never its cached view of the old one", ["ownership", "replica"], async (store, open) => {
+        const id = freshId();
+        const other = await open(hooks.replica(store));
+        await store.register(id, "kit-alice");
+        await append((await store.acquire(id)).session, userEntry("alice-only", null));
+        await other.acquire(id);
+        await hooks.deleteSession(other, id);
+        await other.register(id, "kit-bob");
+        const head = await headOf(store, id);
+        assert.equal(head?.owner, "kit-bob", "this instance's head reads the row");
+        const served = (await store.acquire(id)).session;
+        assert.equal((await served.getMetadata()).incarnation, head?.incarnation, "the session handed out is the row the owner was read from");
+        assert.deepEqual(await entryIds(served), [], "the previous occupant's transcript is not served under the new owner");
+    });
+    faceRun("[ownership] the metadata a session hands out is not the row: writing to it changes no owner or occupant the head answers", ["ownership"], async (store) => {
+        const id = freshId();
+        await store.register(id, "kit-alice");
+        const before = await headOf(store, id);
+        try {
+            Object.assign(await (await store.acquire(id)).session.getMetadata(), { owner: null, incarnation: "kit-forged" });
+        }
+        catch {
+        }
+        assert.deepEqual(await headOf(store, id), before, "admission changes only through a write of the row");
+    });
+    faceRun("[incarnation] a session created through acquire carries a token, and every later read of the row answers the same one", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const first = await tokenOf(store, id, "after acquire");
+        await store.acquire(id);
+        assert.equal(await tokenOf(store, id, "a re-acquire"), first, "a re-acquire reopens the same occupant");
+        await store.forget?.(id);
+        assert.equal(await tokenOf(store, id, "after forget"), first, "the token is the row's, not the cache's: forgetting the cached view must not change it");
+        await store.acquire(id, { requireExisting: true });
+        assert.equal(await tokenOf(store, id, "a require-existing reopen"), first, "a require-existing reopen after the cache forgot it is still the same occupant");
+    });
+    faceRun("[incarnation] the session acquire hands back carries the token headOf answers — a run's memory seat reads the former", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        const acquired = await store.acquire(id);
+        const byId = await tokenOf(store, id, "by-id read");
+        assert.equal((await acquired.session.getMetadata()).incarnation, byId, "two faces of one row cell must agree, or the seat and the by-id read name two occupants");
+    });
+    faceRun("[incarnation] a second store over the same rows (a restart, a replica) answers the same token — the token lives in the row, not in an instance", ["headOf", "requireExisting"], async (store, open) => {
+        const id = freshId();
+        await store.acquire(id);
+        const first = await tokenOf(store, id, "first instance");
+        const second = await open(hooks.reopen(store));
+        assert.equal(await tokenOf(second, id, "second instance"), first, "an instance-local token would name a different occupant after every restart");
+        await second.acquire(id, { requireExisting: true });
+        assert.equal(await tokenOf(second, id, "reopened on the second instance"), first, "reopening the session on the second instance is still the same occupant");
+    });
+    faceRun("[incarnation] two sessions never share a token, and an id with no session has no head (unknown — not an error, not a token)", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const generated = await store.acquire();
+        const a = await tokenOf(store, id, "explicit id");
+        const g = await tokenOf(store, generated.sessionId, "generated id");
+        assert.notEqual(a, g, "two sessions are two occupants");
+        assert.equal(await headOf(store, freshId()), undefined, "no row ⇒ unknown");
+    });
+    faceRun("[incarnation] a deleted id handed out again is a NEW occupant: a fresh token, never the previous occupant's", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const before = await tokenOf(store, id, "first occupant");
+        await hooks.deleteSession(store, id);
+        assert.equal(await headOf(store, id), undefined, "a deleted row has no occupant");
+        await store.acquire(id);
+        const after = await tokenOf(store, id, "second occupant");
+        assert.notEqual(after, before, "the id was recycled — the previous occupant's records must not bind this one");
+    });
+    faceRun("[incarnation] a fork is a new occupant: a fresh token, and the source keeps its own", ["headOf", "requireExisting", "fork"], async (store) => {
+        const src = freshId();
+        await store.acquire(src);
+        const source = await tokenOf(store, src, "fork source");
+        const forkedId = await store.fork(src);
+        assert.ok(forkedId !== null, "forking an existing session returns the fork's id");
+        assert.notEqual(await tokenOf(store, forkedId, "fork"), source, "a fork copies the history, never the occupant");
+        assert.equal(await tokenOf(store, src, "fork source after"), source, "forking does not touch the source's occupant");
     });
-    registerSessionIncarnationCases((name, fn) => faceRun(`[incarnation] ${name}`, ["incarnationOf", "requireExisting"], (store) => fn(store)), hooks);
     await settle();
 }

package/dist/core/store-contracts/workflow-journal-store-contract.js

@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, } from "../workflow-journal-store.js";
+import { JOURNAL_INCOMPATIBLE_ERROR_CODE, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, } from "../workflow-journal-store.js";
 import { beginContract } from "./contract-harness.js";
 const key = (ordinal) => `${ordinal}:h`;
 const completed = (ordinal, over = {}) => ({
@@ -22,6 +22,7 @@ const parked = (ordinal, over = {}) => ({
 });
 const OVER_CAP = "x".repeat(MAX_JOURNAL_RESULT_BYTES + 1024);
 const isOversizeRefusal = (e) => e instanceof Error && e.code === JOURNAL_OVERSIZE_ERROR_CODE;
+const isIncompatibleRefusal = (e) => e instanceof Error && e.code === JOURNAL_INCOMPATIBLE_ERROR_CODE;
 export async function workflowJournalStoreContract(make, runAssertion) {
     const { run, settle } = beginContract(runAssertion);
     run("append → load returns entries ASCENDING by ordinal, both arms verbatim; a re-append per ordinal OVERWRITES", async () => {
@@ -64,6 +65,30 @@ export async function workflowJournalStoreContract(make, runAssertion) {
         await store.append("run-1", "tenant-a", { callKey: key(1), parked: parked(1) });
         assert.equal((await store.load("run-1", "tenant-a"))[1].parked?.terminal.kind, "paused");
     });
+    run("a PARKED row whose payload is not a paused result is refused — at append, or by the whole load — never read back as an entry, never dropped", async () => {
+        const bad = [
+            ["terminal completed", { ...parked(1), terminal: { kind: "completed" } }],
+            ["paused terminal without a checkpoint token", { ...parked(1), terminal: { kind: "paused", gate: { kind: "human", reason: "approve", toolName: "Write" } } }],
+            ["parked arm a string", "paused"],
+        ];
+        for (const [what, payload] of bad) {
+            const store = make();
+            await store.append("run-1", "tenant-a", { callKey: key(0), result: completed(0) });
+            let appended = true;
+            try {
+                await store.append("run-1", "tenant-a", { callKey: key(1), parked: payload });
+            }
+            catch {
+                appended = false;
+            }
+            if (appended) {
+                await assert.rejects(store.load("run-1", "tenant-a"), isIncompatibleRefusal, `${what}: the row was journaled, so the load must refuse — with code "${JOURNAL_INCOMPATIBLE_ERROR_CODE}" — rather than answer around it`);
+            }
+            else {
+                assert.deepEqual((await store.load("run-1", "tenant-a")).map((e) => e.callKey), [key(0)], `${what}: an append that refused must have journaled nothing`);
+            }
+        }
+    });
     run("the cap is inclusive: a payload of EXACTLY the cap's byte count is accepted on both arms", async () => {
         const store = make();
         const fit = (payload) => {

package/dist/core/stub-env.d.ts

@@ -14,6 +14,8 @@ export declare class StubExecutionEnv implements ExecutionEnv {
     readonly externalContentTarget?: boolean;
     /** `ExecutionEnv.cdPath`: the stub runs no shell, so no shell receives a `CDPATH`. */
     readonly cdPath: readonly string[];
+    /** `ExecutionEnv.withheldEnv`: no shell child, so nothing is withheld from one. */
+    readonly withheldEnv: readonly [];
     constructor(cwd?: string);
     private fsErr;
     absolutePath(path: string): Promise<Result<string, FileError>>;

package/dist/core/stub-env.js

@@ -3,6 +3,7 @@ export class StubExecutionEnv {
     cwd;
     externalContentTarget;
     cdPath = [];
+    withheldEnv = [];
     constructor(cwd = "/") {
         this.cwd = cwd;
     }