@retinue/agentkit 0.1.0 → 0.3.0

package/dist/skills/index.d.ts

@@ -63,5 +63,7 @@ export interface SkillResolver {
         version: number;
     }): Promise<SkillVersion>;
 }
+export * from "./catalogue.js";
+export * from "./context.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -27,5 +27,7 @@ export const SKILL_LIMITS = {
     /** Per run, to bound what `load_skill` can pull into context. */
     maxLoadedPerRun: 5,
 };
+export * from "./catalogue.js";
+export * from "./context.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.js.map

package/dist/telemetry/spans.js

@@ -36,8 +36,25 @@ export const SPAN_FOR_RUN_EVENT = {
     "question.answered": "hitl.question",
     "approval.requested": "hitl.approval",
     "approval.decided": "hitl.approval",
+    // Its own span rather than `hitl.approval`: both pause a run for a person, and the questions they answer are
+    // different — "may I do this" versus "I have no access, grant me some" — so a trace that merged them would
+    // make "how often do runs stall on a missing connection" unanswerable.
+    "connection.requested": "hitl.connection",
+    "connection.completed": "hitl.connection",
     "usage.updated": "run.step",
     "context.compacted": "context.compact",
+    // Its own span, not `run.step`: a guardrail verdict is the boundary of a decision somebody will need to find
+    // later — "what stopped this turn" is the question a trace gets opened to answer.
+    "guardrail.verdict": "guardrail.inspect",
+    /**
+     * Its own span, and the reason is a rule this repository enforces: a span shares its first word with its
+     * event unless it is deliberately folded into `run.step`.
+     *
+     * `context.compact` was the first choice — dropping tools to fit a budget is the same *kind* of act as
+     * dropping history to fit one — and `telemetry.test.ts` rejected it. Correctly: an operator searching traces
+     * for why a turn was short of tools would not find it filed under context compaction.
+     */
+    "catalog.truncated": "catalog.truncate",
 };
 /**
  * The spans that are *not* run events.

package/dist/testing/conformance/artifact-exports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `ArtifactExportStore` conformance (#134).
+ *
+ * Almost entirely about `claim`, because that is the method whose contract two adapters can plausibly get
+ * differently and where differing is expensive: a claim that is not exclusive renders the same PDF twice and
+ * leaves two rows pointing at two identical files, and a caller has no way to tell which is canonical.
+ */
+import type { ArtifactId, ConversationId, TenantId } from "../../core/ids.js";
+import type { ArtifactExportStore } from "../../persistence/index.js";
+import { type Fixture, type FixtureOrStore } from "./parents.js";
+/** The parent an adapter with a foreign key needs: an artifact, which itself needs a conversation. */
+export type ExportFixture = Fixture<ArtifactExportStore> & {
+    readonly seedArtifact?: (input: {
+        readonly tenantId: TenantId;
+        readonly artifactId: ArtifactId;
+        readonly conversationId: ConversationId;
+    }) => Promise<void>;
+};
+export declare function artifactExportStoreConformance(make: () => FixtureOrStore<ArtifactExportStore> | Promise<FixtureOrStore<ArtifactExportStore>>): void;
+//# sourceMappingURL=artifact-exports.d.ts.map

package/dist/testing/conformance/artifact-exports.js

