@retinue/agentkit 0.2.0 → 0.3.0

package/dist/testing/conformance/parents.js

@@ -0,0 +1,39 @@
+/**
+ * Parent seeding for the conformance suite.
+ *
+ * An adapter is entitled to enforce referential integrity, and the Postgres schema does: a checkpoint
+ * belongs to a run, a message and a binding belong to a conversation. The in-memory reference adapter
+ * holds no such constraint, so the shared harnesses never created those parent rows — and every
+ * foreign key added to the schema broke them.
+ *
+ * #95 solved that for `CheckpointStore` with a bespoke fixture type. #96 needed the same thing for
+ * `ConversationBindingStore`, which is the point at which a one-off becomes a pattern. This is the
+ * shared mechanism: a harness accepts either a bare store (adapters with no constraints, unchanged)
+ * or a fixture pairing the store with the seeders its constraints require.
+ *
+ * The alternative was to drop the foreign keys so the harness would pass, which would have traded a
+ * real guarantee — orphan rows are impossible — for a green suite. That is the wrong direction.
+ */
+const isFixture = (value) => typeof value === "object" && value !== null && "store" in value;
+/**
+ * Normalise whichever shape the adapter supplied. Returns the store and the seeders, so a harness can
+ * seed unconditionally without caring which form it was given.
+ */
+export const openFixture = (made) => isFixture(made) ? made : { store: made };
+/** Seed a run if the adapter needs one, then hand back the store. */
+export const withRun = async (made, runs) => {
+    const fixture = openFixture(made);
+    if (fixture.seedRun)
+        for (const r of runs)
+            await fixture.seedRun(r);
+    return fixture.store;
+};
+/** Seed a conversation if the adapter needs one, then hand back the store. */
+export const withConversation = async (made, conversations) => {
+    const fixture = openFixture(made);
+    if (fixture.seedConversation)
+        for (const c of conversations)
+            await fixture.seedConversation(c);
+    return fixture.store;
+};
+//# sourceMappingURL=parents.js.map

package/dist/testing/conformance/rate-limit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `RateLimitStore` conformance — task #248, AC-6.
+ *
+ * The contract is small and every clause is a defect somebody would otherwise ship:
+ *
+ * - **Counting is per key.** A store that ignored the window start would never reset; one that ignored the
+ *   tenant would let one customer exhaust another's allowance.
+ * - **`consume` returns the count *after* incrementing**, starting at 1. Off by one here means a limit of `max`
+ *   admits `max + 1`, which no test of the guard alone would catch because the guard would be consistent with
+ *   its own store.
+ * - **It is atomic under concurrency.** Twenty concurrent consumes must yield the twenty distinct counts 1..20,
+ *   with no value repeated. A read-then-write implementation loses increments and quietly raises the effective
+ *   limit — the failure this whole port exists to prevent, arriving from inside.
+ *
+ * Run against the in-memory store and against Redis. The in-memory one is single-process by construction, so it
+ * satisfies the contract while being unusable in a fleet; that is why the Redis suite exists separately and why
+ * `createMemoryRateLimitStore`'s header says so.
+ */
+import type { RateLimitStore } from "../../usage/index.js";
+export declare function rateLimitStoreConformance(
+/** The adapter under test, for the inner describe block. */
+name: string, makeStore: () => RateLimitStore | Promise<RateLimitStore>, 
+/** A suffix making keys unique per run, so a rerun inside the same window does not inherit a count. */
+unique: () => string): void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/testing/conformance/rate-limit.js

