@sema-agent/core 7.54.1 → 7.56.0

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

@@ -0,0 +1,130 @@
+import { strict as assert } from "node:assert";
+import { randomUUID } from "node:crypto";
+import { SESSION_RULES_GRAMMAR, SessionPolicyError, readSessionRulesShape } from "../session-policy-store.js";
+import { beginContract } from "./contract-harness.js";
+const OWNER = "kit-owner";
+const G = SESSION_RULES_GRAMMAR;
+const A = "KitToolA";
+const B = "KitToolB";
+const fresh = () => `kit-2151-${randomUUID()}`;
+const isLoosenRefusal = (e) => e instanceof SessionPolicyError && e.code === "loosen_forbidden";
+async function partOf(store, sessionId) {
+    const row = await store.getRules(sessionId, OWNER);
+    assert.ok(row !== null, "the row the case wrote must read back");
+    const read = readSessionRulesShape(row);
+    assert.ok(!("fault" in read), `the stored row must read as rules: ${"fault" in read ? read.sentence : ""}`);
+    return read.rules.operatorRules;
+}
+export async function sessionPolicyStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("a non-operator write over no row stamps an EMPTY operator part — the owner takes its own deny back", async () => {
+        const store = make();
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { toolDeny: [A] });
+        assert.deepEqual(await partOf(store, sid), { grammar: G });
+        const back = await store.putRules(sid, OWNER, {});
+        assert.equal(back.toolDeny, undefined);
+        assert.deepEqual(await partOf(store, sid), { grammar: G });
+    });
+    run("an operator write's whole value is the operator's: no part on the row, and the owner's drop of its entry is refused with nothing written", async () => {
+        const store = make();
+        const sid = fresh();
+        const stored = await store.putRules(sid, OWNER, { toolDeny: [A] }, { operator: true });
+        assert.equal(await partOf(store, sid), undefined);
+        await assert.rejects(store.putRules(sid, OWNER, {}), isLoosenRefusal);
+        const row = await store.getRules(sid, OWNER);
+        assert.equal(row?.rev, stored.rev);
+        assert.deepEqual(row?.toolDeny, [A]);
+    });
+    run("an owner write over an operator row carries the operator's buckets as its part — above them it adds and takes back, below them it is refused", async () => {
+        const store = make();
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { toolDeny: [A] }, { operator: true });
+        await store.putRules(sid, OWNER, { toolDeny: [A, B] });
+        assert.deepEqual(await partOf(store, sid), { toolDeny: [A], grammar: G });
+        await store.putRules(sid, OWNER, { toolDeny: [A] });
+        assert.deepEqual((await store.getRules(sid, OWNER))?.toolDeny, [A]);
+        await assert.rejects(store.putRules(sid, OWNER, {}), isLoosenRefusal);
+        assert.deepEqual(await partOf(store, sid), { toolDeny: [A], grammar: G });
+    });
+    run("the same entry from both writers: once an operator write carries it, the owner's drop is refused", async () => {
+        const store = make();
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { toolDeny: [A] });
+        await store.putRules(sid, OWNER, { toolDeny: [A] }, { operator: true });
+        await assert.rejects(store.putRules(sid, OWNER, {}), isLoosenRefusal);
+        assert.deepEqual((await store.getRules(sid, OWNER))?.toolDeny, [A]);
+    });
+    run("a part handed in with the value is no authority: the stored part is the judge's", async () => {
+        const store = make();
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { toolDeny: [A] }, { operator: true });
+        const forged = { toolDeny: [A, B], operatorRules: { grammar: G } };
+        await store.putRules(sid, OWNER, forged);
+        assert.deepEqual(await partOf(store, sid), { toolDeny: [A], grammar: G });
+        await assert.rejects(store.putRules(sid, OWNER, {}), isLoosenRefusal);
+    });
+    run("allowDirs: the owner's own confinement is the owner's to remove; an operator's is not", async () => {
+        const store = make();
+        const own = fresh();
+        await store.putRules(own, OWNER, { allowDirs: ["/work/src"] });
+        await store.putRules(own, OWNER, {});
+        assert.equal((await store.getRules(own, OWNER))?.allowDirs, undefined);
+        const operators = fresh();
+        await store.putRules(operators, OWNER, { allowDirs: ["/work"] }, { operator: true });
+        await store.putRules(operators, OWNER, { allowDirs: ["/work/src"] });
+        await store.putRules(operators, OWNER, { allowDirs: ["/work"] });
+        await assert.rejects(store.putRules(operators, OWNER, {}), isLoosenRefusal);
+        assert.deepEqual((await store.getRules(operators, OWNER))?.allowDirs, ["/work"]);
+    });
+    run("a stored row replayed by a non-operator onto a fresh or erased key keeps who may take what back (an import's replay)", async () => {
+        const store = make();
+        const exported = async (sid) => {
+            const records = store.listBySession !== undefined ? await store.listBySession(sid) : [{ principal: OWNER, rules: (await store.getRules(sid, OWNER)) }];
+            assert.equal(records.length, 1);
+            return records[0].rules;
+        };
+        const opSid = fresh();
+        await store.putRules(opSid, OWNER, { toolDeny: [A] }, { operator: true });
+        const opRow = await exported(opSid);
+        const replayed = fresh();
+        await store.putRules(replayed, OWNER, opRow);
+        await assert.rejects(store.putRules(replayed, OWNER, {}), isLoosenRefusal);
+        const mixedSid = fresh();
+        await store.putRules(mixedSid, OWNER, { toolDeny: [A] }, { operator: true });
+        await store.putRules(mixedSid, OWNER, { toolDeny: [A, B] });
+        const mixed = await exported(mixedSid);
+        const target = fresh();
+        await store.putRules(target, OWNER, mixed);
+        assert.deepEqual(await partOf(store, target), { toolDeny: [A], grammar: G });
+        await store.putRules(target, OWNER, { toolDeny: [A] });
+        await assert.rejects(store.putRules(target, OWNER, {}), isLoosenRefusal);
+        if (store.deleteBySession !== undefined) {
+            await store.deleteBySession(replayed);
+            await store.putRules(replayed, OWNER, opRow);
+            await assert.rejects(store.putRules(replayed, OWNER, {}), isLoosenRefusal);
+        }
+    });
+    run("a value built on the no-row record (`{ rev: 0 }`, what a read of an unwritten key answers) is written now: the owner takes back what it added through it", async () => {
+        const store = make();
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { rev: 0, toolDeny: [A] });
+        assert.deepEqual(await partOf(store, sid), { grammar: G });
+        const back = await store.putRules(sid, OWNER, {});
+        assert.equal(back.toolDeny, undefined);
+    });
+    run("the part rides the session's enumeration (an export carries who may take what back)", async () => {
+        const store = make();
+        if (store.listBySession === undefined)
+            return;
+        const sid = fresh();
+        await store.putRules(sid, OWNER, { toolDeny: [A] }, { operator: true });
+        await store.putRules(sid, OWNER, { toolDeny: [A, B] });
+        const records = await store.listBySession(sid);
+        assert.equal(records.length, 1);
+        const read = readSessionRulesShape(records[0].rules);
+        assert.ok(!("fault" in read));
+        assert.deepEqual(read.rules.operatorRules, { toolDeny: [A], grammar: G });
+    });
+    await settle();
+}

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

