@sema-agent/core/dist/core/store-contracts/session-store-incarnation-contract.js

Stateless, task-oriented AI agent core

import { strict as assert } from "node:assert";
import { hasSessionFork } from "../session.js";
import { beginContract } from "./contract-harness.js";
const ID_A = "0198fa00-0000-7000-8000-0000000014a1";
const ID_B = "0198fa00-0000-7000-8000-0000000014b2";
const ID_NONE = "0198fa00-0000-7000-8000-0000000014ff";
async function tokenOf(store, sessionId) {
    assert.equal(typeof store.incarnationOf, "function", "this kit is for stores that implement SessionStore.incarnationOf");
    return store.incarnationOf(sessionId);
}
function assertToken(token, what) {
    assert.equal(typeof token, "string", `${what}: a session row created through this store must carry an incarnation`);
    assert.notEqual(token, "", `${what}: an empty token names nobody`);
}
export async function sessionStoreIncarnationContract(make, hooks) {
    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
    const run = (name, fn) => runRaw(name, async () => {
        const store = make();
        try {
            await fn(store);
        }
        finally {
            await store.dispose();
        }
    });
    run("a session created through acquire carries a token, and every later read of the row answers the same one", async (store) => {
        await store.acquire(ID_A);
        const first = await tokenOf(store, ID_A);
        assertToken(first, "after acquire");
        await store.acquire(ID_A);
        assert.equal(await tokenOf(store, ID_A), first, "a re-acquire reopens the same occupant");
        await store.forget?.(ID_A);
        assert.equal(await tokenOf(store, ID_A), first, "the token is the row's, not the cache's: forgetting the cached view must not change it");
        await store.acquire(ID_A, { requireExisting: true });
        assert.equal(await tokenOf(store, ID_A), first, "a require-existing reopen after the cache forgot it is still the same occupant");
    });
    run("the session acquire hands back carries the token incarnationOf answers — a run's memory seat reads the former", async (store) => {
        const acquired = await store.acquire(ID_A);
        const byId = await tokenOf(store, ID_A);
        assertToken(byId, "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");
    });
    run("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", async (store) => {
        await store.acquire(ID_A);
        const first = await tokenOf(store, ID_A);
        assertToken(first, "first instance");
        const second = hooks.reopen(store);
        try {
            assert.equal(await tokenOf(second, ID_A), first, "an instance-local token would name a different occupant after every restart");
            await second.acquire(ID_A, { requireExisting: true });
            assert.equal(await tokenOf(second, ID_A), first, "reopening the session on the second instance is still the same occupant");
        }
        finally {
            await second.dispose();
        }
    });
    run("two sessions never share a token, and an id with no session answers undefined (unknown — not an error, not a token)", async (store) => {
        await store.acquire(ID_A);
        const generated = await store.acquire();
        const a = await tokenOf(store, ID_A);
        const g = await tokenOf(store, generated.sessionId);
        assertToken(a, "explicit id");
        assertToken(g, "generated id");
        assert.notEqual(a, g, "two sessions are two occupants");
        assert.equal(await tokenOf(store, ID_NONE), undefined, "no row ⇒ unknown");
    });
    run("a deleted id handed out again is a NEW occupant: a fresh token, never the previous occupant's", async (store) => {
        await store.acquire(ID_A);
        const before = await tokenOf(store, ID_A);
        assertToken(before, "first occupant");
        await hooks.deleteSession(store, ID_A);
        assert.equal(await tokenOf(store, ID_A), undefined, "a deleted row has no occupant");
        await store.acquire(ID_A);
        const after = await tokenOf(store, ID_A);
        assertToken(after, "second occupant");
        assert.notEqual(after, before, "the id was recycled — the previous occupant's records must not bind this one");
    });
    run("a fork is a new occupant: a fresh token, and the source keeps its own", async (store) => {
        if (!hasSessionFork(store))
            return;
        await store.acquire(ID_B);
        const source = await tokenOf(store, ID_B);
        assertToken(source, "fork source");
        const forkedId = await store.fork(ID_B);
        assert.ok(forkedId !== null, "forking an existing session returns the fork's id");
        const forked = await tokenOf(store, forkedId);
        assertToken(forked, "fork");
        assert.notEqual(forked, source, "a fork copies the history, never the occupant");
        assert.equal(await tokenOf(store, ID_B), source, "forking does not touch the source's occupant");
    });
    await settle();
}