@@ -0,0 +1,71 @@
+/**
+ * `RateLimitStore` conformance — task #248, AC-6.
+ *
+ * The contract is small and every clause is a defect somebody would otherwise ship:
+ *
+ * - **Counting is per key.** A store that ignored the window start would never reset; one that ignored the
+ *   tenant would let one customer exhaust another's allowance.
+ * - **`consume` returns the count *after* incrementing**, starting at 1. Off by one here means a limit of `max`
+ *   admits `max + 1`, which no test of the guard alone would catch because the guard would be consistent with
+ *   its own store.
+ * - **It is atomic under concurrency.** Twenty concurrent consumes must yield the twenty distinct counts 1..20,
+ *   with no value repeated. A read-then-write implementation loses increments and quietly raises the effective
+ *   limit — the failure this whole port exists to prevent, arriving from inside.
+ *
+ * Run against the in-memory store and against Redis. The in-memory one is single-process by construction, so it
+ * satisfies the contract while being unusable in a fleet; that is why the Redis suite exists separately and why
+ * `createMemoryRateLimitStore`'s header says so.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+// `export function`, not `export const`: the coverage guard splits harness sources on
+// `\nexport function (\w+Conformance)` to locate each body, so an arrow-function export is invisible to it and
+// reads as a missing harness.
+export function rateLimitStoreConformance(
+/** The adapter under test, for the inner describe block. */
+name, makeStore, 
+/** A suffix making keys unique per run, so a rerun inside the same window does not inherit a count. */
+unique) {
+    // Exactly `<Port> conformance`: `scripts/conformance-matrix.mjs` maps that title back to the port. The
+    // adapter's name goes on the inner block instead.
+    describe("RateLimitStore conformance", () => {
+        const T1 = asId(`rlc-t1-${unique()}`);
+        const T2 = asId(`rlc-t2-${unique()}`);
+        const T = (s) => asId(`rlc-${s}-${unique()}`);
+        it(`[${name}] returns the count after incrementing, starting at 1`, async () => {
+            const store = await makeStore();
+            const tenantId = T("count");
+            const input = { tenantId, windowStartMs: 60_000, windowSeconds: 60 };
+            expect(await store.consume(input)).toBe(1);
+            expect(await store.consume(input)).toBe(2);
+            expect(await store.consume(input)).toBe(3);
+        });
+        it("counts each window separately", async () => {
+            const store = await makeStore();
+            const tenantId = T("window");
+            expect(await store.consume({ tenantId, windowStartMs: 60_000, windowSeconds: 60 })).toBe(1);
+            expect(await store.consume({ tenantId, windowStartMs: 60_000, windowSeconds: 60 })).toBe(2);
+            // A new window is a new count, which is what makes a limit recover rather than latch.
+            expect(await store.consume({ tenantId, windowStartMs: 120_000, windowSeconds: 60 })).toBe(1);
+        });
+        it("counts each tenant separately — T2 is unaffected by T1's consumption", async () => {
+            // The isolation clause. There is no cross-tenant *read* to leak here, but there is a cross-tenant
+            // *count*: a store keyed on the window alone would let one customer exhaust every other customer's
+            // allowance, which is the same class of defect as the AgentStore leak #91 found.
+            const store = await makeStore();
+            expect(await store.consume({ tenantId: T1, windowStartMs: 60_000, windowSeconds: 60 })).toBe(1);
+            expect(await store.consume({ tenantId: T1, windowStartMs: 60_000, windowSeconds: 60 })).toBe(2);
+            expect(await store.consume({ tenantId: T2, windowStartMs: 60_000, windowSeconds: 60 })).toBe(1);
+        });
+        it("loses no increment under concurrency", async () => {
+            // Twenty concurrent consumes must produce the twenty distinct counts 1..20. A read-then-write store
+            // returns duplicates, and a duplicate is a lost increment — a limit that admits more than it says.
+            const store = await makeStore();
+            const tenantId = T("concurrent");
+            const input = { tenantId, windowStartMs: 60_000, windowSeconds: 60 };
+            const counts = await Promise.all(Array.from({ length: 20 }, () => store.consume(input)));
+            expect([...counts].sort((x, y) => x - y)).toEqual(Array.from({ length: 20 }, (_, i) => i + 1));
+        });
+    });
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/testing/conformance/records.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Record-store conformance: `MessageStore`, `AgentStore`, `SkillStore`, `BlobStore`,
+ * `IdempotencyStore`, `PrincipalMemoryStore`, `McpConnectionStore`.
+ *
+ * Two of these carry a safety property rather than merely a data contract, and both are asserted
+ * here rather than assumed:
+ *  - `BlobStore` — "tenant-scoped so a ref from one tenant can never resolve another's bytes".
+ *  - `PrincipalMemoryStore` — every method takes `{ tenantId, principalId }`, so a query "can never
+ *    reach another principal's or tenant's memory". Tenant isolation alone is not enough; the
+ *    cross-*principal* case inside one tenant is the one that would leak between colleagues.
+ */
+import { type FixtureOrStore } from "./parents.js";
+import type { TenantId } from "../../core/ids.js";
+import type { AgentStore, BlobStore, MessageStore, SkillStore } from "../../persistence/index.js";
+import { type IdempotencyStore } from "../../idempotency/index.js";
+import type { PrincipalMemoryStore } from "../../principal-memory/index.js";
+import type { McpConnectionStore } from "../../mcp/provider.js";
+export declare function messageStoreConformance(makeFixture: () => FixtureOrStore<MessageStore>): void;
+export declare function agentStoreConformance(makeStore: () => AgentStore, seed: (store: AgentStore, input: {
+    tenantId: TenantId;
+    agentId: string;
+    version: number;
+}) => Promise<void>): void;
+export declare function skillStoreConformance(makeStore: () => SkillStore, seed: (store: SkillStore, input: {
+    tenantId: TenantId;
+    name: string;
+    version: number;
+}) => Promise<void>): void;
+export declare function blobStoreConformance(makeStore: () => BlobStore): void;
+export declare function idempotencyStoreConformance(makeStore: () => IdempotencyStore): void;
+export declare function principalMemoryStoreConformance(makeStore: () => PrincipalMemoryStore): void;
+export declare function mcpConnectionStoreConformance(makeStore: () => McpConnectionStore, seed: (store: McpConnectionStore, input: {
+    tenantId: TenantId;
+    id: string;
+}) => Promise<void>): void;
+//# sourceMappingURL=records.d.ts.map

package/dist/testing/conformance/records.js

@@ -0,0 +1,400 @@
+/**
+ * Record-store conformance: `MessageStore`, `AgentStore`, `SkillStore`, `BlobStore`,
+ * `IdempotencyStore`, `PrincipalMemoryStore`, `McpConnectionStore`.
+ *
+ * Two of these carry a safety property rather than merely a data contract, and both are asserted
+ * here rather than assumed:
+ *  - `BlobStore` — "tenant-scoped so a ref from one tenant can never resolve another's bytes".
+ *  - `PrincipalMemoryStore` — every method takes `{ tenantId, principalId }`, so a query "can never
+ *    reach another principal's or tenant's memory". Tenant isolation alone is not enough; the
+ *    cross-*principal* case inside one tenant is the one that would leak between colleagues.
+ */
+import { describe, expect, it } from "vitest";
+import { withConversation } from "./parents.js";
+import { asId } from "../../core/ids.js";
+import { deriveIdempotencyKey } from "../../idempotency/index.js";
+const T1 = asId("conf-tenant-1");
+const T2 = asId("conf-tenant-2");
+const P1 = asId("conf-principal-1");
+const P2 = asId("conf-principal-2");
+const RUN = asId("conf-run-1");
+const C1 = asId("conf-convo-1");
+export function messageStoreConformance(makeFixture) {
+    // A message references a conversation, and Postgres enforces that with a foreign key (#96) — the
+    // fixture's `seedConversation` creates the parent through the adapter's own executor. See ./parents.ts.
+    const open = (conversationId = C1) => withConversation(makeFixture(), [{ tenantId: T1, conversationId }]);
+    /**
+     * Seeding goes through the port as of #157. It used to be a callback each adapter test supplied, because
+     * `append` was a "test-only affordance" off the port with a positional signature — so all three adapter tests
+     * carried their own cast and their own copy of this loop, free to diverge on the very shapes the suite is
+     * supposed to be pinning down. The Postgres copy seeded `role: "user"` with a text part; the memory copy
+     * seeded `role: "assistant"` with none. The parts round-trip test below therefore proved nothing about the
+     * memory adapter: it asserted `Array.isArray(parts)`, and `[]` is an array.
+     */
+    const seed = async (store, { tenantId, conversationId, count }) => {
+        for (let n = 0; n < count; n += 1) {
+            await store.append({ tenantId, message: message(conversationId, n) });
+        }
+    };
+    const message = (conversationId, n, id = `m${n}`) => ({
+        id: asId(id),
+        conversationId,
+        runId: RUN,
+        role: n % 2 === 0 ? "user" : "assistant",
+        parts: [
+            {
+                id: asId(`p${n}`),
+                type: "text",
+                schemaVersion: 1,
+                createdAt: `2020-01-01T00:00:${String(n).padStart(2, "0")}.000Z`,
+                text: `message ${n}`,
+            },
+        ],
+        createdAt: `2020-01-01T00:00:${String(n).padStart(2, "0")}.000Z`,
+    });
+    describe("MessageStore conformance", () => {
+        it("returns null for an unknown id", async () => {
+            const store = await open();
+            expect(await store.findById({ tenantId: T1, id: asId("nope") })).toBeNull();
+        });
+        it("reads back an appended message by id", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, message: message(C1, 0) });
+            const found = await store.findById({ tenantId: T1, id: asId("m0") });
+            expect(found?.id).toBe("m0");
+            expect(found?.role).toBe("user");
+        });
+        it("lists a conversation's messages in order", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 3 });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items).toHaveLength(3);
+            expect(page.items.map((m) => m.id)).toEqual(["m0", "m1", "m2"]);
+        });
+        it("pages by stable cursor with no overlap between pages", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 5 });
+            const first = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 2 });
+            expect(first.items).toHaveLength(2);
+            expect(first.nextCursor).toBeDefined();
+            const second = await store.listByConversation({
+                tenantId: T1,
+                conversationId: C1,
+                limit: 2,
+                cursor: first.nextCursor,
+            });
+            const firstIds = new Set(first.items.map((m) => m.id));
+            expect(second.items.some((m) => firstIds.has(m.id))).toBe(false);
+        });
+        it("preserves typed content parts through a round-trip", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 1 });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 1 });
+            const part = page.items[0]?.parts[0];
+            expect(part?.type).toBe("text");
+            expect(part).toMatchObject({ id: "p0", schemaVersion: 1, text: "message 0" });
+        });
+        /**
+         * The most recent messages, which is the query a chat application actually makes — #167.
+         *
+         * The port could only answer "the oldest N", so a host wanting the tail of a long conversation either paged
+         * through the whole thing or, much more likely, asked for 100 and silently got turns 1–100. In a
+         * 2000-message conversation that hands a model the beginning and none of the present.
+         */
+        it("reads the newest messages first when asked", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 5 });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 2, newestFirst: true });
+            expect(page.items.map((m) => m.id)).toEqual(["m4", "m3"]);
+        });
+        it("pages backwards without overlap or gaps", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 5 });
+            const first = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 2, newestFirst: true });
+            const second = await store.listByConversation({
+                tenantId: T1,
+                conversationId: C1,
+                limit: 2,
+                newestFirst: true,
+                cursor: first.nextCursor,
+            });
+            // The cursor has to flip with the sort. Split apart they produce a page that scans one way and pages the
+            // other, which returns rows already seen and looks like duplication.
+            expect(second.items.map((m) => m.id)).toEqual(["m2", "m1"]);
+        });
+        /**
+         * Ordered by timestamp, not by insertion.
+         *
+         * The two agree for anything appended in order, which is why this went unnoticed: every fixture seeded in
+         * timestamp order, so the in-memory adapter's array order happened to match the SQL adapter's `ORDER BY`.
+         * A backfilled or replayed message is where they diverge.
+         */
+        it("orders by created_at even when messages arrive out of order", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, message: message(C1, 5, "later") });
+            await store.append({ tenantId: T1, message: message(C1, 1, "earlier") });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items.map((m) => m.id)).toEqual(["earlier", "later"]);
+        });
+        /**
+         * A retried request must neither fail nor duplicate. #157 put `append` on the port, and a caller that
+         * retries — the same user turn re-submitted after a dropped connection — carries the same message id;
+         * a second row would show the user their own message twice and feed the model a doubled turn.
+         */
+        it("is idempotent on the message id", async () => {
+            const store = await open();
+            await store.append({ tenantId: T1, message: message(C1, 0) });
+            await store.append({ tenantId: T1, message: message(C1, 0) });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items).toHaveLength(1);
+        });
+        /** The same id under another tenant is a different message, not a conflict to swallow. */
+        it("scopes appended messages to the writing tenant", async () => {
+            const fixture = await withConversation(makeFixture(), [
+                { tenantId: T1, conversationId: C1 },
+                { tenantId: T2, conversationId: C1 },
+            ]);
+            await fixture.append({ tenantId: T1, message: message(C1, 0) });
+            await fixture.append({ tenantId: T2, message: { ...message(C1, 0), role: "assistant" } });
+            expect((await fixture.findById({ tenantId: T1, id: asId("m0") }))?.role).toBe("user");
+            expect((await fixture.findById({ tenantId: T2, id: asId("m0") }))?.role).toBe("assistant");
+        });
+        it("enforces tenant isolation", async () => {
+            const store = await open();
+            await seed(store, { tenantId: T1, conversationId: C1, count: 2 });
+            const other = await store.listByConversation({ tenantId: T2, conversationId: C1, limit: 10 });
+            expect(other.items).toHaveLength(0);
+        });
+    });
+}
+export function agentStoreConformance(makeStore, seed) {
+    describe("AgentStore conformance", () => {
+        it("returns null for an unknown agent version", async () => {
+            expect(await makeStore().findByVersion({ tenantId: T1, agentId: "nope", version: 1 })).toBeNull();
+        });
+        it("resolves the exact version requested", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, agentId: "a", version: 1 });
+            await seed(store, { tenantId: T1, agentId: "a", version: 2 });
+            expect(await store.findByVersion({ tenantId: T1, agentId: "a", version: 1 })).not.toBeNull();
+            expect(await store.findByVersion({ tenantId: T1, agentId: "a", version: 2 })).not.toBeNull();
+        });
+        it("does not fall back to another version when the requested one is absent", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, agentId: "a", version: 1 });
+            expect(await store.findByVersion({ tenantId: T1, agentId: "a", version: 7 })).toBeNull();
+        });
+        /**
+         * Surfaced by #91 as a real leak and fixed: `createMemoryAgentStore` keyed its map by
+         * `id@version` alone and destructured only `{ agentId, version }`, so one tenant could resolve
+         * another tenant's manifest. It now partitions by tenant like every sibling store.
+         *
+         * Kept deliberately as a regression test rather than deleted — an agent manifest carries no
+         * `tenantId` of its own, so nothing in the type system stops this from being reintroduced.
+         */
+        it("enforces tenant isolation", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, agentId: "a", version: 1 });
+            expect(await store.findByVersion({ tenantId: T2, agentId: "a", version: 1 })).toBeNull();
+        });
+        it("keeps same-id manifests separate per tenant", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, agentId: "shared", version: 1 });
+            await seed(store, { tenantId: T2, agentId: "shared", version: 1 });
+            // Both tenants may legitimately own an agent with the same id; neither may see the other's.
+            expect(await store.findByVersion({ tenantId: T1, agentId: "shared", version: 1 })).not.toBeNull();
+            expect(await store.findByVersion({ tenantId: T2, agentId: "shared", version: 1 })).not.toBeNull();
+        });
+        it("does not leak a version one tenant owns and the other does not", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, agentId: "a", version: 1 });
+            await seed(store, { tenantId: T2, agentId: "a", version: 2 });
+            expect(await store.findByVersion({ tenantId: T1, agentId: "a", version: 2 })).toBeNull();
+            expect(await store.findByVersion({ tenantId: T2, agentId: "a", version: 1 })).toBeNull();
+        });
+    });
+}
+export function skillStoreConformance(makeStore, seed) {
+    describe("SkillStore conformance", () => {
+        it("returns an empty catalog for a tenant with no skills", async () => {
+            expect(await makeStore().listCatalog({ tenantId: T1 })).toHaveLength(0);
+        });
+        it("lists the catalog after seeding", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, name: "post-composition", version: 1 });
+            expect((await store.listCatalog({ tenantId: T1 })).length).toBeGreaterThan(0);
+        });
+        it("resolves a specific version, so a run records what it actually used", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, name: "post-composition", version: 1 });
+            await seed(store, { tenantId: T1, name: "post-composition", version: 2 });
+            const v1 = await store.findVersion({ tenantId: T1, name: "post-composition", version: 1 });
+            expect(v1?.version).toBe(1);
+        });
+        it("returns null for an absent version rather than the nearest one", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, name: "post-composition", version: 1 });
+            expect(await store.findVersion({ tenantId: T1, name: "post-composition", version: 9 })).toBeNull();
+        });
+        it("enforces tenant isolation", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, name: "post-composition", version: 1 });
+            expect(await store.listCatalog({ tenantId: T2 })).toHaveLength(0);
+            expect(await store.findVersion({ tenantId: T2, name: "post-composition", version: 1 })).toBeNull();
+        });
+    });
+}
+export function blobStoreConformance(makeStore) {
+    describe("BlobStore conformance", () => {
+        it("round-trips a stored value by ref", async () => {
+            const store = makeStore();
+            const ref = await store.put({ tenantId: T1, value: { large: "payload" } });
+            expect(await store.get({ tenantId: T1, ref })).toEqual({ large: "payload" });
+        });
+        it("returns null for a ref that was never issued", async () => {
+            const store = makeStore();
+            // Previously this asked a *second store instance* for a ref the first had issued, which for an
+            // in-memory adapter means "unknown" and for a durable one means the opposite — a second store
+            // over the same database should find it. It passed only because the Postgres wiring hands each
+            // factory call a fresh database, so it was testing instance identity rather than absence.
+            // Fabricating a ref tests what the name says, and is correct for both (#102).
+            await store.put({ tenantId: T1, value: 1 });
+            expect(await store.get({ tenantId: T1, ref: asId("blob:never-issued:0") })).toBeNull();
+        });
+        it("a ref from one tenant never resolves another tenant's bytes", async () => {
+            const store = makeStore();
+            const ref = await store.put({ tenantId: T1, value: { secret: true } });
+            expect(await store.get({ tenantId: T2, ref })).toBeNull();
+        });
+        it("keeps distinct values distinct", async () => {
+            const store = makeStore();
+            const a = await store.put({ tenantId: T1, value: { v: "a" } });
+            const b = await store.put({ tenantId: T1, value: { v: "b" } });
+            expect(await store.get({ tenantId: T1, ref: a })).toEqual({ v: "a" });
+            expect(await store.get({ tenantId: T1, ref: b })).toEqual({ v: "b" });
+        });
+    });
+}
+export function idempotencyStoreConformance(makeStore) {
+    const key = deriveIdempotencyKey({ tenantId: T1, runId: RUN, toolCallId: asId("tc1") });
+    describe("IdempotencyStore conformance", () => {
+        it("returns null for an unseen key", async () => {
+            expect(await makeStore().get({ tenantId: T1, key })).toBeNull();
+        });
+        it("returns the stored result for a repeated key, so the operation is not re-executed", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, key, result: { published: true } });
+            const seen = await store.get({ tenantId: T1, key });
+            expect(seen?.result).toEqual({ published: true });
+        });
+        it("reports firstSeen honestly on the replay path", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, key, result: 1 });
+            expect((await store.get({ tenantId: T1, key }))?.firstSeen).toBe(false);
+        });
+        it("enforces tenant isolation — a key is never shared across tenants", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, key, result: { published: true } });
+            expect(await store.get({ tenantId: T2, key })).toBeNull();
+        });
+    });
+}
+export function principalMemoryStoreConformance(makeStore) {
+    describe("PrincipalMemoryStore conformance", () => {
+        it("stores and reads back an entry for its principal", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "prefers concise answers" });
+            expect(await store.get({ tenantId: T1, principalId: P1, id: entry.id })).toMatchObject({
+                text: "prefers concise answers",
+            });
+        });
+        it("never reaches another principal's memory inside the same tenant", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "private to P1" });
+            expect(await store.get({ tenantId: T1, principalId: P2, id: entry.id })).toBeNull();
+            expect((await store.list({ tenantId: T1, principalId: P2, limit: 10 })).items).toHaveLength(0);
+        });
+        it("never reaches another tenant's memory", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "private to T1" });
+            expect(await store.get({ tenantId: T2, principalId: P1, id: entry.id })).toBeNull();
+        });
+        it("rejects a stale expectedVersion on update", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "v1" });
+            await store.update({
+                tenantId: T1,
+                principalId: P1,
+                id: entry.id,
+                expectedVersion: entry.version,
+                patch: { text: "v2" },
+            });
+            await expect(store.update({
+                tenantId: T1,
+                principalId: P1,
+                id: entry.id,
+                expectedVersion: entry.version,
+                patch: { text: "stale" },
+            })).rejects.toThrow();
+        });
+        it("hard-deletes, so a deleted entry cannot resurface in a later prompt", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "forget me" });
+            await store.delete({ tenantId: T1, principalId: P1, id: entry.id });
+            expect(await store.get({ tenantId: T1, principalId: P1, id: entry.id })).toBeNull();
+            expect(await store.retrieve({ tenantId: T1, principalId: P1, limit: 10 })).toHaveLength(0);
+        });
+        it("excludes disabled entries from retrieval but keeps them readable", async () => {
+            const store = makeStore();
+            const entry = await store.put({ tenantId: T1, principalId: P1, text: "temporarily off" });
+            await store.update({
+                tenantId: T1,
+                principalId: P1,
+                id: entry.id,
+                expectedVersion: entry.version,
+                patch: { disabled: true },
+            });
+            expect(await store.retrieve({ tenantId: T1, principalId: P1, limit: 10 })).toHaveLength(0);
+            expect(await store.get({ tenantId: T1, principalId: P1, id: entry.id })).not.toBeNull();
+        });
+        it("retrieve returns most salient first and honors the limit", async () => {
+            const store = makeStore();
+            await store.put({ tenantId: T1, principalId: P1, text: "low", salience: 1 });
+            await store.put({ tenantId: T1, principalId: P1, text: "high", salience: 9 });
+            const top = await store.retrieve({ tenantId: T1, principalId: P1, limit: 1 });
+            expect(top).toHaveLength(1);
+            expect(top[0]?.text).toBe("high");
+        });
+    });
+}
+export function mcpConnectionStoreConformance(makeStore, seed) {
+    describe("McpConnectionStore conformance", () => {
+        it("returns null for an unregistered connection", async () => {
+            expect(await makeStore().get({ tenantId: T1, id: "nope" })).toBeNull();
+        });
+        it("registers and reads back a connection", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, id: "srv1" });
+            expect(await store.get({ tenantId: T1, id: "srv1" })).not.toBeNull();
+        });
+        it("lists a tenant's connections", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, id: "srv1" });
+            await seed(store, { tenantId: T1, id: "srv2" });
+            expect(await store.list({ tenantId: T1 })).toHaveLength(2);
+        });
+        it("toggles enabled without losing the record", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, id: "srv1" });
+            await store.setEnabled({ tenantId: T1, id: "srv1", enabled: false });
+            expect(await store.get({ tenantId: T1, id: "srv1" })).not.toBeNull();
+        });
+        it("enforces tenant isolation", async () => {
+            const store = makeStore();
+            await seed(store, { tenantId: T1, id: "srv1" });
+            expect(await store.get({ tenantId: T2, id: "srv1" })).toBeNull();
+            expect(await store.list({ tenantId: T2 })).toHaveLength(0);
+        });
+    });
+}
+//# sourceMappingURL=records.js.map