@@ -1,4 +1,5 @@
 import { strict as assert } from "node:assert";
+import { TtlSessionStore } from "../session-store.js";
 import { beginContract } from "./contract-harness.js";
 const SESSION_ENTRY = (id, parentId) => ({
     id,
@@ -72,5 +73,180 @@ export async function sessionRepoContract(make, runAssertion) {
         assert.deepEqual(after.map((e) => e.parentId), [null, "e1"]);
         assert.equal((await repo.exportEntries(A)).length, 2, "importing into C must not disturb the donor session");
     });
+    run("list answers each row once, with its owner cell; a row's lastActiveAt, where the repo records it, is a finite time that a later write or touch never moves back", async () => {
+        const repo = make();
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        await (await repo.create({ id: A, owner: "kit-alice" })).getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await (await repo.create({ id: B })).getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        let rows = await repo.list();
+        for (const id of [A, B])
+            assert.equal(rows.filter((r) => r.id === id).length, 1, `row ${id} is listed once`);
+        const rowA = rows.find((r) => r.id === A);
+        const rowB = rows.find((r) => r.id === B);
+        assert.equal(rowA.owner ?? null, "kit-alice", "a listed row carries its owner cell");
+        assert.equal(rowB.owner ?? null, null);
+        const timeOf = (id) => {
+            const row = rows.find((r) => r.id === id);
+            return row.lastActiveAt ?? Date.parse(row.createdAt);
+        };
+        if (rowA.lastActiveAt !== undefined && rowB.lastActiveAt !== undefined) {
+            assert.ok(Number.isFinite(rowA.lastActiveAt) && Number.isFinite(rowB.lastActiveAt), "a recorded activity time is a finite epoch-ms number");
+            assert.ok(rowB.lastActiveAt >= rowA.lastActiveAt, "the row written later is not listed as older");
+            const before = rowA.lastActiveAt;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            await (await repo.open({ id: A, createdAt: "" })).getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+            rows = await repo.list();
+            assert.ok(timeOf(A) >= before && timeOf(A) >= rowB.lastActiveAt, "a write moves its row's time forward, past the rows written before it");
+        }
+        if (repo.touch === undefined)
+            return;
+        const latest = Math.max(timeOf(A), timeOf(B));
+        const older = timeOf(A) <= timeOf(B) ? A : B;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await repo.touch(older);
+        rows = await repo.list();
+        const touched = rows.find((r) => r.id === older).lastActiveAt;
+        assert.ok(touched !== undefined && Number.isFinite(touched), "a touched row lists a recorded time");
+        assert.ok(touched >= latest, "a touch moves its row's time forward, past the rows active before it");
+        await repo.touch("0198fa00-0000-7000-8000-0000000000ff");
+    });
+    run("the owner cell round-trips: create({id, owner}) records it and open() reads it back; a create naming no owner records null", async () => {
+        const repo = make();
+        const owned = await repo.create({ id: A, owner: "kit-alice" });
+        assert.equal((await owned.getMetadata()).owner, "kit-alice");
+        assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-alice", "the owner is in the row, not in the handle");
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        await repo.create({ id: B });
+        assert.equal((await (await repo.open({ id: B, createdAt: "" })).getMetadata()).owner ?? null, null, "no owner named ⇒ anonymous");
+    });
+    run("a create or fork whose owner is no principal name (the empty string, a blank string, a string holding a control or invisible character) is refused and leaves no row", async () => {
+        const repo = make();
+        for (const owner of ["", " \t ", "ali\u0000ce", "\u200b"])
+            await assert.rejects(() => repo.create({ id: A, owner }), `create with owner ${JSON.stringify(owner)}`);
+        await assert.rejects(() => repo.open({ id: A, createdAt: "" }), "the refused creates stored nothing");
+        const src = await repo.create({ id: A, owner: "kit-alice" });
+        await src.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        for (const owner of ["", " \t ", "ali\u0000ce", "\u200b"])
+            await assert.rejects(() => repo.fork({ id: A, createdAt: "" }, { id: B, owner }), `fork with owner ${JSON.stringify(owner)}`);
+        await assert.rejects(() => repo.open({ id: B, createdAt: "" }), "the refused forks stored nothing");
+        assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-alice", "the source row is untouched");
+    });
+    run("create({id, owner: Y}) onto an existing row owned by X reopens it untouched: the row keeps X, and the session it returns carries X", async () => {
+        const repo = make();
+        const first = await repo.create({ id: A, owner: "kit-x" });
+        const token = (await first.getMetadata()).incarnation;
+        const again = await repo.create({ id: A, owner: "kit-y" });
+        assert.equal((await again.getMetadata()).owner, "kit-x", "a caller whose create met an existing row reads that row's owner, never its own");
+        assert.equal((await again.getMetadata()).incarnation, token, "and the same occupant");
+        assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-x");
+    });
+    run("fork records the owner its options name in the fork row, else (absent or null) the source row's; importEntries onto an existing row keeps its metadata whole, onto an absent id records the importer", async () => {
+        const repo = make();
+        const src = await repo.create({ id: A, owner: "kit-alice" });
+        await src.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        const C = "0198fa00-0000-7000-8000-00000000000c";
+        const D = "0198fa00-0000-7000-8000-00000000000d";
+        assert.equal((await (await repo.fork({ id: A, createdAt: "" }, { id: B, owner: "kit-bob" })).getMetadata()).owner, "kit-bob");
+        assert.equal((await (await repo.fork({ id: A, createdAt: "" }, { id: C })).getMetadata()).owner, "kit-alice", "a fork whose options name no owner records the source row's — a copy of an owned history is never anonymous");
+        assert.equal((await (await repo.fork({ id: A, createdAt: "" }, { id: D, owner: null })).getMetadata()).owner, "kit-alice", "an explicit null never downgrades the copy either");
+        if (repo.importEntries === undefined)
+            return;
+        const token = (await src.getMetadata()).incarnation;
+        await repo.importEntries(A, "kit-carol", [SESSION_ENTRY("e1", null)]);
+        const imported = await (await repo.open({ id: A, createdAt: "" })).getMetadata();
+        assert.equal(imported.owner, "kit-alice", "the owner is recorded only by the write that creates the row: an import never re-stamps it");
+        assert.equal(imported.incarnation, token, "the log is replaced, not the occupant");
+        await repo.importEntries(A, undefined, []);
+        assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-alice", "an import with no principal never makes an owned row anonymous");
+        const cells = (m) => [m.createdAt, m.forkedFrom, m.forkedFromIncarnation, m.incarnation, m.owner, JSON.stringify(m.placement)];
+        const forkRow = await (await repo.open({ id: B, createdAt: "" })).getMetadata();
+        await repo.importEntries(B, "kit-carol", [SESSION_ENTRY("e1", null)]);
+        assert.deepEqual(cells(await (await repo.open({ id: B, createdAt: "" })).getMetadata()), cells(forkRow), "the log is replaced, never the row: a fork row keeps its creation time and its lineage");
+        const E = "0198fa00-0000-7000-8000-00000000000e";
+        await repo.importEntries(E, "kit-carol", [SESSION_ENTRY("e1", null)]);
+        assert.equal((await (await repo.open({ id: E, createdAt: "" })).getMetadata()).owner, "kit-carol", "an import onto an absent id is a new row of the importer");
+    });
+    run("the metadata a repo hands out is not the row: writing to it (from open() or list()) changes no identity cell the row answers", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A, owner: "kit-alice" });
+        const token = (await sess.getMetadata()).incarnation;
+        for (const meta of [await sess.getMetadata(), await (await repo.open({ id: A, createdAt: "" })).getMetadata(), ...(await repo.list()).filter((m) => m.id === A)]) {
+            try {
+                Object.assign(meta, { owner: "kit-mallory", incarnation: "kit-forged" });
+            }
+            catch {
+            }
+        }
+        const again = await (await repo.open({ id: A, createdAt: "" })).getMetadata();
+        assert.equal(again.owner, "kit-alice", "the owner changes only through a write of the row");
+        assert.equal(again.incarnation, token);
+        if (repo.headOf !== undefined)
+            assert.deepEqual(await repo.headOf(A), { owner: "kit-alice", incarnation: token, leafId: null });
+    });
+    run("headOf (where the repo answers it): no row ⇒ undefined; a row ⇒ its owner, occupant and active leaf, as open() reads them", async () => {
+        const repo = make();
+        if (repo.headOf === undefined)
+            return;
+        assert.equal(await repo.headOf(A), undefined);
+        const sess = await repo.create({ id: A, owner: "kit-alice" });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+        await sess.getStorage().setLeafId("e1");
+        const opened = await repo.open({ id: A, createdAt: "" });
+        assert.deepEqual(await repo.headOf(A), { owner: "kit-alice", incarnation: (await opened.getMetadata()).incarnation, leafId: await opened.getStorage().getLeafId() });
+        await repo.delete({ id: A, createdAt: "" });
+        assert.equal(await repo.headOf(A), undefined, "a deleted row has no head");
+    });
+    run("the store over a repo: a row replaced behind a cached session (deleted, then created again naming another owner) — the store's next acquire serves the new row, never the cached transcript", async () => {
+        const repo = make();
+        const store = new TtlSessionStore({ repo });
+        try {
+            if (store.headOf === undefined)
+                return;
+            await store.register(A, "kit-alice");
+            await (await store.acquire(A)).session.getStorage().appendEntry(SESSION_ENTRY("alice-only", null));
+            await repo.delete({ id: A, createdAt: "" });
+            await repo.create({ id: A, owner: "kit-bob" });
+            const served = (await store.acquire(A)).session;
+            assert.equal((await served.getMetadata()).owner, "kit-bob", "the session handed out is the row the owner is read from");
+            assert.deepEqual((await served.getStorage().getEntries()).map((e) => e.id), [], "the previous owner's transcript is not served under the new owner");
+        }
+        finally {
+            store.dispose();
+        }
+    });
+    run("the store over a repo answers headOf exactly when the repo does: present ⇒ the repo's own answer; absent ⇒ no headOf on the store, which still works", async () => {
+        const repo = make();
+        const store = new TtlSessionStore({ repo });
+        try {
+            assert.equal(typeof store.headOf, typeof repo.headOf === "function" ? "function" : "undefined");
+            const { sessionId } = await store.acquire(A);
+            if (store.headOf !== undefined)
+                assert.deepEqual(await store.headOf(sessionId), await repo.headOf(sessionId), "the store's head is the repo's, verbatim");
+        }
+        finally {
+            store.dispose();
+        }
+        const bare = {
+            create: (o) => repo.create(o),
+            open: (m) => repo.open(m),
+            list: () => repo.list(),
+            delete: (m) => repo.delete(m),
+            fork: (s, o) => repo.fork(s, o),
+        };
+        const over = new TtlSessionStore({ repo: bare });
+        try {
+            assert.equal(over.headOf, undefined, "no head read on the repo ⇒ none on the store (an authorizer takes its fail-closed arm)");
+            const B = "0198fa00-0000-7000-8000-00000000000b";
+            await over.acquire(B);
+            await over.register(B, "kit-alice");
+        }
+        finally {
+            over.dispose();
+        }
+    });
     await settle();
 }

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