@@ -0,0 +1,172 @@
+/**
+ * `ArtifactExportStore` conformance (#134).
+ *
+ * Almost entirely about `claim`, because that is the method whose contract two adapters can plausibly get
+ * differently and where differing is expensive: a claim that is not exclusive renders the same PDF twice and
+ * leaves two rows pointing at two identical files, and a caller has no way to tell which is canonical.
+ */
+import { describe, expect, it } from "vitest";
+import { asId } from "../../core/ids.js";
+import { openFixture } from "./parents.js";
+const T1 = asId("conf-export-tenant-1");
+const T2 = asId("conf-export-tenant-2");
+const A1 = asId("conf-export-artifact-1");
+const AT = "2026-08-23T12:00:00.000Z";
+const USER = asId("conf-export-user");
+const requested = (overrides = {}) => ({
+    id: overrides.id ?? "e1",
+    artifactId: A1,
+    version: overrides.version ?? 1,
+    format: overrides.format ?? "pdf",
+    requestedBy: USER,
+    createdAt: AT,
+});
+export function artifactExportStoreConformance(make) {
+    describe("ArtifactExportStore conformance", () => {
+        const open = async () => {
+            const fixture = openFixture(await make());
+            // Both tenants, because every isolation case below needs the parent to exist on both sides — otherwise
+            // a cross-tenant write would fail on the foreign key and look like isolation working.
+            for (const tenantId of [T1, T2]) {
+                await fixture.seedArtifact?.({
+                    tenantId,
+                    artifactId: A1,
+                    conversationId: asId("conf-export-convo-1"),
+                });
+            }
+            return fixture.store;
+        };
+        it("claims a slot and records it pending", async () => {
+            const store = await open();
+            const result = await store.claim({ tenantId: T1, export: requested() });
+            expect(result.claimed).toBe(true);
+            expect(result.export).toMatchObject({ id: "e1", version: 1, format: "pdf", state: "pending" });
+        });
+        it("lets exactly one of two racing claims win, and hands the loser the winner's row", async () => {
+            // The property the whole port exists for. Both callers then read the same row, which is why the loser
+            // gets it rather than an error: its next move is identical either way.
+            const store = await open();
+            const results = await Promise.all([
+                store.claim({ tenantId: T1, export: requested({ id: "race-a" }) }),
+                store.claim({ tenantId: T1, export: requested({ id: "race-b" }) }),
+            ]);
+            expect(results.filter((r) => r.claimed)).toHaveLength(1);
+            const winner = results.find((r) => r.claimed).export;
+            const loser = results.find((r) => !r.claimed).export;
+            expect(loser.id).toBe(winner.id);
+        });
+        it("treats a different format as a different slot", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1", format: "pdf" }) });
+            const second = await store.claim({ tenantId: T1, export: requested({ id: "e2", format: "markdown" }) });
+            expect(second.claimed).toBe(true);
+        });
+        it("treats a different version as a different slot", async () => {
+            // An export is of a *version*. Sharing one across versions would hand someone last week's document.
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1", version: 1 }) });
+            const second = await store.claim({ tenantId: T1, export: requested({ id: "e2", version: 2 }) });
+            expect(second.claimed).toBe(true);
+        });
+        it("does not share a slot across tenants", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1" }) });
+            const other = await store.claim({ tenantId: T2, export: requested({ id: "e2" }) });
+            expect(other.claimed).toBe(true);
+            expect(await store.get({ tenantId: T2, id: "e1" })).toBeNull();
+        });
+        it("records a rendered outcome with its file and checksum", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            expect(await store.complete({
+                tenantId: T1,
+                id: "e1",
+                state: "rendered",
+                fileId: asId("file-1"),
+                byteSize: 2048,
+                checksum: "abc",
+                at: AT,
+            })).toEqual({ recorded: true });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({
+                state: "rendered",
+                fileId: "file-1",
+                byteSize: 2048,
+                checksum: "abc",
+                renderedAt: AT,
+            });
+        });
+        it("records a failure with its reason and message", async () => {
+            // AC-4 depends on both surviving storage: the reason drives behaviour and the message is what the user
+            // reads, so a store keeping one and dropping the other would half-work.
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            await store.complete({
+                tenantId: T1,
+                id: "e1",
+                state: "failed",
+                failureReason: "render-failed",
+                failureMessage: "That artifact could not be rendered.",
+                at: AT,
+            });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({
+                state: "failed",
+                failureReason: "render-failed",
+                failureMessage: "That artifact could not be rendered.",
+            });
+        });
+        it("does not complete another tenant's export", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            // Reported rather than thrown: it is the same answer a deleted row gives, and a worker must be able to
+            // tell "gone" from "broken".
+            expect(await store.complete({ tenantId: T2, id: "e1", state: "rendered", fileId: asId("f"), at: AT })).toEqual({ recorded: false });
+            expect(await store.get({ tenantId: T1, id: "e1" })).toMatchObject({ state: "pending" });
+        });
+        it("finds an export by version and format, which is the cache lookup", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested({ id: "e1" }) });
+            expect(await store.find({ tenantId: T1, artifactId: A1, version: 1, format: "pdf" })).toMatchObject({
+                id: "e1",
+            });
+            expect(await store.find({ tenantId: T1, artifactId: A1, version: 1, format: "markdown" })).toBeNull();
+            expect(await store.find({ tenantId: T2, artifactId: A1, version: 1, format: "pdf" })).toBeNull();
+        });
+        it("lists an artifact's exports, paging on a keyset cursor", async () => {
+            // Two formats requested together share a timestamp, so a cursor on the timestamp alone would skip or
+            // repeat -- which is the normal case here rather than a rare one.
+            const store = await open();
+            for (const n of [1, 2, 3, 4, 5]) {
+                await store.claim({
+                    tenantId: T1,
+                    export: { ...requested({ id: `e${n}`, version: n }), createdAt: AT },
+                });
+            }
+            const seen = [];
+            let cursor;
+            do {
+                const page = await store.listByArtifact({
+                    tenantId: T1,
+                    artifactId: A1,
+                    limit: 2,
+                    ...(cursor === undefined ? {} : { cursor }),
+                });
+                seen.push(...page.items.map((e) => e.id));
+                cursor = page.nextCursor;
+            } while (cursor !== undefined);
+            expect(seen.sort()).toEqual(["e1", "e2", "e3", "e4", "e5"]);
+        });
+        it("lists nothing for another tenant", async () => {
+            const store = await open();
+            await store.claim({ tenantId: T1, export: requested() });
+            expect((await store.listByArtifact({ tenantId: T2, artifactId: A1, limit: 10 })).items).toEqual([]);
+        });
+        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.claim({ tenantId: T1, export: requested() });
+            await expect(store.complete({ tenantId: T1, id: "e1", state: "rendered", fileId: asId("f"), at: "t" })).rejects.toThrow();
+        });
+    });
+}
+//# sourceMappingURL=artifact-exports.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * `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 type { ArtifactStore } from "../../persistence/index.js";
+import { type FixtureOrStore } from "./parents.js";
+export declare function artifactStoreConformance(make: () => FixtureOrStore<ArtifactStore> | Promise<FixtureOrStore<ArtifactStore>>): void;
+//# sourceMappingURL=artifacts.d.ts.map

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