@sema-agent/core/dist/core/store-contracts/peer-directory-contract.js

Stateless, task-oriented AI agent core

import { strict as assert } from "node:assert";
import { resolvePeerSessions } from "../../agents/peer-directory.js";
import { beginContract } from "./contract-harness.js";
export const PEER_DIRECTORY_CONTRACT_SCOPE = "peer-kit-A";
function row(name, sessionId, over = {}) {
    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", ...over };
}
async function withDirs(mk, fn) {
    const live = [];
    const make = () => {
        const d = mk();
        live.push(d);
        return d;
    };
    try {
        await fn(make);
    }
    finally {
        for (const d of live.splice(0))
            d.close?.();
    }
}
export async function peerDirectoryContract(mk, hooks) {
    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
    const run = (name, fn) => runRaw(name, () => withDirs(mk, fn));
    const S = PEER_DIRECTORY_CONTRACT_SCOPE;
    run("scope wall: a listing is the accessor's scope only", async (make) => {
        const d = make();
        await hooks.write(d, row("alpha", "sess-a"));
        await hooks.write(d, row("beta", "sess-b", { scope: "peer-kit-B" }));
        const inA = await d.listPeerSessions({ scope: S });
        assert.deepEqual(inA.map((r) => r.sessionId), ["sess-a"], "scope A must list exactly its own row");
        const inB = await d.listPeerSessions({ scope: "peer-kit-B" });
        assert.deepEqual(inB.map((r) => r.sessionId), ["sess-b"]);
        const inC = await d.listPeerSessions({ scope: "peer-kit-C" });
        assert.equal(inC.length, 0, "an unrelated scope sees nothing");
    });
    run("the full set is listed (live + dead + deleted) and every listed row is a copy", async (make) => {
        const d = make();
        await hooks.write(d, row("alpha", "sess-a"));
        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
        const listed = await d.listPeerSessions({ scope: S });
        assert.deepEqual([...listed.map((r) => r.sessionId)].sort(), ["sess-a", "sess-b", "sess-c"], "dead and deleted rows are MARKED, never dropped from a listing");
        assert.deepEqual(Object.fromEntries(listed.map((r) => [r.sessionId, r.liveness])), { "sess-a": "live", "sess-b": "dead", "sess-c": "deleted" });
        const first = listed.find((r) => r.sessionId === "sess-a");
        first.name = "scribbled";
        const again = await d.listPeerSessions({ scope: S });
        assert.equal(again.find((r) => r.sessionId === "sess-a").name, "alpha", "a listed row is a copy");
    });
    run("the engine's resolver over the listing: live by name, dead still found, deleted refuses", async (make) => {
        const d = make();
        await hooks.write(d, row("alpha", "sess-a"));
        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
        const rows = await d.listPeerSessions({ scope: S });
        const alpha = resolvePeerSessions(rows, "alpha");
        assert.equal(alpha.status, "found");
        const beta = resolvePeerSessions(rows, "beta");
        assert.equal(beta.status, "found", "a dead row is the name truth offline delivery resolves through");
        const gamma = resolvePeerSessions(rows, "gamma");
        assert.equal(gamma.status, "deleted", "a tombstone resolves only to refuse");
        assert.equal(resolvePeerSessions(rows, "session.sess-b").status, "found", "an address resolves to a KNOWN row");
        assert.equal(resolvePeerSessions(rows, "session.sess-zzz").status, "not_found", "an address nobody registered is not an append target");
    });
    run("restorePeerSession (where implemented) is CAS-on-absent: restores an absent row, never overwrites a present one", async (make) => {
        const d = make();
        if (d.restorePeerSession === undefined)
            return;
        const restored = await d.restorePeerSession(row("alpha", "sess-a", { liveness: "dead", diedAt: 3_000 }));
        assert.equal(restored, true, "an absent row is restored");
        assert.deepEqual((await d.listPeerSessions({ scope: S })).map((r) => r.sessionId), ["sess-a"]);
        await hooks.write(d, row("alpha", "sess-a", { updatedAt: 9_000 }));
        const again = await d.restorePeerSession(row("alpha-stale", "sess-a", { liveness: "dead", diedAt: 3_000 }));
        assert.equal(again, false, "a present row wins over a restore");
        const current = (await d.listPeerSessions({ scope: S })).find((r) => r.sessionId === "sess-a");
        assert.equal(current.name, "alpha");
        assert.equal(current.liveness, "live");
        assert.equal(current.updatedAt, 9_000, "the existing row is byte-unchanged by a losing restore");
    });
    await settle();
}