@retinue/agentkit 0.1.0 → 0.3.0

package/dist/testing/conformance/session-state.js

@@ -0,0 +1,198 @@
+/**
+ * `SessionStateStore`, `ConversationBindingStore`, `ThreadSummaryStore` and `UnitOfWork`
+ * conformance — `docs/13-sessions-and-threads.md`.
+ *
+ * Session state is the deliberate replacement for Agno's fixed 20-turn re-injection (see the
+ * extraction inventory), so its optimistic concurrency and size ceiling are load-bearing: they are
+ * what stop two runs on one conversation from clobbering each other and what keep working memory
+ * from growing into a document store.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { gatedIt } from "./capability.js";
+import { withConversation } from "./parents.js";
+const T1 = asId("conf-tenant-1");
+const T2 = asId("conf-tenant-2");
+const C1 = asId("conf-convo-1");
+const AGENT = asId("conf-agent-1");
+const MSG = asId("conf-msg-1");
+export function sessionStateStoreConformance(makeFixture, options = {}) {
+    // Session state references a conversation, and Postgres enforces it with a foreign key (#97).
+    const open = () => withConversation(makeFixture(), [{ tenantId: T1, conversationId: C1 }]);
+    describe("SessionStateStore conformance", () => {
+        it("returns null before anything is written", async () => {
+            const store = await open();
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toBeNull();
+        });
+        it("writes at expectedVersion 0 and reads back version 1", async () => {
+            const store = await open();
+            const put = await store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { a: 1 } });
+            expect(put).toMatchObject({ version: 1, data: { a: 1 } });
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toMatchObject({ version: 1 });
+        });
+        it("increments the version on each write", async () => {
+            const store = await open();
+            await store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { n: 1 } });
+            const second = await store.put({ tenantId: T1, conversationId: C1, expectedVersion: 1, data: { n: 2 } });
+            expect(second.version).toBe(2);
+        });
+        it("rejects a stale expectedVersion, so concurrent runs cannot clobber each other", async () => {
+            const store = await open();
+            await store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { n: 1 } });
+            await expect(store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { n: 99 } })).rejects.toThrow();
+            expect((await store.get({ tenantId: T1, conversationId: C1 }))?.data).toEqual({ n: 1 });
+        });
+        it("rejects a write beyond the size ceiling — working memory, not a document store", async () => {
+            const store = await open();
+            const maxBytes = options.maxBytes ?? 64 * 1024;
+            const oversized = { blob: "x".repeat(maxBytes + 1_000) };
+            await expect(store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: oversized })).rejects.toThrow();
+        });
+        it("enforces tenant isolation", async () => {
+            const store = await open();
+            await store.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { a: 1 } });
+            expect(await store.get({ tenantId: T2, conversationId: C1 })).toBeNull();
+        });
+    });
+}
+export function conversationBindingStoreConformance(makeFixture) {
+    // A binding belongs to a conversation, and Postgres enforces that with a foreign key (#96). The
+    // in-memory adapter has no such constraint and passes no seeder — see ./parents.ts.
+    const open = () => withConversation(makeFixture(), [{ tenantId: T1, conversationId: C1 }]);
+    describe("ConversationBindingStore conformance", () => {
+        it("returns null for an unbound conversation rather than a default", async () => {
+            const store = await open();
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toBeNull();
+        });
+        it("round-trips a pinned binding including the version", async () => {
+            const store = await open();
+            await store.bind({
+                tenantId: T1,
+                conversationId: C1,
+                agentId: AGENT,
+                agentVersionPolicy: "pinned",
+                agentVersion: 3,
+            });
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toMatchObject({
+                agentId: AGENT,
+                agentVersionPolicy: "pinned",
+                agentVersion: 3,
+            });
+        });
+        it("round-trips a latest-policy binding", async () => {
+            const store = await open();
+            await store.bind({ tenantId: T1, conversationId: C1, agentId: AGENT, agentVersionPolicy: "latest" });
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toMatchObject({
+                agentVersionPolicy: "latest",
+            });
+        });
+        it("re-binding is idempotent — the last write wins, without error", async () => {
+            const store = await open();
+            await store.bind({ tenantId: T1, conversationId: C1, agentId: AGENT, agentVersionPolicy: "latest" });
+            await store.bind({
+                tenantId: T1,
+                conversationId: C1,
+                agentId: AGENT,
+                agentVersionPolicy: "pinned",
+                agentVersion: 2,
+            });
+            expect(await store.get({ tenantId: T1, conversationId: C1 })).toMatchObject({ agentVersion: 2 });
+        });
+        it("enforces tenant isolation", async () => {
+            const store = await open();
+            await store.bind({ tenantId: T1, conversationId: C1, agentId: AGENT, agentVersionPolicy: "latest" });
+            expect(await store.get({ tenantId: T2, conversationId: C1 })).toBeNull();
+        });
+    });
+}
+export function threadSummaryStoreConformance(makeFixture) {
+    // Same foreign key as session state (#97).
+    const open = () => withConversation(makeFixture(), [{ tenantId: T1, conversationId: C1 }]);
+    describe("ThreadSummaryStore conformance", () => {
+        it("returns null before any summary exists", async () => {
+            const store = await open();
+            expect(await store.latest({ tenantId: T1, conversationId: C1 })).toBeNull();
+        });
+        it("appends version 1 first", async () => {
+            const store = await open();
+            const s = await store.append({
+                tenantId: T1,
+                conversationId: C1,
+                summary: "first",
+                coversUpToMessageId: MSG,
+            });
+            expect(s).toMatchObject({ version: 1, summary: "first" });
+        });
+        it("versions successive summaries rather than overwriting", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, conversationId: C1, summary: "first", coversUpToMessageId: MSG });
+            const second = await store.append({
+                tenantId: T1,
+                conversationId: C1,
+                summary: "second",
+                coversUpToMessageId: MSG,
+            });
+            expect(second.version).toBe(2);
+            expect((await store.latest({ tenantId: T1, conversationId: C1 }))?.summary).toBe("second");
+        });
+        it("records how far the summary covers, so recent turns stay verbatim", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, conversationId: C1, summary: "s", coversUpToMessageId: MSG });
+            expect((await store.latest({ tenantId: T1, conversationId: C1 }))?.coversUpToMessageId).toBe(MSG);
+        });
+        it("enforces tenant isolation", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, conversationId: C1, summary: "s", coversUpToMessageId: MSG });
+            expect(await store.latest({ tenantId: T2, conversationId: C1 })).toBeNull();
+        });
+    });
+}
+export function unitOfWorkConformance(makeFixture, declaration) {
+    /** A fresh backend per test, with its parent row seeded — so no case depends on another's order. */
+    const open = async () => {
+        const fixture = makeFixture();
+        // Committed before any transaction opens, so a rolled-back unit does not take the parent with it.
+        await fixture.seedConversation?.({ tenantId: T1, conversationId: C1 });
+        return fixture;
+    };
+    describe("UnitOfWork conformance", () => {
+        it("returns the callback's value on success", async () => {
+            const { unitOfWork } = await open();
+            expect(await unitOfWork.run(async () => 42)).toBe(42);
+        });
+        it("propagates the callback's error", async () => {
+            const { unitOfWork } = await open();
+            await expect(unitOfWork.run(async () => {
+                throw new Error("boom");
+            })).rejects.toThrow("boom");
+        });
+        /**
+         * Gated on `transactions` deliberately, and this gate documents a real divergence rather than
+         * hiding one. An adapter backed by a database transaction rolls a store write back with no
+         * cooperation from the caller. The in-memory reference adapter instead offers compensations via
+         * its own `runTx(tx => tx.onRollback(...))`, which the bare port cannot express — so through
+         * `run()` alone it rolls back nothing. Callers that rely on automatic rollback are therefore
+         * only portable to adapters declaring `transactions`. See the PR discussion on #91.
+         *
+         * As of #98 Postgres is the first adapter for which this gate opens, so the case finally runs
+         * somewhere instead of standing down everywhere — which is what AC-5 of #98 is really about.
+         */
+        gatedIt(declaration, "transactions", "leaves no partial write behind when the unit fails", async () => {
+            const { unitOfWork, sessions } = await open();
+            await expect(unitOfWork.run(async () => {
+                await sessions.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { staged: true } });
+                throw new Error("fail after the write");
+            })).rejects.toThrow("fail after the write");
+            // The all-or-nothing guarantee: usage and session state commit together or not at all.
+            expect(await sessions.get({ tenantId: T1, conversationId: C1 })).toBeNull();
+        });
+        it("commits the write when the unit succeeds", async () => {
+            const { unitOfWork, sessions } = await open();
+            await unitOfWork.run(async () => {
+                await sessions.put({ tenantId: T1, conversationId: C1, expectedVersion: 0, data: { committed: true } });
+            });
+            expect((await sessions.get({ tenantId: T1, conversationId: C1 }))?.data).toEqual({ committed: true });
+        });
+    });
+}
+//# sourceMappingURL=session-state.js.map

