@retinue/agentkit 0.2.0 → 0.3.1

package/dist/testing/conformance/artifacts.js

@@ -0,0 +1,316 @@
+/**
+ * `ArtifactStore` conformance (#133) — AC-6.
+ *
+ * The cases are mostly about **versioning**, because that is the part where two adapters can plausibly
+ * disagree and where disagreeing is expensive: an earlier version that stops resolving is a shared link that
+ * 404s, and a race that silently collapses two regenerations into one is data loss that looks like success.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { withConversation } from "./parents.js";
+const T1 = asId("conf-artifact-tenant-1");
+const T2 = asId("conf-artifact-tenant-2");
+const C1 = asId("conf-artifact-convo-1");
+const C2 = asId("conf-artifact-convo-2");
+const AT = "2026-08-23T12:00:00.000Z";
+const USER = asId("conf-artifact-user");
+const version = (overrides = {}) => ({
+    id: asId(`v-${Math.abs(hash(JSON.stringify(overrides)))}`),
+    contentRef: asId("blob-1"),
+    byteSize: 128,
+    provenance: { producedBy: "create_artifact", inputs: { topic: "q3" } },
+    createdBy: USER,
+    createdAt: AT,
+    ...overrides,
+});
+/** Deterministic, because `Math.random` in a fixture makes a failure unreproducible. */
+const hash = (s) => {
+    let h = 0;
+    for (const ch of s)
+        h = (h * 31 + ch.charCodeAt(0)) | 0;
+    return h;
+};
+const artifact = (overrides = {}) => ({
+    id: asId(overrides.id ?? "a1"),
+    conversationId: overrides.conversationId ?? C1,
+    kind: "markdown",
+    name: overrides.name ?? "Q3 summary",
+    createdAt: AT,
+});
+export function artifactStoreConformance(make) {
+    describe("ArtifactStore conformance", () => {
+        const open = async (conversations = [C1]) => withConversation(await make(), conversations.flatMap((conversationId) => [
+            { tenantId: T1, conversationId },
+            { tenantId: T2, conversationId },
+        ]));
+        it("creates an artifact at version 1 with its content by reference", async () => {
+            // AC-1 and AC-5 together: the row carries a ref, and there is no field content could live in.
+            const store = await open();
+            const created = await store.create({
+                tenantId: T1,
+                artifact: artifact(),
+                version: version({ id: asId("v1"), contentRef: asId("blob-a") }),
+            });
+            expect(created).toMatchObject({ id: "a1", name: "Q3 summary", kind: "markdown", latestVersion: 1 });
+            const v1 = await store.getVersion({ tenantId: T1, id: asId("a1") });
+            expect(v1).toMatchObject({ version: 1, contentRef: "blob-a", byteSize: 128 });
+            // Nothing resembling content on the version row itself.
+            expect(Object.keys(v1 ?? {})).not.toContain("content");
+        });
+        it("refuses to create the same id twice", async () => {
+            // Overwriting would repoint a name at different content while leaving the old versions attached to it.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            await expect(store.create({ tenantId: T1, artifact: artifact(), version: version() })).rejects.toMatchObject({ code: "conflict" });
+        });
+        it("returns null for another tenant's artifact", async () => {
+            // Indistinguishable from absent, so the endpoint cannot be used to probe which ids exist.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            expect(await store.get({ tenantId: T2, id: asId("a1") })).toBeNull();
+            expect(await store.getVersion({ tenantId: T2, id: asId("a1") })).toBeNull();
+        });
+        it("makes a new version the default and keeps the earlier one resolvable", async () => {
+            // AC-2, both halves. The second half is the one that breaks quietly: an implementation that overwrote
+            // would pass every assertion about the *new* version.
+            const store = await open();
+            await store.create({
+                tenantId: T1,
+                artifact: artifact(),
+                version: version({ id: asId("v1"), contentRef: asId("blob-1") }),
+            });
+            const added = await store.addVersion({
+                tenantId: T1,
+                id: asId("a1"),
+                expectedLatestVersion: 1,
+                version: version({
+                    id: asId("v2"),
+                    contentRef: asId("blob-2"),
+                    createdAt: "2026-08-23T13:00:00.000Z",
+                }),
+            });
+            expect(added).toEqual({ added: true, version: 2 });
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ latestVersion: 2 });
+            // No version asked for: the current one.
+            expect(await store.getVersion({ tenantId: T1, id: asId("a1") })).toMatchObject({
+                version: 2,
+                contentRef: "blob-2",
+            });
+            // Asked for by number: still there, still pointing at its own content.
+            expect(await store.getVersion({ tenantId: T1, id: asId("a1"), version: 1 })).toMatchObject({
+                version: 1,
+                contentRef: "blob-1",
+            });
+        });
+        it("lets exactly one of two racing regenerations win", async () => {
+            // Both hold `expectedLatestVersion: 1`. Without the compare both become version 2 and one silently
+            // replaces the other -- which is AC-2 failing in the way nobody notices.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            const results = await Promise.all([
+                store.addVersion({
+                    tenantId: T1,
+                    id: asId("a1"),
+                    expectedLatestVersion: 1,
+                    version: version({ id: asId("race-a") }),
+                }),
+                store.addVersion({
+                    tenantId: T1,
+                    id: asId("a1"),
+                    expectedLatestVersion: 1,
+                    version: version({ id: asId("race-b") }),
+                }),
+            ]);
+            expect(results.filter((r) => r.added)).toHaveLength(1);
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ latestVersion: 2 });
+        });
+        it("refuses a version whose expected latest is stale", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            const result = await store.addVersion({
+                tenantId: T1,
+                id: asId("a1"),
+                // Wrong on purpose: a caller working from a read that has since moved on.
+                expectedLatestVersion: 7,
+                version: version({ id: asId("stale") }),
+            });
+            expect(result).toEqual({ added: false });
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ latestVersion: 1 });
+        });
+        it("does not add a version to another tenant's artifact", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            const result = await store.addVersion({
+                tenantId: T2,
+                id: asId("a1"),
+                expectedLatestVersion: 1,
+                version: version({ id: asId("cross") }),
+            });
+            expect(result).toEqual({ added: false });
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ latestVersion: 1 });
+        });
+        it("records the conversation, run and inputs that produced a version", async () => {
+            // AC-3. Every field, because provenance is stored as one JSON value and a mapper that dropped part of
+            // it would still return a plausible record.
+            const store = await open();
+            await store.create({
+                tenantId: T1,
+                artifact: artifact(),
+                version: version({
+                    id: asId("v1"),
+                    provenance: {
+                        runId: asId("run-7"),
+                        producedBy: "summarize_document",
+                        inputs: { fileId: "file-3", sections: ["revenue"] },
+                        sourceFileIds: [asId("file-3")],
+                    },
+                }),
+            });
+            const v1 = await store.getVersion({ tenantId: T1, id: asId("a1") });
+            // The conversation comes from the artifact -- it owns the artifact, so duplicating it per version would
+            // be a second place for it to disagree.
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({
+                conversationId: C1,
+            });
+            expect(v1?.provenance).toEqual({
+                runId: "run-7",
+                producedBy: "summarize_document",
+                inputs: { fileId: "file-3", sections: ["revenue"] },
+                sourceFileIds: ["file-3"],
+            });
+        });
+        it("lists a conversation's artifacts, newest cursor last", async () => {
+            const store = await open([C1, C2]);
+            await store.create({
+                tenantId: T1,
+                artifact: artifact({ id: "a1", name: "first" }),
+                version: version({ id: asId("v-a1") }),
+            });
+            await store.create({
+                tenantId: T1,
+                artifact: artifact({ id: "a2", name: "second" }),
+                version: version({ id: asId("v-a2"), createdAt: "2026-08-23T13:00:00.000Z" }),
+            });
+            await store.create({
+                tenantId: T1,
+                artifact: artifact({ id: "a3", conversationId: C2, name: "elsewhere" }),
+                version: version({ id: asId("v-a3") }),
+            });
+            const page = await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 });
+            expect(page.items.map((a) => a.id).sort()).toEqual(["a1", "a2"]);
+        });
+        it("pages a listing on a keyset cursor rather than an offset", async () => {
+            // An offset cursor shifts when a row is inserted, so a caller paging while an artifact is created
+            // either sees one twice or misses one.
+            const store = await open();
+            for (const n of [1, 2, 3, 4, 5]) {
+                await store.create({
+                    tenantId: T1,
+                    artifact: { ...artifact({ id: `a${n}` }), createdAt: `2026-08-23T1${n}:00:00.000Z` },
+                    version: version({ id: asId(`v-a${n}`), createdAt: `2026-08-23T1${n}:00:00.000Z` }),
+                });
+            }
+            const seen = [];
+            let cursor;
+            do {
+                const page = await store.listByConversation({
+                    tenantId: T1,
+                    conversationId: C1,
+                    limit: 2,
+                    ...(cursor === undefined ? {} : { cursor }),
+                });
+                seen.push(...page.items.map((a) => a.id));
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            expect(seen).toEqual(["a1", "a2", "a3", "a4", "a5"]);
+        });
+        it("lists every version in order, oldest first", async () => {
+            // The history a restore reads. Order matters more here than anywhere else in this port.
+            const store = await open();
+            await store.create({
+                tenantId: T1,
+                artifact: artifact(),
+                version: version({ id: asId("v1") }),
+            });
+            for (const n of [2, 3, 4]) {
+                await store.addVersion({
+                    tenantId: T1,
+                    id: asId("a1"),
+                    expectedLatestVersion: n - 1,
+                    // Every version created in the same millisecond: a timestamp keyset would tie, and the version
+                    // number cannot.
+                    version: version({ id: asId(`v${n}`), createdAt: AT }),
+                });
+            }
+            const seen = [];
+            let cursor;
+            do {
+                const page = await store.listVersions({
+                    tenantId: T1,
+                    id: asId("a1"),
+                    limit: 2,
+                    ...(cursor === undefined ? {} : { cursor }),
+                });
+                seen.push(...page.items.map((v) => v.version));
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            expect(seen).toEqual([1, 2, 3, 4]);
+        });
+        it("returns no versions for another tenant's artifact", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            expect((await store.listVersions({ tenantId: T2, id: asId("a1"), limit: 10 })).items).toEqual([]);
+        });
+        it("hides a soft-deleted artifact from the conversation listing but keeps it resolvable", async () => {
+            // Both halves. The row is kept precisely so a shared link resolves to "deleted" rather than to nothing,
+            // and a listing that still showed it would be a deleted document coming back.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            expect(await store.softDelete({ tenantId: T1, id: asId("a1"), at: AT })).toEqual({
+                deleted: true,
+            });
+            expect((await store.listByConversation({ tenantId: T1, conversationId: C1, limit: 10 })).items).toEqual([]);
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ deletedAt: AT });
+        });
+        it("keeps the first deletion timestamp when deleted again", async () => {
+            // "When was this deleted" must not move every time someone clicks again.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            await store.softDelete({ tenantId: T1, id: asId("a1"), at: AT });
+            await store.softDelete({
+                tenantId: T1,
+                id: asId("a1"),
+                at: "2026-08-24T12:00:00.000Z",
+            });
+            expect(await store.get({ tenantId: T1, id: asId("a1") })).toMatchObject({ deletedAt: AT });
+        });
+        it("does not delete another tenant's artifact", async () => {
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            expect(await store.softDelete({ tenantId: T2, id: asId("a1"), at: AT })).toEqual({
+                deleted: false,
+            });
+            expect((await store.get({ tenantId: T1, id: asId("a1") }))?.deletedAt).toBeUndefined();
+        });
+        it("adds no version to a deleted artifact", async () => {
+            // A new version would resurrect it in every listing that filters through the artifact row.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            await store.softDelete({ tenantId: T1, id: asId("a1"), at: AT });
+            expect(await store.addVersion({
+                tenantId: T1,
+                id: asId("a1"),
+                expectedLatestVersion: 1,
+                version: version({ id: asId("after-delete") }),
+            })).toEqual({ added: false });
+        });
+        it("rejects a non-timestamp `at` rather than storing it", async () => {
+            // The lesson from #129: a reference adapter laxer than the real one turns a production write failure
+            // into a passing test.
+            const store = await open();
+            await store.create({ tenantId: T1, artifact: artifact(), version: version() });
+            await expect(store.softDelete({ tenantId: T1, id: asId("a1"), at: "t" })).rejects.toThrow();
+        });
+    });
+}
+//# sourceMappingURL=artifacts.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * 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 type { SpeechProvider, TranscriptionProvider } from "../../audio/index.js";
+/** Every key a transcription result must carry. A provider cannot quietly return less. */
+export declare const TRANSCRIPTION_CONTRACT_KEYS: readonly ["text", "truncated"];
+/** And a speech result. `durationSeconds` is optional on both — absent is a legitimate answer. */
+export declare const SPEECH_CONTRACT_KEYS: readonly ["audio", "mediaType"];
+export declare function transcriptionProviderConformance(make: () => TranscriptionProvider): void;
+export declare function speechProviderConformance(make: () => SpeechProvider): void;
+/** The transcript bounding, on its own — shared by both suites and worth asserting once. */
+export declare function transcriptBoundingConformance(): void;
+//# sourceMappingURL=audio.d.ts.map

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