@retinue/agentkit 0.1.0 → 0.3.0

package/dist/testing/conformance/audio.js

@@ -0,0 +1,145 @@
+/**
+ * Audio provider conformance — REQ-062 (#257), task #258, AC-7.
+ *
+ * ## Why this is not in the storage suite
+ *
+ * AC-7 asks for these ports to be "covered by the conformance suite, consistent with the other 31". The other
+ * 31 are the **storage** conformance suite — `conformance/index.ts` says so in its first line, and every
+ * harness there is handed a store and asserts persistence semantics: a claim, a lease, a version check, a
+ * tenant boundary.
+ *
+ * A transcription provider is not a store. Adding it to that suite would put a non-storage port in a list whose
+ * name and coverage report both say storage, and the next reader would reasonably conclude the audio ports have
+ * a durable backing they do not have.
+ *
+ * So: the same *mechanism* — one shared harness, any adapter must pass it — in its own file, following the
+ * precedent `tools-scrape` already set with `CONTRACT_KEYS`. The intent of the AC is that no adapter gets to
+ * define its own contract, and that is what this enforces.
+ *
+ * ## What it can and cannot assert
+ *
+ * It runs against a **fake** provider by default and against a real one when a caller passes one. That split
+ * is deliberate: the contract is about shape and bounds, which a fake can exercise exhaustively and cheaply,
+ * while "does Whisper actually transcribe" is a live-call question answered once in `audio-live` rather than on
+ * every test run. `#268` is the precedent in the other direction — a *crypto* implementation must be run for
+ * real before shipping, because an untested one is worse than none. A transcription adapter that returns the
+ * wrong text is visibly wrong; one that silently reports no duration is not, which is why duration is the thing
+ * asserted hardest here.
+ */
+import { describe, expect, it } from "vitest";
+import { boundTranscript, MAX_SPEECH_CHARS, MAX_TRANSCRIPT_CHARS } from "../../audio/index.js";
+/** Every key a transcription result must carry. A provider cannot quietly return less. */
+export const TRANSCRIPTION_CONTRACT_KEYS = ["text", "truncated"];
+/** And a speech result. `durationSeconds` is optional on both — absent is a legitimate answer. */
+export const SPEECH_CONTRACT_KEYS = ["audio", "mediaType"];
+/** A tiny valid-looking payload. No provider here decodes it; the fakes do not, and the real one is not run. */
+const SILENCE = new Uint8Array([0xff, 0xfb, 0x90, 0x00, 0x00, 0x00, 0x00, 0x00]);
+export function transcriptionProviderConformance(make) {
+    describe("TranscriptionProvider conformance", () => {
+        it("names itself, so a usage record can say which provider ran", () => {
+            expect(make().id).toBeTruthy();
+        });
+        it("returns every contract key", async () => {
+            const result = await make().transcribe({ audio: SILENCE, mediaType: "audio/mpeg" });
+            for (const key of TRANSCRIPTION_CONTRACT_KEYS) {
+                expect(result, `missing ${key}`).toHaveProperty(key);
+            }
+            expect(typeof result.text).toBe("string");
+            expect(typeof result.truncated).toBe("boolean");
+        });
+        it("reports a duration, because usage is charged on it", async () => {
+            /**
+             * The assertion that matters most, and the one a provider is most likely to fail quietly.
+             *
+             * Audio is billed per second. A provider that omits `durationSeconds` makes every transcription cost
+             * **nothing** in the ledger — under-billing that scales with usage and shows up as a revenue shortfall
+             * rather than as a bug. The OpenAI adapter asks for `verbose_json` specifically to get this field.
+             *
+             * `undefined` is permitted by the type, because some providers genuinely do not report it — but a
+             * provider claiming conformance has to state which it is rather than leaving a caller to find out from an
+             * invoice.
+             */
+            const result = await make().transcribe({ audio: SILENCE, mediaType: "audio/mpeg" });
+            if (result.durationSeconds === undefined) {
+                // Made loud on purpose: this is a costing decision, not a detail.
+                throw new Error("this provider reports no durationSeconds, so its transcriptions will be billed as free. If that is " +
+                    "correct for it, exclude this case explicitly and say why.");
+            }
+            expect(result.durationSeconds).toBeGreaterThan(0);
+        });
+        it("refuses a media type it does not accept, rather than sending it", async () => {
+            // The useful refusal happens locally: a provider answers an unknown container with a message about the
+            // request, not about the format.
+            await expect(make().transcribe({ audio: SILENCE, mediaType: "application/zip" })).rejects.toThrow();
+        });
+        it("bounds the transcript and reports the truncation", async () => {
+            const provider = make();
+            const result = await provider.transcribe({
+                audio: SILENCE,
+                mediaType: "audio/mpeg",
+                maxTranscriptChars: 20,
+            });
+            expect(result.text.length).toBeLessThanOrEqual(20);
+            // If it was cut, it must say so. A shortened transcript claiming to be whole would have a model
+            // summarise a fragment as if it were the entire recording.
+            if (result.text.length === 20)
+                expect(result.truncated).toBe(true);
+        });
+    });
+}
+export function speechProviderConformance(make) {
+    describe("SpeechProvider conformance", () => {
+        it("names itself", () => {
+            expect(make().id).toBeTruthy();
+        });
+        it("returns every contract key, with audio as bytes", async () => {
+            const result = await make().speak({ text: "hello" });
+            for (const key of SPEECH_CONTRACT_KEYS) {
+                expect(result, `missing ${key}`).toHaveProperty(key);
+            }
+            expect(result.audio).toBeInstanceOf(Uint8Array);
+            expect(result.audio.byteLength).toBeGreaterThan(0);
+            expect(result.mediaType).toMatch(/^audio\//);
+        });
+        it("refuses empty text rather than producing silence", async () => {
+            // A zero-length recording is a bill and a file for nothing, and it reads to a user as a broken player.
+            await expect(make().speak({ text: "   " })).rejects.toThrow();
+        });
+        it("refuses text over the ceiling before the call", async () => {
+            // Speech is billed per character, so a runaway prompt is a runaway bill. Refused locally, not by the
+            // provider, because the provider's refusal costs the round trip.
+            await expect(make().speak({ text: "a".repeat(MAX_SPEECH_CHARS + 1) })).rejects.toThrow();
+        });
+        it("honours the requested format in the media type it reports", async () => {
+            const result = await make().speak({ text: "hello", format: "wav" });
+            // Reported, not assumed: a caller storing this as an artifact writes the media type into the file record,
+            // and a wrong one makes the browser refuse to play a file that is perfectly good.
+            expect(result.mediaType).toBe("audio/wav");
+        });
+    });
+}
+/** The transcript bounding, on its own — shared by both suites and worth asserting once. */
+export function transcriptBoundingConformance() {
+    describe("transcript bounding", () => {
+        it("leaves a short transcript alone", () => {
+            expect(boundTranscript("short")).toEqual({ text: "short", truncated: false });
+        });
+        it("cuts at a word boundary when one is near the ceiling", () => {
+            const text = `${"word ".repeat(20)}finalword`;
+            const bounded = boundTranscript(text, 50);
+            expect(bounded.truncated).toBe(true);
+            // Not mid-word: a sliced word reads as a transcription error rather than as a truncation.
+            expect(bounded.text.endsWith(" ")).toBe(false);
+            expect(text.startsWith(bounded.text)).toBe(true);
+        });
+        it("still cuts when there is no word boundary to use", () => {
+            const bounded = boundTranscript("a".repeat(200), 50);
+            expect(bounded.text).toHaveLength(50);
+            expect(bounded.truncated).toBe(true);
+        });
+        it("defaults to the documented ceiling", () => {
+            expect(boundTranscript("x".repeat(MAX_TRANSCRIPT_CHARS + 10)).text).toHaveLength(MAX_TRANSCRIPT_CHARS);
+        });
+    });
+}
+//# sourceMappingURL=audio.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * Capability gating for the conformance suite — `docs/02` → capability declarations.
+ *
+ * A harness block may be skipped **only** when the adapter declares the capability absent via
+ * `AdapterCapability`. An unconditional `it.skip` is not permitted: a silent skip is how a suite
+ * comes to look green while verifying nothing, which is exactly the failure #91 exists to close.
+ *
+ * `gatedIt` therefore always registers a test. When the capability is missing it registers a
+ * *passing* test whose name carries the declared reason, so the skip is visible in the report
+ * rather than absent from it.
+ */
+import type { AdapterCapability } from "../../persistence/index.js";
+/** What an adapter tells the suite about itself. Absent ⇒ treated as "declares nothing". */
+export type AdapterDeclaration = {
+    readonly capabilities?: readonly AdapterCapability[];
+};
+export declare const declares: (declaration: AdapterDeclaration | undefined, capability: AdapterCapability) => boolean;
+/**
+ * Register a test that runs only when the adapter declares `capability`. When it does not, the
+ * test still appears in the report, named with the reason — a visible, attributable skip.
+ */
+export declare const gatedIt: (declaration: AdapterDeclaration | undefined, capability: AdapterCapability, name: string, fn: () => Promise<void> | void) => void;
+//# sourceMappingURL=capability.d.ts.map

package/dist/testing/conformance/capability.js

@@ -0,0 +1,27 @@
+/**
+ * Capability gating for the conformance suite — `docs/02` → capability declarations.
+ *
+ * A harness block may be skipped **only** when the adapter declares the capability absent via
+ * `AdapterCapability`. An unconditional `it.skip` is not permitted: a silent skip is how a suite
+ * comes to look green while verifying nothing, which is exactly the failure #91 exists to close.
+ *
+ * `gatedIt` therefore always registers a test. When the capability is missing it registers a
+ * *passing* test whose name carries the declared reason, so the skip is visible in the report
+ * rather than absent from it.
+ */
+import { it } from "vitest";
+export const declares = (declaration, capability) => (declaration?.capabilities ?? []).includes(capability);
+/**
+ * Register a test that runs only when the adapter declares `capability`. When it does not, the
+ * test still appears in the report, named with the reason — a visible, attributable skip.
+ */
+export const gatedIt = (declaration, capability, name, fn) => {
+    if (declares(declaration, capability)) {
+        it(name, fn);
+        return;
+    }
+    it(`${name} [skipped: adapter does not declare "${capability}"]`, () => {
+        // Intentionally empty: the assertion is the printed reason. See the module docstring.
+    });
+};
+//# sourceMappingURL=capability.js.map

package/dist/testing/conformance/checkpoint-store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `CheckpointStore` conformance — `docs/04` → durable execution. The port documents `save` as
+ * **monotonic**: "a save with a lower sequence is ignored". That is what stops a slow in-flight
+ * write from rewinding a recovered run, so every adapter must agree on it.
+ *
+ * **Referential integrity (#95).** A checkpoint belongs to a run, and an adapter is entitled to
+ * enforce that — the Postgres schema does, with a foreign key, because an orphan checkpoint is
+ * meaningless. The in-memory adapter holds no such constraint. The fixture may therefore supply
+ * `seedRun`, via the shared `parents` helper (#96 generalised what started here); adapters without
+ * referential integrity omit it and nothing changes for them.
+ */
+import type { CheckpointStore } from "../../persistence/index.js";
+import { type FixtureOrStore } from "./parents.js";
+export declare function checkpointStoreConformance(makeFixture: () => FixtureOrStore<CheckpointStore>): void;
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/testing/conformance/checkpoint-store.js

@@ -0,0 +1,72 @@
+/**
+ * `CheckpointStore` conformance — `docs/04` → durable execution. The port documents `save` as
+ * **monotonic**: "a save with a lower sequence is ignored". That is what stops a slow in-flight
+ * write from rewinding a recovered run, so every adapter must agree on it.
+ *
+ * **Referential integrity (#95).** A checkpoint belongs to a run, and an adapter is entitled to
+ * enforce that — the Postgres schema does, with a foreign key, because an orphan checkpoint is
+ * meaningless. The in-memory adapter holds no such constraint. The fixture may therefore supply
+ * `seedRun`, via the shared `parents` helper (#96 generalised what started here); adapters without
+ * referential integrity omit it and nothing changes for them.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { emptyCheckpoint } from "../../runtime/checkpoint.js";
+import { withRun } from "./parents.js";
+const T1 = asId("conf-tenant-1");
+const T2 = asId("conf-tenant-2");
+const RUN = asId("conf-run-1");
+const at = (runId, sequence, step = 0) => ({
+    ...emptyCheckpoint(runId, `2020-01-01T00:00:${String(sequence).padStart(2, "0")}.000Z`),
+    sequence,
+    step,
+});
+export function checkpointStoreConformance(makeFixture) {
+    const open = (runIds = [{ tenantId: T1, runId: RUN }]) => withRun(makeFixture(), runIds);
+    describe("CheckpointStore conformance", () => {
+        it("returns null before anything is saved", async () => {
+            const store = await open();
+            expect(await store.latest({ tenantId: T1, runId: RUN })).toBeNull();
+        });
+        it("saves and returns the checkpoint", async () => {
+            const store = await open();
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 5, 2) });
+            expect(await store.latest({ tenantId: T1, runId: RUN })).toMatchObject({ sequence: 5, step: 2 });
+        });
+        it("advances on a higher sequence", async () => {
+            const store = await open();
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 5) });
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 9) });
+            expect((await store.latest({ tenantId: T1, runId: RUN }))?.sequence).toBe(9);
+        });
+        it("ignores a save with a lower sequence — monotonic, so recovery never rewinds", async () => {
+            const store = await open();
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 9) });
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 4) });
+            expect((await store.latest({ tenantId: T1, runId: RUN }))?.sequence).toBe(9);
+        });
+        it("treats an equal sequence as a no-op rather than an error", async () => {
+            const store = await open();
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 7, 1) });
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 7, 1) });
+            expect((await store.latest({ tenantId: T1, runId: RUN }))?.sequence).toBe(7);
+        });
+        it("round-trips pendingToolCalls, which recovery reconciles against", async () => {
+            const store = await open();
+            const checkpoint = {
+                ...at(RUN, 3),
+                pendingToolCalls: [{ toolCallId: asId("tc1"), toolName: "search_web", startedAt: "2020-01-01T00:00:03.000Z" }],
+            };
+            await store.save({ tenantId: T1, checkpoint });
+            const latest = await store.latest({ tenantId: T1, runId: RUN });
+            expect(latest?.pendingToolCalls).toHaveLength(1);
+            expect(latest?.pendingToolCalls[0]?.toolName).toBe("search_web");
+        });
+        it("enforces tenant isolation", async () => {
+            const store = await open();
+            await store.save({ tenantId: T1, checkpoint: at(RUN, 5) });
+            expect(await store.latest({ tenantId: T2, runId: RUN })).toBeNull();
+        });
+    });
+}
+//# sourceMappingURL=checkpoint-store.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * `ConnectionStore` conformance — REQ-063 (#259), task #261.
+ *
+ * Every clause here is a defect somebody would otherwise ship, and two of them are the reason the port exists
+ * at all: a store that leaked across tenants would hand one customer another's credential, and a store that
+ * kept a revoked connection readable would let a withdrawn credential be used once more.
+ *
+ * The store never sees plaintext, so this suite never supplies any: it seals nothing and asserts nothing about
+ * encryption. That belongs to `SecretCipher`'s own tests and to the raw-row assertion, which needs a real
+ * database and lives with the adapter.
+ */
+import type { ConnectionStore } from "../../connections/index.js";
+export declare function connectionStoreConformance(makeStore: () => ConnectionStore | Promise<ConnectionStore>): void;
+//# sourceMappingURL=connections.d.ts.map

package/dist/testing/conformance/connections.js

@@ -0,0 +1,171 @@
+/**
+ * `ConnectionStore` conformance — REQ-063 (#259), task #261.
+ *
+ * Every clause here is a defect somebody would otherwise ship, and two of them are the reason the port exists
+ * at all: a store that leaked across tenants would hand one customer another's credential, and a store that
+ * kept a revoked connection readable would let a withdrawn credential be used once more.
+ *
+ * The store never sees plaintext, so this suite never supplies any: it seals nothing and asserts nothing about
+ * encryption. That belongs to `SecretCipher`'s own tests and to the raw-row assertion, which needs a real
+ * database and lives with the adapter.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+const sealed = (marker) => ({
+    keyId: "k1",
+    algorithm: "aes-256-gcm",
+    nonce: Buffer.alloc(12, 1).toString("base64"),
+    ciphertext: Buffer.from(`sealed-${marker}`).toString("base64"),
+});
+const connection = (over) => ({
+    provider: "github",
+    mode: "token",
+    scheme: "bearer",
+    sealed: sealed(over.id),
+    ...over,
+});
+export function connectionStoreConformance(makeStore) {
+    describe("ConnectionStore conformance", () => {
+        const T1 = asId("conn-t1");
+        const T2 = asId("conn-t2");
+        it("creates and reads back, scoped to its tenant", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1", label: "Acme org" }) });
+            const read = await store.get({ tenantId: T1, id: "c1" });
+            expect(read).toMatchObject({ id: "c1", provider: "github", label: "Acme org", scheme: "bearer" });
+            expect(read?.sealed.ciphertext).toBe(sealed("c1").ciphertext);
+            expect(read?.createdAt).toBeTruthy();
+        });
+        it("returns null for another tenant's connection", async () => {
+            // Indistinguishable from absent, so the store cannot be used to probe which ids exist — and, far worse,
+            // cannot hand T2 a credential belonging to T1.
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            expect(await store.get({ tenantId: T2, id: "c1" })).toBeNull();
+        });
+        it("lists only this tenant's live connections", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "a" }) });
+            await store.create({ tenantId: T2, connection: connection({ id: "b" }) });
+            expect((await store.list({ tenantId: T1 })).map((c) => c.id)).toEqual(["a"]);
+        });
+        it("allows several connections to one provider for one tenant", async () => {
+            // A customer with three GitHub organisations is the normal case, not an edge one.
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "org-a", label: "A" }) });
+            await store.create({ tenantId: T1, connection: connection({ id: "org-b", label: "B" }) });
+            expect((await store.list({ tenantId: T1, provider: "github" })).map((c) => c.id)).toEqual(["org-a", "org-b"]);
+        });
+        it("narrows a listing by provider", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "gh" }) });
+            await store.create({ tenantId: T1, connection: connection({ id: "sl", provider: "slack" }) });
+            expect((await store.list({ tenantId: T1, provider: "slack" })).map((c) => c.id)).toEqual(["sl"]);
+        });
+        it("orders a listing stably, so a default connection does not move", async () => {
+            // The resolver's default is "the oldest", which is only stable if the order is. Newest-first would
+            // silently re-point every agent the moment somebody connects a second account.
+            const store = await makeStore();
+            for (const id of ["first", "second", "third"]) {
+                await store.create({ tenantId: T1, connection: connection({ id }) });
+            }
+            const once = (await store.list({ tenantId: T1 })).map((c) => c.id);
+            const twice = (await store.list({ tenantId: T1 })).map((c) => c.id);
+            expect(once).toEqual(twice);
+            expect(once[0]).toBe("first");
+        });
+        it("refuses to create the same id twice rather than overwriting", async () => {
+            // Silently overwriting is the worst resolution of a duplicate: it replaces a working credential with
+            // whatever the second caller had.
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await expect(store.create({ tenantId: T1, connection: connection({ id: "c1" }) })).rejects.toThrow();
+        });
+        it("updates the secret, which is what a refresh does", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            const updated = await store.update({ tenantId: T1, id: "c1", patch: { sealed: sealed("rotated") } });
+            expect(updated.sealed.ciphertext).toBe(sealed("rotated").ciphertext);
+            expect((await store.get({ tenantId: T1, id: "c1" }))?.sealed.ciphertext).toBe(sealed("rotated").ciphertext);
+        });
+        it("leaves unpatched fields alone", async () => {
+            // An absent field means "leave it", not "set it to null" — otherwise a label-only rename would wipe the
+            // credential.
+            const store = await makeStore();
+            await store.create({
+                tenantId: T1,
+                connection: connection({ id: "c1", label: "before", metadata: { cloudId: "x" } }),
+            });
+            const updated = await store.update({ tenantId: T1, id: "c1", patch: { label: "after" } });
+            expect(updated.label).toBe("after");
+            expect(updated.metadata?.cloudId).toBe("x");
+            expect(updated.sealed.ciphertext).toBe(sealed("c1").ciphertext);
+        });
+        it("refuses to update another tenant's connection", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await expect(store.update({ tenantId: T2, id: "c1", patch: { label: "mine now" } })).rejects.toThrow();
+        });
+        it("makes a revoked connection unreadable, while keeping the row", async () => {
+            // The audit trail survives — "who connected this and when was it removed" is a question a security review
+            // asks — and the credential does not resolve.
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await store.revoke({ tenantId: T1, id: "c1" });
+            expect(await store.get({ tenantId: T1, id: "c1" })).toBeNull();
+            expect(await store.list({ tenantId: T1 })).toEqual([]);
+        });
+        it("treats revoking twice as success", async () => {
+            // A retried disconnect should not have to distinguish "already gone" from "failed".
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await store.revoke({ tenantId: T1, id: "c1" });
+            await expect(store.revoke({ tenantId: T1, id: "c1" })).resolves.toBeUndefined();
+        });
+        it("refuses to revoke another tenant's connection", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await expect(store.revoke({ tenantId: T2, id: "c1" })).rejects.toThrow();
+        });
+        it("refuses to update a revoked connection", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "c1" }) });
+            await store.revoke({ tenantId: T1, id: "c1" });
+            await expect(store.update({ tenantId: T1, id: "c1", patch: { label: "back" } })).rejects.toThrow();
+        });
+        it("purges one tenant's connections and only that tenant's", async () => {
+            // `docs/18`. A soft-deleted credential is still a credential, so deletion has to be real — and it has to
+            // stop at the tenant boundary, or a retention job for one customer removes another's access.
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "a" }) });
+            await store.create({ tenantId: T1, connection: connection({ id: "b" }) });
+            await store.create({ tenantId: T2, connection: connection({ id: "c" }) });
+            expect(await store.purge({ tenantId: T1 })).toBe(2);
+            expect(await store.list({ tenantId: T1 })).toEqual([]);
+            expect((await store.list({ tenantId: T2 })).map((x) => x.id)).toEqual(["c"]);
+        });
+        it("purges revoked connections too, since a retention promise covers them", async () => {
+            const store = await makeStore();
+            await store.create({ tenantId: T1, connection: connection({ id: "a" }) });
+            await store.revoke({ tenantId: T1, id: "a" });
+            expect(await store.purge({ tenantId: T1 })).toBe(1);
+        });
+        it("round-trips metadata and granted scopes without reshaping them", async () => {
+            // Both are read on the request path — the cloud id goes into the URL, the scopes decide whether to tell
+            // somebody to reconnect — so a store that dropped or reordered them would break the call, not the listing.
+            const store = await makeStore();
+            await store.create({
+                tenantId: T1,
+                connection: connection({
+                    id: "c1",
+                    metadata: { cloudId: "abc", username: "me@example.com" },
+                    grantedScopes: ["read:issues", "write:issues"],
+                }),
+            });
+            const read = await store.get({ tenantId: T1, id: "c1" });
+            expect(read?.metadata).toEqual({ cloudId: "abc", username: "me@example.com" });
+            expect(read?.grantedScopes).toEqual(["read:issues", "write:issues"]);
+        });
+    });
+}
+//# sourceMappingURL=connections.js.map

package/dist/testing/conformance/conversation-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared storage conformance harness — `docs/02` "Conformance suite".
+ *
+ * Every `ConversationStore` adapter (memory today, Postgres/Supabase later) must pass the same
+ * suite, so "swap the database" is provably safe. Adapter packages call this from a test file.
+ * Not part of the published build (excluded in tsconfig); imported by tests only.
+ */
+import type { ConversationStore } from "../../persistence/index.js";
+export declare function conversationStoreConformance(makeStore: () => ConversationStore): void;
+//# sourceMappingURL=conversation-store.d.ts.map

package/dist/testing/conformance/conversation-store.js

@@ -0,0 +1,60 @@
+/**
+ * Shared storage conformance harness — `docs/02` "Conformance suite".
+ *
+ * Every `ConversationStore` adapter (memory today, Postgres/Supabase later) must pass the same
+ * suite, so "swap the database" is provably safe. Adapter packages call this from a test file.
+ * Not part of the published build (excluded in tsconfig); imported by tests only.
+ */
+import { describe, expect, it } from "vitest";
+export function conversationStoreConformance(makeStore) {
+    const t1 = "tenant-1";
+    const t2 = "tenant-2";
+    const cid = (s) => s;
+    describe("ConversationStore conformance", () => {
+        it("create then findById returns the row, scoped to its tenant", async () => {
+            const store = makeStore();
+            const created = await store.create({ tenantId: t1, id: cid("c1"), title: "Hello" });
+            expect(created).toMatchObject({ id: "c1", tenantId: t1, title: "Hello", version: 1 });
+            expect(await store.findById({ tenantId: t1, id: cid("c1") })).toMatchObject({ id: "c1" });
+        });
+        it("enforces tenant isolation", async () => {
+            const store = makeStore();
+            await store.create({ tenantId: t1, id: cid("c1"), title: "t1 only" });
+            expect(await store.findById({ tenantId: t2, id: cid("c1") })).toBeNull();
+            expect((await store.list({ tenantId: t2, limit: 10 })).items).toHaveLength(0);
+        });
+        it("rejects a duplicate id", async () => {
+            const store = makeStore();
+            await store.create({ tenantId: t1, id: cid("c1"), title: "a" });
+            await expect(store.create({ tenantId: t1, id: cid("c1"), title: "b" })).rejects.toThrow();
+        });
+        it("paginates by stable cursor", async () => {
+            const store = makeStore();
+            for (const n of [1, 2, 3, 4, 5])
+                await store.create({ tenantId: t1, id: cid(`c${n}`), title: `#${n}` });
+            const first = await store.list({ tenantId: t1, limit: 2 });
+            expect(first.items).toHaveLength(2);
+            expect(first.nextCursor).toBeDefined();
+            const second = await store.list({ tenantId: t1, limit: 2, cursor: first.nextCursor });
+            expect(second.items).toHaveLength(2);
+            // no overlap between pages
+            const ids = new Set(first.items.map((c) => c.id));
+            expect(second.items.some((c) => ids.has(c.id))).toBe(false);
+        });
+        it("optimistic concurrency: a stale expectedVersion is rejected", async () => {
+            const store = makeStore();
+            await store.create({ tenantId: t1, id: cid("c1"), title: "v1" });
+            const updated = await store.update({ tenantId: t1, id: cid("c1"), expectedVersion: 1, patch: { title: "v2" } });
+            expect(updated.version).toBe(2);
+            await expect(store.update({ tenantId: t1, id: cid("c1"), expectedVersion: 1, patch: { title: "stale" } })).rejects.toThrow();
+        });
+        it("soft delete hides the row from findById and list", async () => {
+            const store = makeStore();
+            await store.create({ tenantId: t1, id: cid("c1"), title: "bye" });
+            await store.softDelete({ tenantId: t1, id: cid("c1") });
+            expect(await store.findById({ tenantId: t1, id: cid("c1") })).toBeNull();
+            expect((await store.list({ tenantId: t1, limit: 10 })).items).toHaveLength(0);
+        });
+    });
+}
+//# sourceMappingURL=conversation-store.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * `EvaluationStore` conformance (#141).
+ *
+ * The cases are mostly about *aggregates agreeing with their evidence* and about *idempotency*, because those
+ * are what a release gate depends on: a mean that disagrees with its case rows is a number nobody can defend,
+ * and a double-counted case makes the gate pass or fail for the wrong reason.
+ */
+import type { EvaluationStore } from "../../persistence/index.js";
+export declare function evaluationStoreConformance(make: () => EvaluationStore | Promise<EvaluationStore>): void;
+//# sourceMappingURL=evaluation.d.ts.map