package/dist/testing/conformance/usage-limits.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `UsageLimitStore` conformance — admin-configured spend limits (#175).
+ *
+ * The rule under test is **most specific wins, as a fallback and never a merge**. That distinction is the whole
+ * reason this harness exists: an adapter that merged a principal's cost limit with the tenant's token limit would
+ * produce a third set of limits nobody configured, and every individual assertion about either would still pass.
+ */
+import type { UsageLimitStore } from "../../persistence/index.js";
+export declare function usageLimitStoreConformance(makeStore: () => UsageLimitStore): void;
+//# sourceMappingURL=usage-limits.d.ts.map

package/dist/testing/conformance/usage-limits.js

@@ -0,0 +1,309 @@
+/**
+ * `UsageLimitStore` conformance — admin-configured spend limits (#175).
+ *
+ * The rule under test is **most specific wins, as a fallback and never a merge**. That distinction is the whole
+ * reason this harness exists: an adapter that merged a principal's cost limit with the tenant's token limit would
+ * produce a third set of limits nobody configured, and every individual assertion about either would still pass.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { windowKey } from "../../persistence/index.js";
+/**
+ * The window every pre-existing case in here uses — #181 widened `period` into a union, and spelling it out at
+ * thirty-odd sites would bury what each case is about.
+ */
+const MONTH = { kind: "calendar", period: "month" };
+/** Five hours, the case a workspace admin actually asked for. */
+const FIVE_HOURS = { kind: "rolling", minutes: 300 };
+/** Two models, so a per-model limit can be shown *not* to bind on the other one — #182. */
+const OPUS = "claude-opus-5";
+const HAIKU = "claude-haiku-4-5";
+const T1 = asId("conf-tenant-1");
+const T2 = asId("conf-tenant-2");
+const P1 = asId("conf-principal-1");
+const P2 = asId("conf-principal-2");
+export function usageLimitStoreConformance(makeStore) {
+    describe("UsageLimitStore conformance", () => {
+        it("returns null when nothing is configured, which means unbounded", async () => {
+            // Not zero. A store that returned a zeroed limit would refuse every run, and an outage is only visible to
+            // the customer it is happening to — where an unbounded quota is visible in the rollups.
+            expect(await makeStore().resolve({ tenantId: T1, principalId: P1, window: MONTH })).toBeNull();
+        });
+        it("falls back to the tenant default when a principal has no override", async () => {
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" },
+            });
+            const resolved = await store.resolve({ tenantId: T1, principalId: P1, window: MONTH });
+            expect(resolved?.costMinorUnits).toBe(5000);
+            expect(resolved?.principalId).toBeUndefined();
+        });
+        it("prefers a principal's own limit over the tenant default", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" } });
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" },
+            });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(100);
+            // And leaves everyone else on the default.
+            expect((await store.resolve({ tenantId: T1, principalId: P2, window: MONTH }))?.costMinorUnits).toBe(5000);
+        });
+        /**
+         * A fallback, never a merge.
+         *
+         * The principal's row sets a cost limit and no token limit. Resolution must return *that row* — so the token
+         * limit is unbounded for them — rather than filling the gap from the tenant default. Merging would invent a
+         * limit nobody configured, and it would look correct in every test that checked one field at a time.
+         */
+        it("does not merge a partial override with the tenant default", async () => {
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, inputTokens: 1_000_000, updatedAt: "t" },
+            });
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" },
+            });
+            const resolved = await store.resolve({ tenantId: T1, principalId: P1, window: MONTH });
+            expect(resolved?.costMinorUnits).toBe(100);
+            expect(resolved?.inputTokens).toBeUndefined();
+        });
+        /**
+         * An omitted limit round-trips as **absent**, never as zero.
+         *
+         * The most dangerous direction in this whole feature, and the one my first pass at this harness missed: a
+         * store writing `0` for an unset limit refuses every run, and the quota code cannot tell that apart from an
+         * administrator setting a limit of zero on purpose. An outage is only visible to the customer it is happening
+         * to, where an unbounded quota is visible in the rollups.
+         *
+         * Caught by sabotage — replacing `?? null` with `?? 0` in the adapter passed every other test here.
+         */
+        it("round-trips an omitted limit as absent, not as zero", async () => {
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                // Cost only. Tokens are deliberately unset, which means unbounded.
+                limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" },
+            });
+            const resolved = await store.resolve({ tenantId: T1, principalId: P1, window: MONTH });
+            expect(resolved?.costMinorUnits).toBe(100);
+            expect(resolved?.inputTokens).toBeUndefined();
+            expect(resolved?.outputTokens).toBeUndefined();
+            expect(resolved?.warnAt).toBeUndefined();
+        });
+        it("stores a deliberate zero as zero, which is a different statement from absent", async () => {
+            // An administrator setting a limit of zero is saying "this person may spend nothing", and that has to be
+            // distinguishable from "no limit configured" — otherwise the two collapse and one of them is wrong.
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 0, updatedAt: "t" },
+            });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(0);
+        });
+        it("keeps periods independent", async () => {
+            // A monthly allowance says nothing about a weekly one. Resolving across periods would apply a month's
+            // budget to a week.
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" } });
+            expect(await store.resolve({ tenantId: T1, principalId: P1, window: { kind: "calendar", period: "week" } })).toBeNull();
+        });
+        it("replaces rather than accumulates when a limit is edited", async () => {
+            // Otherwise `resolve` would have to disambiguate between rows, and "which one wins" becomes an accident of
+            // insertion order.
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 250, updatedAt: "t" } });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(250);
+            expect(await store.list({ tenantId: T1 })).toHaveLength(1);
+        });
+        it("removing an override falls back to the default rather than to zero", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" } });
+            await store.remove({ tenantId: T1, principalId: P1, window: MONTH });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(5000);
+        });
+        it("removing the tenant default leaves an override in place", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t" } });
+            await store.remove({ tenantId: T1, window: MONTH });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(100);
+            expect(await store.resolve({ tenantId: T1, principalId: P2, window: MONTH })).toBeNull();
+        });
+        it("records who changed a limit", async () => {
+            // A spend limit is the kind of setting somebody eventually has to explain.
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100, updatedAt: "t", updatedBy: "admin@example.com" },
+            });
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.updatedBy).toBe("admin@example.com");
+        });
+        it("enforces tenant isolation", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5000, updatedAt: "t" } });
+            expect(await store.resolve({ tenantId: T2, principalId: P1, window: MONTH })).toBeNull();
+            expect(await store.list({ tenantId: T2 })).toEqual([]);
+        });
+        /** The rolling window an admin can now configure — #181. */
+        it("stores and resolves a rolling window", async () => {
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: FIVE_HOURS, costMinorUnits: 500, updatedAt: "t" },
+            });
+            const resolved = await store.resolve({ tenantId: T1, principalId: P1, window: FIVE_HOURS });
+            // Round-tripped as the union, not as whatever string the adapter happens to store — the guard branches on
+            // `kind`, so a rolling row coming back as a calendar one would enforce the wrong span silently.
+            expect(resolved?.window).toEqual(FIVE_HOURS);
+            expect(resolved?.costMinorUnits).toBe(500);
+        });
+        it("keeps a rolling window and a calendar one as separate limits", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 10_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: FIVE_HOURS, costMinorUnits: 500, updatedAt: "t" } });
+            // Both, because they are both real: "500 in any five hours **and** 10,000 a month" is the normal shape of
+            // a plan. If the window were not part of the key, the second `put` would have overwritten the first.
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(10_000);
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: FIVE_HOURS }))?.costMinorUnits).toBe(500);
+            expect(await store.list({ tenantId: T1 })).toHaveLength(2);
+        });
+        it("keeps two rolling windows of different lengths apart", async () => {
+            const store = makeStore();
+            const ninety = { kind: "rolling", minutes: 90 };
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: FIVE_HOURS, costMinorUnits: 500, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: ninety, costMinorUnits: 200, updatedAt: "t" } });
+            // The length is part of the identity. A key that dropped it would make every rolling limit the same row.
+            expect((await store.resolve({ tenantId: T1, window: FIVE_HOURS }))?.costMinorUnits).toBe(500);
+            expect((await store.resolve({ tenantId: T1, window: ninety }))?.costMinorUnits).toBe(200);
+        });
+        it("falls back from a principal's rolling window to the tenant's, and never merges them", async () => {
+            const store = makeStore();
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, window: FIVE_HOURS, costMinorUnits: 5000, inputTokens: 1_000_000, updatedAt: "t" },
+            });
+            await store.put({
+                tenantId: T1,
+                limit: { tenantId: T1, principalId: P1, window: FIVE_HOURS, costMinorUnits: 100, updatedAt: "t" },
+            });
+            const resolved = await store.resolve({ tenantId: T1, principalId: P1, window: FIVE_HOURS });
+            expect(resolved?.costMinorUnits).toBe(100);
+            // The rule #175 established, restated for the new window kind: a fallback, never a merge. Inheriting the
+            // tenant's token limit alongside the principal's cost limit would be a third set nobody configured.
+            expect(resolved?.inputTokens).toBeUndefined();
+        });
+        it("removes a rolling window without touching the calendar one beside it", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 10_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: FIVE_HOURS, costMinorUnits: 500, updatedAt: "t" } });
+            await store.remove({ tenantId: T1, principalId: P1, window: FIVE_HOURS });
+            expect(await store.resolve({ tenantId: T1, principalId: P1, window: FIVE_HOURS })).toBeNull();
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(10_000);
+        });
+        /**
+         * Per-model limits, and the rule that makes several limits coexist — #182.
+         *
+         * `applicable` is the surface the guard actually uses, so these are the cases that decide whether a
+         * configured limit is enforced at all.
+         */
+        it("returns every limit in force, not the most specific one", async () => {
+            const store = makeStore();
+            // A personal five-hour cap, a workspace monthly cap, and a workspace cap on one model.
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: FIVE_HOURS, costMinorUnits: 500, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 100_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, modelId: OPUS, costMinorUnits: 2_000, updatedAt: "t" } });
+            const applicable = await store.applicable({ tenantId: T1, principalId: P1, modelId: OPUS });
+            // All three. Returning only the "most specific" was how a workspace-wide Opus cap went unenforced for
+            // anybody who also had a personal limit — configured, visible, and never read.
+            expect(applicable).toHaveLength(3);
+            expect(applicable.map((r) => r.costMinorUnits).sort((a, b) => a - b)).toEqual([500, 2_000, 100_000]);
+        });
+        it("lets a principal's row override the tenant's within a scope, and only within it", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 100_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 5_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: FIVE_HOURS, costMinorUnits: 900, updatedAt: "t" } });
+            const applicable = await store.applicable({ tenantId: T1, principalId: P1 });
+            // Two scopes, two rows: the month is Alice's 5,000 (hers replaces the workspace's), and the five-hour is
+            // still the workspace's 900 — an override in one scope must not silence a different scope.
+            expect(applicable).toHaveLength(2);
+            const month = applicable.find((r) => windowKey(r.window) === "month");
+            const rolling = applicable.find((r) => windowKey(r.window) === "rolling:300");
+            expect(month?.costMinorUnits).toBe(5_000);
+            expect(month?.principalId).toBe(P1);
+            expect(rolling?.costMinorUnits).toBe(900);
+            expect(rolling?.principalId).toBeUndefined();
+        });
+        it("applies a model-scoped limit only to that model", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, modelId: OPUS, costMinorUnits: 2_000, updatedAt: "t" } });
+            expect(await store.applicable({ tenantId: T1, principalId: P1, modelId: OPUS })).toHaveLength(1);
+            // A cheap model is not subject to the expensive model's allowance, which is the entire point of scoping.
+            expect(await store.applicable({ tenantId: T1, principalId: P1, modelId: HAIKU })).toHaveLength(0);
+        });
+        it("does not apply a model-scoped limit when no model is given", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, modelId: OPUS, costMinorUnits: 2_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 100_000, updatedAt: "t" } });
+            const applicable = await store.applicable({ tenantId: T1, principalId: P1 });
+            // Only the unscoped one. An unknown model cannot be checked against a per-model allowance, and applying it
+            // anyway would refuse work on a model the limit was never about.
+            expect(applicable).toHaveLength(1);
+            expect(applicable[0]?.modelId).toBeUndefined();
+        });
+        it("keeps a model-scoped limit and an unscoped one as separate rows", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, modelId: OPUS, costMinorUnits: 2_000, updatedAt: "t" } });
+            // If the model were not part of the key, the second `put` would have overwritten the first — the person's
+            // overall monthly allowance would silently become 2,000.
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(100_000);
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH, modelId: OPUS }))?.costMinorUnits).toBe(2_000);
+            expect(await store.list({ tenantId: T1 })).toHaveLength(2);
+        });
+        it("removes a model-scoped limit without touching the unscoped one", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, costMinorUnits: 100_000, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: MONTH, modelId: OPUS, costMinorUnits: 2_000, updatedAt: "t" } });
+            await store.remove({ tenantId: T1, principalId: P1, window: MONTH, modelId: OPUS });
+            expect(await store.resolve({ tenantId: T1, principalId: P1, window: MONTH, modelId: OPUS })).toBeNull();
+            expect((await store.resolve({ tenantId: T1, principalId: P1, window: MONTH }))?.costMinorUnits).toBe(100_000);
+        });
+        it("does not return another principal's limit", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P2, window: MONTH, costMinorUnits: 1, updatedAt: "t" } });
+            // P2's row is not P1's business, and a guard that saw it would refuse the wrong person.
+            expect(await store.applicable({ tenantId: T1, principalId: P1 })).toHaveLength(0);
+        });
+        it("does not return another tenant's limits", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 5, updatedAt: "t" } });
+            expect(await store.applicable({ tenantId: T2, principalId: P1 })).toHaveLength(0);
+        });
+        it("keys a window the same way in every adapter", () => {
+            // Not a store test — a guard on the codec both adapters key on. The memory store builds its map key from
+            // `windowKey` and the SQL store writes the same string to `window_key`; if the two ever spelled a window
+            // differently, both would stay self-consistent and neither could read the other's rows, and every case
+            // above would still pass.
+            expect(windowKey(MONTH)).toBe("month");
+            expect(windowKey(FIVE_HOURS)).toBe("rolling:300");
+        });
+        it("lists every configured limit for an admin screen, in a stable order", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P2, window: MONTH, costMinorUnits: 1, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, window: MONTH, costMinorUnits: 2, updatedAt: "t" } });
+            await store.put({ tenantId: T1, limit: { tenantId: T1, principalId: P1, window: { kind: "calendar", period: "week" }, costMinorUnits: 3, updatedAt: "t" } });
+            const listed = await store.list({ tenantId: T1 });
+            expect(listed).toHaveLength(3);
+            // The tenant default first, then principals — so a screen does not reshuffle between refreshes.
+            expect(listed[0]?.principalId).toBeUndefined();
+        });
+    });
+}
+//# sourceMappingURL=usage-limits.js.map