package/dist/testing/conformance/rollups.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `UsageRollupStore` conformance (#139).
+ *
+ * Almost every case is about a property that only shows up under repetition or concurrency: idempotency, no
+ * double counting, no lost records, no cross-tenant aggregate. Those are the ones a spend figure has to get
+ * right, and the ones a single-write test cannot see.
+ *
+ * The fixture pairs the rollup store with the ledger it derives from, because a rollup computed from a
+ * *different* set of events than the ledger holds is the exact bug this port exists to prevent — and a suite
+ * that opened them separately could not notice.
+ */
+import type { RunId, TenantId } from "../../core/ids.js";
+import type { UsageRollupStore, UsageStore } from "../../persistence/index.js";
+/**
+ * Both ports over one set of events, which is how a real deployment provides them.
+ *
+ * `seedRun` because `usage_records` has a foreign key to `runs` — an event belongs to a run, and Postgres
+ * enforces it. The in-memory adapter has no such constraint, which is exactly the situation `parents.ts`
+ * exists for.
+ */
+export type RollupFixture = {
+    readonly usage: UsageStore;
+    readonly rollups: UsageRollupStore;
+    readonly seedRun?: (input: {
+        readonly tenantId: TenantId;
+        readonly runId: RunId;
+    }) => Promise<void>;
+};
+export declare function usageRollupStoreConformance(make: () => RollupFixture | Promise<RollupFixture>): void;
+//# sourceMappingURL=rollups.d.ts.map