@@ -1,6 +1,5 @@
 import { type SessionStore } from "../session.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
-import { type SessionStoreIncarnationContractHooks } from "./session-store-incarnation-contract.js";
 /**
  * The cross-backend contract for {@link SessionStore} as the interface states it TODAY — what a store must
  * do so that the engine, a deployment's authorizer and a shell read the same answers off it whether the
@@ -18,15 +17,14 @@ import { type SessionStoreIncarnationContractHooks } from "./session-store-incar
  * What the kit cannot see from outside, it does not claim: idle eviction and `pin` (the interface has no
  * clock seam), what `release` does to an ordinary session's live set (`size` is best-effort and a durable
  * `list` may still show the history), a durable backend's crash recovery, and a delete that fails half-way.
- * One stated obligation is not a case yet because the bundled store does not keep it: an ownership row
- * outliving its session across a restart (`TtlSessionStore` holds owners in process memory).
  *
- * Semantics since @sema-agent/core 7.55.0.
+ * Semantics since @sema-agent/core 7.56.0: the list reads the store's rows (a reopened store lists them), pages by the
+ * `(lastActiveAt, sessionId)` keyset, filters by the row's owner, and refuses a bad query through `readSessionListQuery`.
  */
 export interface SessionStoreContractHooks {
-    /** The same hook as the incarnation kit's ({@link SessionStoreIncarnationContractHooks.deleteSession}): one
-     *  function serves both kits. */
-    deleteSession: SessionStoreIncarnationContractHooks["deleteSession"];
+    /** Delete `sessionId`'s session ROW through the backend's own deletion path (history and all), so that a later
+     *  `acquire(sessionId)` creates a new session under the same id. */
+    deleteSession: (store: SessionStore, sessionId: string) => Promise<void>;
     /** A SECOND, independent store instance over the same rows as `store` — what a restarted process
      *  constructs. After calling it the kit no longer uses `store`, so a backend that holds an exclusive lock
      *  may release `store`'s first (the kit still disposes `store` at the end of the case: that dispose must
@@ -40,7 +38,7 @@ export interface SessionStoreContractHooks {
     /** Optional faces (plus the replica hook, and `requireExisting` — absent = the store rejects the option, its other
      *  legal mode) a run verified or found absent; reported per judging case, after its assertions held. */
     onOptionalMember?: (report: {
-        member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "ownership" | "incarnationOf" | "replica";
+        member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "headOf" | "ownership" | "replica";
         status: "verified" | "absent";
     }) => void;
 }