package/dist/testing/conformance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim. The suite grew from one harness into `./conformance/` (see #91); this file keeps
+ * the original import path working so existing adapter tests did not have to change in the same PR.
+ *
+ * Prefer importing from `../testing/conformance/index.js` in new code.
+ */
+export * from "./conformance/index.js";
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.js

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim. The suite grew from one harness into `./conformance/` (see #91); this file keeps
+ * the original import path working so existing adapter tests did not have to change in the same PR.
+ *
+ * Prefer importing from `../testing/conformance/index.js` in new code.
+ */
+export * from "./conformance/index.js";
+//# sourceMappingURL=conformance.js.map

package/dist/testing/memory-backend.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Every in-memory store, assembled — task #253 AC-5.
+ *
+ * Fifteen `createMemory*` calls is the current price of a test that needs a working backend, and the reference
+ * host pays it in `examples/src/memory-app.ts`. Every consumer testing an agent would rebuild the same list,
+ * and the sixteenth store to land would be missing from all of them — silently, because a missing store is a
+ * missing dependency and a caller that does not use it never notices.
+ *
+ * ## Called, not shared
+ *
+ * A factory per assembly, because here the factory **is** the state. `examples/src/memory-app.ts` records what
+ * calling it twice does: two empty worlds, and a message that vanishes between being written and being read.
+ * The Postgres adapters take an executor and hold nothing, which is why they are safe to construct per call and
+ * these are not.
+ */
+export declare const createMemoryStores: () => {
+    conversations: import("../index.js").ConversationStore;
+    messages: import("../index.js").MessageStore;
+    runs: import("../index.js").RunStore;
+    checkpoints: import("../index.js").CheckpointStore;
+    eventLog: import("../index.js").RunEventLog;
+    interactions: import("../index.js").InteractionStore;
+    grants: import("../index.js").ApprovalGrantStore;
+    sessions: import("../index.js").SessionStateStore;
+    summaries: import("../index.js").ThreadSummaryStore;
+    idempotency: import("../index.js").IdempotencyStore;
+    principalMemory: import("../index.js").PrincipalMemoryStore;
+    skills: import("../index.js").SkillStore & {
+        add(tenantId: string, skill: import("../index.js").SkillVersion): void;
+    };
+    usage: import("../index.js").UsageStore;
+    rollups: import("../index.js").UsageRollupStore;
+    limits: import("../index.js").UsageLimitStore;
+    coordinator: import("../index.js").ConversationRunCoordinator;
+    /** #248. Single-process by construction — see the adapter's own header before using it anywhere real. */
+    rateLimit: import("../index.js").RateLimitStore;
+};
+export type MemoryStores = ReturnType<typeof createMemoryStores>;
+//# sourceMappingURL=memory-backend.d.ts.map

package/dist/testing/memory-backend.js

@@ -0,0 +1,41 @@
+/**
+ * Every in-memory store, assembled — task #253 AC-5.
+ *
+ * Fifteen `createMemory*` calls is the current price of a test that needs a working backend, and the reference
+ * host pays it in `examples/src/memory-app.ts`. Every consumer testing an agent would rebuild the same list,
+ * and the sixteenth store to land would be missing from all of them — silently, because a missing store is a
+ * missing dependency and a caller that does not use it never notices.
+ *
+ * ## Called, not shared
+ *
+ * A factory per assembly, because here the factory **is** the state. `examples/src/memory-app.ts` records what
+ * calling it twice does: two empty worlds, and a message that vanishes between being written and being read.
+ * The Postgres adapters take an executor and hold nothing, which is why they are safe to construct per call and
+ * these are not.
+ */
+import { createMemoryApprovalGrantStore, createMemoryCheckpointStore, createMemoryConversationRunCoordinator, createMemoryConversationStore, createMemoryIdempotencyStore, createMemoryInteractionStore, createMemoryMessageStore, createMemoryPrincipalMemoryStore, createMemoryRunEventLog, createMemoryRunStore, createMemorySessionStateStore, createMemorySkillStore, createMemoryThreadSummaryStore, createMemoryUsageBackend, createMemoryUsageLimitStore, } from "../adapters/memory/index.js";
+import { createMemoryRateLimitStore } from "../adapters/memory/rate-limit.js";
+export const createMemoryStores = () => {
+    const usage = createMemoryUsageBackend();
+    return {
+        conversations: createMemoryConversationStore(),
+        messages: createMemoryMessageStore(),
+        runs: createMemoryRunStore(),
+        checkpoints: createMemoryCheckpointStore(),
+        eventLog: createMemoryRunEventLog(),
+        interactions: createMemoryInteractionStore(),
+        grants: createMemoryApprovalGrantStore(),
+        sessions: createMemorySessionStateStore(),
+        summaries: createMemoryThreadSummaryStore(),
+        idempotency: createMemoryIdempotencyStore(),
+        principalMemory: createMemoryPrincipalMemoryStore(),
+        skills: createMemorySkillStore(),
+        usage: usage.usage,
+        rollups: usage.rollups,
+        limits: createMemoryUsageLimitStore(),
+        coordinator: createMemoryConversationRunCoordinator(),
+        /** #248. Single-process by construction — see the adapter's own header before using it anywhere real. */
+        rateLimit: createMemoryRateLimitStore(),
+    };
+};
+//# sourceMappingURL=memory-backend.js.map