@nymbalhq/contract-tests 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import {
   CONTRACT_KINDS
-} from "./chunk-ABEL44IM.js";
+} from "./chunk-KK53D2KL.js";
 
-// src/ai.ts
+// src/analytics.ts
 import { describe as describe2, expect as expect2, it as it2 } from "vitest";
 
 // src/common.ts
@@ -94,59 +94,24 @@ function healthAndDowntime(build, unreachable, label, operation) {
   });
 }
 
-// src/ai.ts
-function runAiContract(name, build, options = {}) {
-  describe2(`AiAdapter contract: ${name}`, () => {
-    it2(
-      "embed returns embedding vectors with correct dimensions",
-      async () => {
-        const adapter = await build();
-        const embeddings = await adapter.embed(["hello world", "test text"]);
-        expect2(Array.isArray(embeddings)).toBe(true);
-        expect2(embeddings).toHaveLength(2);
-        expect2(Array.isArray(embeddings[0])).toBe(true);
-        expect2((embeddings[0] ?? []).length).toBeGreaterThan(0);
-      },
-      CASE_MS
-    );
-    it2(
-      "complete returns a non-empty string",
-      async () => {
-        const adapter = await build();
-        const result = await adapter.complete("Write one word: hello", { maxTokens: 10 });
-        expect2(typeof result).toBe("string");
-        expect2(result.length).toBeGreaterThan(0);
-      },
-      CASE_MS
-    );
-    healthAndDowntime(
-      build,
-      options.unreachable,
-      "complete()",
-      (adapter) => adapter.complete("Write one word: hello", { maxTokens: 10 })
-    );
-  });
-}
-
 // src/analytics.ts
-import { describe as describe3, expect as expect3, it as it3 } from "vitest";
 function runAnalyticsContract(name, build, options = {}) {
-  describe3(`AnalyticsAdapter contract: ${name}`, () => {
-    it3(
+  describe2(`AnalyticsAdapter contract: ${name}`, () => {
+    it2(
       "track resolves without throwing",
       async () => {
         const adapter = await build();
-        await expect3(
+        await expect2(
           adapter.track("product_viewed", { productId: "prod-1", source: "test" })
         ).resolves.not.toThrow();
       },
       CASE_MS
     );
-    it3(
+    it2(
       "identify resolves without throwing",
       async () => {
         const adapter = await build();
-        await expect3(
+        await expect2(
           adapter.identify("user-1", { email: "test@example.com", plan: "free" })
         ).resolves.not.toThrow();
       },
@@ -162,11 +127,11 @@ function runAnalyticsContract(name, build, options = {}) {
 }
 
 // src/document-store.ts
-import { describe as describe5, expect as expect6, it as it6 } from "vitest";
+import { describe as describe4, expect as expect5, it as it5 } from "vitest";
 
 // src/document-store-model.ts
 import fc from "fast-check";
-import { describe as describe4, expect as expect4, it as it4 } from "vitest";
+import { describe as describe3, expect as expect3, it as it3 } from "vitest";
 import {
   compareDocumentValues,
   matchesSortKey
@@ -296,8 +261,8 @@ async function rejection(promise) {
 }
 var TTL_SECONDS = 1;
 function documentStoreModelCases(make, opts) {
-  describe4("agrees with the reference model", () => {
-    it4(
+  describe3("agrees with the reference model", () => {
+    it3(
       "every query\u2019s page sequence equals the reference: filter by partition and sortKey, order with nulls last and ties by key, slice by limit",
       async () => {
         await fc.assert(
@@ -313,11 +278,11 @@ function documentStoreModelCases(make, opts) {
                 const q = { partition, sortKey, orderBy };
                 const expected = reference(docs, q);
                 const { pages, ended } = await walk(store, q, limit, docs.length + 2);
-                expect4(ended, "the cursor walk never ended").toBe(true);
-                for (const page of pages) expect4(page.length).toBeLessThanOrEqual(limit);
-                expect4(withoutTrailingEmpty(pages.map(idsOf))).toEqual(chunk(expected, limit));
+                expect3(ended, "the cursor walk never ended").toBe(true);
+                for (const page of pages) expect3(page.length).toBeLessThanOrEqual(limit);
+                expect3(withoutTrailingEmpty(pages.map(idsOf))).toEqual(chunk(expected, limit));
                 const byId = new Map(docs.map((d) => [d.id, d]));
-                for (const item of pages.flat()) expect4(item).toEqual(byId.get(item.id));
+                for (const item of pages.flat()) expect3(item).toEqual(byId.get(item.id));
               });
             }
           ),
@@ -326,7 +291,7 @@ function documentStoreModelCases(make, opts) {
       },
       SLOW
     );
-    it4(
+    it3(
       "without orderBy, a cursor walk returns exactly the reference\u2019s matches, each once",
       async () => {
         await fc.assert(
@@ -341,11 +306,11 @@ function documentStoreModelCases(make, opts) {
                 const q = { partition, sortKey, orderBy: void 0 };
                 const { pages, ended } = await walk(store, q, limit, docs.length + 2);
                 const walked = idsOf(pages.flat());
-                expect4(ended, "the cursor walk never ended").toBe(true);
-                expect4(walked.length, `duplicates in ${walked.join(",")}`).toBe(
+                expect3(ended, "the cursor walk never ended").toBe(true);
+                expect3(walked.length, `duplicates in ${walked.join(",")}`).toBe(
                   new Set(walked).size
                 );
-                expect4([...walked].sort()).toEqual(reference(docs, q));
+                expect3([...walked].sort()).toEqual(reference(docs, q));
               });
             }
           ),
@@ -354,7 +319,7 @@ function documentStoreModelCases(make, opts) {
       },
       SLOW
     );
-    it4(
+    it3(
       "a cursor walk across a mid-walk delete returns every remaining match exactly once, in the reference order",
       async () => {
         await fc.assert(
@@ -374,14 +339,14 @@ function documentStoreModelCases(make, opts) {
                   if (n === 1) await store.delete(COLLECTION, deleted);
                 });
                 const walked = idsOf(pages.flat());
-                expect4(ended, "the cursor walk never ended").toBe(true);
-                expect4(walked.length, `duplicates in ${walked.join(",")}`).toBe(
+                expect3(ended, "the cursor walk never ended").toBe(true);
+                expect3(walked.length, `duplicates in ${walked.join(",")}`).toBe(
                   new Set(walked).size
                 );
-                expect4(walked.filter((id) => !expected.includes(id))).toEqual([]);
-                expect4(expected.filter((id) => id !== deleted && !walked.includes(id))).toEqual([]);
+                expect3(walked.filter((id) => !expected.includes(id))).toEqual([]);
+                expect3(expected.filter((id) => id !== deleted && !walked.includes(id))).toEqual([]);
                 if (orderBy !== void 0) {
-                  expect4(walked).toEqual(expected.filter((id) => walked.includes(id)));
+                  expect3(walked).toEqual(expected.filter((id) => walked.includes(id)));
                 }
               });
             }
@@ -391,7 +356,7 @@ function documentStoreModelCases(make, opts) {
       },
       SLOW
     );
-    it4(
+    it3(
       "a cursor issued under one orderBy is refused under another, and continues the walk under its own",
       async () => {
         const generated = ["k1", "k2", "k3", "k4", "k5"].map((key, i) => ({
@@ -408,23 +373,23 @@ function documentStoreModelCases(make, opts) {
             orderBy: { field: "v", direction: "asc" }
           };
           const first = await store.query(COLLECTION, params(asc, 2));
-          expect4(first.nextCursor).not.toBeNull();
+          expect3(first.nextCursor).not.toBeNull();
           const cursor = first.nextCursor;
           const otherDirection = { ...asc, orderBy: { field: "v", direction: "desc" } };
           const otherField = { ...asc, orderBy: { field: "nested.v", direction: "asc" } };
-          expect4(
+          expect3(
             await rejection(store.query(COLLECTION, params(otherDirection, 2, cursor)))
           ).toBeInstanceOf(Error);
-          expect4(
+          expect3(
             await rejection(store.query(COLLECTION, params(otherField, 2, cursor)))
           ).toBeInstanceOf(Error);
           const next = await store.query(COLLECTION, params(asc, 2, cursor));
-          expect4(idsOf(next.items)).toEqual(reference(docs, asc).slice(2, 4));
+          expect3(idsOf(next.items)).toEqual(reference(docs, asc).slice(2, 4));
         });
       },
       SLOW
     );
-    it4(
+    it3(
       "a document put with a TTL is returned until it expires, then by no get, query or batchGet; one put without stays",
       async () => {
         const store = await make();
@@ -434,33 +399,33 @@ function documentStoreModelCases(make, opts) {
           const putAt = Date.now();
           await store.put(COLLECTION, short.id, short, { ttl: TTL_SECONDS });
           await store.put(COLLECTION, long.id, long);
-          expect4(await store.get(COLLECTION, short.id)).toEqual(short);
+          expect3(await store.get(COLLECTION, short.id)).toEqual(short);
           if (opts.clock !== void 0) {
             await opts.clock.advance(TTL_SECONDS * 1e3 - 1);
-            expect4(await store.get(COLLECTION, short.id)).toEqual(short);
+            expect3(await store.get(COLLECTION, short.id)).toEqual(short);
             await opts.clock.advance(2);
           } else {
             const deadline = putAt + TTL_SECONDS * 1e3 + 3e3;
             while (await store.get(COLLECTION, short.id) !== null && Date.now() < deadline) {
               await new Promise((r) => setTimeout(r, 25));
             }
-            expect4(Date.now() - putAt, "expired before its TTL").toBeGreaterThanOrEqual(
+            expect3(Date.now() - putAt, "expired before its TTL").toBeGreaterThanOrEqual(
               TTL_SECONDS * 1e3 - 100
             );
           }
-          expect4(await store.get(COLLECTION, short.id)).toBeNull();
+          expect3(await store.get(COLLECTION, short.id)).toBeNull();
           const all = await store.query(COLLECTION, {
             partitionKey: { field: "part", value: "*" },
             limit: 100
           });
-          expect4(idsOf(all.items)).toEqual([long.id]);
+          expect3(idsOf(all.items)).toEqual([long.id]);
           const batch = await store.batchGet(COLLECTION, [short.id, long.id]);
-          expect4([...batch.keys()]).toEqual([long.id]);
+          expect3([...batch.keys()]).toEqual([long.id]);
         });
       },
       SLOW
     );
-    it4("a conditional put applies when the field matches, and otherwise fails condition-failed and changes nothing", async () => {
+    it3("a conditional put applies when the field matches, and otherwise fails condition-failed and changes nothing", async () => {
       const store = await make();
       await closing(store, async () => {
         const v1 = {
@@ -473,7 +438,7 @@ function documentStoreModelCases(make, opts) {
         const v2 = { ...v1, label: "v2", version: 2 };
         await store.put(COLLECTION, "c", v1);
         await store.put(COLLECTION, "c", v2, { conditionKey: "version", conditionValue: 1 });
-        expect4(await store.get(COLLECTION, "c")).toEqual(v2);
+        expect3(await store.get(COLLECTION, "c")).toEqual(v2);
         const stale = await rejection(
           store.put(
             COLLECTION,
@@ -482,16 +447,16 @@ function documentStoreModelCases(make, opts) {
             { conditionKey: "version", conditionValue: 1 }
           )
         );
-        expect4(stale?.code).toBe("adapter.condition-failed");
-        expect4(await store.get(COLLECTION, "c")).toEqual(v2);
+        expect3(stale?.code).toBe("adapter.condition-failed");
+        expect3(await store.get(COLLECTION, "c")).toEqual(v2);
         const absent = await rejection(
           store.put(COLLECTION, "none", v1, { conditionKey: "version", conditionValue: 1 })
         );
-        expect4(absent?.code).toBe("adapter.condition-failed");
-        expect4(await store.get(COLLECTION, "none")).toBeNull();
+        expect3(absent?.code).toBe("adapter.condition-failed");
+        expect3(await store.get(COLLECTION, "none")).toBeNull();
       });
     }, CASE_MS);
-    it4(
+    it3(
       "batchPut stores every item and batchGet returns exactly the stored keys, equal to what was put",
       async () => {
         await fc.assert(
@@ -502,10 +467,10 @@ function documentStoreModelCases(make, opts) {
               await store.batchPut(COLLECTION, new Map(docs.map((d) => [d.id, d])));
               const asked = [...docs.map((d) => d.id), "contract-absent"];
               const got = await store.batchGet(COLLECTION, asked);
-              expect4(got.size).toBe(docs.length);
+              expect3(got.size).toBe(docs.length);
               for (const doc of docs) {
-                expect4(got.get(doc.id)).toEqual(doc);
-                expect4(await store.get(COLLECTION, doc.id)).toEqual(doc);
+                expect3(got.get(doc.id)).toEqual(doc);
+                expect3(await store.get(COLLECTION, doc.id)).toEqual(doc);
               }
             });
           }),
@@ -514,7 +479,7 @@ function documentStoreModelCases(make, opts) {
       },
       SLOW
     );
-    it4("collections are isolated for get, query and delete", async () => {
+    it3("collections are isolated for get, query and delete", async () => {
       const store = await make();
       await closing(store, async () => {
         const a = { id: "same", part: "p", nested: {}, label: "A" };
@@ -523,21 +488,21 @@ function documentStoreModelCases(make, opts) {
         await store.put("contract-col-a", a.id, a);
         await store.put("contract-col-a", onlyA.id, onlyA);
         await store.put("contract-col-b", b.id, b);
-        expect4(await store.get("contract-col-a", "same")).toEqual(a);
-        expect4(await store.get("contract-col-b", "same")).toEqual(b);
+        expect3(await store.get("contract-col-a", "same")).toEqual(a);
+        expect3(await store.get("contract-col-b", "same")).toEqual(b);
         const inB = await store.query("contract-col-b", {
           partitionKey: { field: "part", value: "*" },
           limit: 100
         });
-        expect4(idsOf(inB.items)).toEqual([b.id]);
+        expect3(idsOf(inB.items)).toEqual([b.id]);
         await store.delete("contract-col-a", "same");
-        expect4(await store.get("contract-col-b", "same")).toEqual(b);
-        expect4(await store.get("contract-col-a", "only-a")).toEqual(onlyA);
+        expect3(await store.get("contract-col-b", "same")).toEqual(b);
+        expect3(await store.get("contract-col-a", "only-a")).toEqual(onlyA);
       });
     }, CASE_MS);
     if (opts.isolation !== void 0) {
       const isolation = opts.isolation;
-      it4("two instances with different prefixes never see each other\u2019s documents", async () => {
+      it3("two instances with different prefixes never see each other\u2019s documents", async () => {
         const [one, two] = await isolation();
         try {
           const mine = { id: "shared-key", part: "p", nested: {}, label: "one" };
@@ -545,18 +510,18 @@ function documentStoreModelCases(make, opts) {
           await one.put(COLLECTION, mine.id, mine);
           await one.put(COLLECTION, "one-only", { ...mine, id: "one-only" });
           await two.put(COLLECTION, theirs.id, theirs);
-          expect4(await one.get(COLLECTION, mine.id)).toEqual(mine);
-          expect4(await two.get(COLLECTION, theirs.id)).toEqual(theirs);
-          expect4(await two.get(COLLECTION, "one-only")).toBeNull();
+          expect3(await one.get(COLLECTION, mine.id)).toEqual(mine);
+          expect3(await two.get(COLLECTION, theirs.id)).toEqual(theirs);
+          expect3(await two.get(COLLECTION, "one-only")).toBeNull();
           const inTwo = await two.query(COLLECTION, {
             partitionKey: { field: "part", value: "*" },
             limit: 100
           });
-          expect4(idsOf(inTwo.items)).toEqual([theirs.id]);
+          expect3(idsOf(inTwo.items)).toEqual([theirs.id]);
           const batch = await two.batchGet(COLLECTION, [mine.id, "one-only"]);
-          expect4([...batch.values()]).toEqual([theirs]);
+          expect3([...batch.values()]).toEqual([theirs]);
           await one.delete(COLLECTION, mine.id);
-          expect4(await two.get(COLLECTION, theirs.id)).toEqual(theirs);
+          expect3(await two.get(COLLECTION, theirs.id)).toEqual(theirs);
         } finally {
           await one.close();
           await two.close();
@@ -568,7 +533,7 @@ function documentStoreModelCases(make, opts) {
 
 // src/document-store-replace.ts
 import fc2 from "fast-check";
-import { expect as expect5, it as it5 } from "vitest";
+import { expect as expect4, it as it4 } from "vitest";
 var SLOW2 = 6e4;
 var KEYS = ["a", "b", "c", "d", "e", "f", "g", "h"];
 var macrotask = () => new Promise((resolve) => setImmediate(resolve));
@@ -588,7 +553,7 @@ async function putAll(store, collection, docs) {
 }
 var docsFrom = (keys, v) => keys.map((id) => ({ id, part: "p", v }));
 function documentStoreReplaceCases(make, opts) {
-  it5(
+  it4(
     "replaceCollection leaves exactly the new set, whatever the old and new sets: no stale key of the old set survives, and another collection is untouched (property)",
     async () => {
       await using(make, async (store) => {
@@ -605,11 +570,11 @@ function documentStoreReplaceCases(make, opts) {
               await putAll(store, decoy, docsFrom(oldKeys, 3));
               const next = docsFrom(newKeys, 2);
               await store.replaceCollection(collection, entriesOf(next));
-              expect5(await snapshot(store, collection)).toEqual(shape(next));
+              expect4(await snapshot(store, collection)).toEqual(shape(next));
               for (const key of oldKeys.filter((k) => !newKeys.includes(k))) {
-                expect5(await store.get(collection, key), `stale key ${key}`).toBeNull();
+                expect4(await store.get(collection, key), `stale key ${key}`).toBeNull();
               }
-              expect5(await snapshot(store, decoy)).toEqual(shape(docsFrom(oldKeys, 3)));
+              expect4(await snapshot(store, decoy)).toEqual(shape(docsFrom(oldKeys, 3)));
             }
           ),
           { numRuns: 25 }
@@ -618,7 +583,7 @@ function documentStoreReplaceCases(make, opts) {
     },
     SLOW2
   );
-  it5(
+  it4(
     "replaceCollection is atomic to a concurrent reader: polling while the replace runs sees only the full old set or the full new set, never a partial set",
     async () => {
       await using(make, async (store) => {
@@ -638,19 +603,19 @@ function documentStoreReplaceCases(make, opts) {
           done = true;
         });
         await reader;
-        expect5(seen.length, "the reader read while the replace ran").toBeGreaterThan(0);
+        expect4(seen.length, "the reader read while the replace ran").toBeGreaterThan(0);
         for (const observed of seen) {
-          expect5(
+          expect4(
             allowed.has(JSON.stringify(observed)),
             `a partial set: ${observed.join(" ")}`
           ).toBe(true);
         }
-        expect5(await snapshot(store, "contract-replace-reader")).toEqual(shape(next));
+        expect4(await snapshot(store, "contract-replace-reader")).toEqual(shape(next));
       });
     },
     CASE_MS
   );
-  it5(
+  it4(
     "replaceCollection whose source throws part-way rejects with the source\u2019s error and leaves the old set intact",
     async () => {
       await using(make, async (store) => {
@@ -665,34 +630,34 @@ function documentStoreReplaceCases(make, opts) {
           () => null,
           (error) => error
         );
-        expect5(String(failed)).toContain("contract: the source failed");
-        expect5(await snapshot(store, "contract-replace-failing")).toEqual(shape(old));
+        expect4(String(failed)).toContain("contract: the source failed");
+        expect4(await snapshot(store, "contract-replace-failing")).toEqual(shape(old));
       });
     },
     CASE_MS
   );
-  it5(
+  it4(
     "replaceCollection with an empty source empties the collection",
     async () => {
       await using(make, async (store) => {
         await putAll(store, "contract-replace-empty", docsFrom(["a", "b"], 1));
         await store.replaceCollection("contract-replace-empty", entriesOf([]));
-        expect5(await snapshot(store, "contract-replace-empty")).toEqual([]);
-        expect5(await store.get("contract-replace-empty", "a")).toBeNull();
+        expect4(await snapshot(store, "contract-replace-empty")).toEqual([]);
+        expect4(await store.get("contract-replace-empty", "a")).toBeNull();
       });
     },
     CASE_MS
   );
   const clock = opts.clock;
   if (clock !== void 0) {
-    it5(
+    it4(
       "replaceCollection writes documents without a TTL: a key whose old document had one is still there after that TTL passes",
       async () => {
         await using(make, async (store) => {
           await store.put("contract-replace-ttl", "a", { id: "a", part: "p", v: 1 }, { ttl: 60 });
           await store.replaceCollection("contract-replace-ttl", entriesOf(docsFrom(["a", "b"], 2)));
           await clock.advance(61e3);
-          expect5(await snapshot(store, "contract-replace-ttl")).toEqual(["a:2", "b:2"]);
+          expect4(await snapshot(store, "contract-replace-ttl")).toEqual(["a:2", "b:2"]);
         });
       },
       CASE_MS
@@ -735,37 +700,37 @@ async function walk2(store, collection, params2, between) {
   return pages;
 }
 function runDocumentStoreContract(name, make, opts = {}) {
-  describe5(`DocumentStoreAdapter contract: ${name}`, () => {
-    it6(
+  describe4(`DocumentStoreAdapter contract: ${name}`, () => {
+    it5(
       "get is null for a missing key; put then get round-trips; a second put overwrites",
       async () => {
         await using2(make, async (store) => {
-          expect6(await store.get("col", "missing")).toBeNull();
+          expect5(await store.get("col", "missing")).toBeNull();
           await store.put("col", "k1", { name: "test", value: 42, nested: { list: [1, "two"] } });
-          expect6(await store.get("col", "k1")).toEqual({
+          expect5(await store.get("col", "k1")).toEqual({
             name: "test",
             value: 42,
             nested: { list: [1, "two"] }
           });
           await store.put("col", "k1", { v: 2 });
-          expect6(await store.get("col", "k1")).toEqual({ v: 2 });
+          expect5(await store.get("col", "k1")).toEqual({ v: 2 });
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "delete removes the document, and deleting a missing key does not throw",
       async () => {
         await using2(make, async (store) => {
           await store.put("col", "k1", { v: 1 });
           await store.delete("col", "k1");
-          expect6(await store.get("col", "k1")).toBeNull();
-          await expect6(store.delete("col", "nope")).resolves.toBeUndefined();
+          expect5(await store.get("col", "k1")).toBeNull();
+          await expect5(store.delete("col", "nope")).resolves.toBeUndefined();
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "query narrows by partition, and '*' returns the whole collection",
       async () => {
         await using2(make, async (store) => {
@@ -775,15 +740,15 @@ function runDocumentStoreContract(name, make, opts = {}) {
             { id: "c", part: "p" }
           ]);
           const p = await store.query("col", { partitionKey: { field: "part", value: "p" } });
-          expect6(ids(p.items).sort()).toEqual(["a", "c"]);
+          expect5(ids(p.items).sort()).toEqual(["a", "c"]);
           const all = await store.query("col", { partitionKey: { field: "part", value: "*" } });
-          expect6(ids(all.items).sort()).toEqual(["a", "b", "c"]);
-          expect6(all.nextCursor).toBeNull();
+          expect5(ids(all.items).sort()).toEqual(["a", "b", "c"]);
+          expect5(all.nextCursor).toBeNull();
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "sortKey eq is strict (1 is not '1', 'a' is not 'A'); gt, lt and between follow compareDocumentValues",
       async () => {
         await using2(make, async (store) => {
@@ -801,20 +766,20 @@ function runDocumentStoreContract(name, make, opts = {}) {
               sortKey
             })).items
           ).sort();
-          expect6(await where({ field: "v", operator: "eq", value: 1 })).toEqual(["n1"]);
-          expect6(await where({ field: "v", operator: "eq", value: "a" })).toEqual(["sa"]);
-          expect6(await where({ field: "v", operator: "lt", value: "0" })).toEqual(["n1", "n5"]);
-          expect6(await where({ field: "v", operator: "gt", value: 5 })).toEqual(
+          expect5(await where({ field: "v", operator: "eq", value: 1 })).toEqual(["n1"]);
+          expect5(await where({ field: "v", operator: "eq", value: "a" })).toEqual(["sa"]);
+          expect5(await where({ field: "v", operator: "lt", value: "0" })).toEqual(["n1", "n5"]);
+          expect5(await where({ field: "v", operator: "gt", value: 5 })).toEqual(
             ["nul", "s1", "sA", "sa"].sort()
           );
-          expect6(await where({ field: "v", operator: "between", value: [2, "a"] })).toEqual(
+          expect5(await where({ field: "v", operator: "between", value: [2, "a"] })).toEqual(
             ["n5", "s1", "sA", "sa"].sort()
           );
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "orderBy orders by value with the collator, nulls and missing last, ties by key, on a dotted path too",
       async () => {
         await using2(make, async (store) => {
@@ -831,17 +796,17 @@ function runDocumentStoreContract(name, make, opts = {}) {
             partitionKey: { field: "part", value: "p" },
             orderBy: { field: "nested.v", direction: "asc", nulls: "last" }
           });
-          expect6(ids(asc.items)).toEqual(["k6", "k5", "k2", "k1", "k4", "k0", "k3"]);
+          expect5(ids(asc.items)).toEqual(["k6", "k5", "k2", "k1", "k4", "k0", "k3"]);
           const desc = await store.query("col", {
             partitionKey: { field: "part", value: "p" },
             orderBy: { field: "nested.v", direction: "desc", nulls: "last" }
           });
-          expect6(ids(desc.items)).toEqual(["k1", "k4", "k2", "k5", "k6", "k0", "k3"]);
+          expect5(ids(desc.items)).toEqual(["k1", "k4", "k2", "k5", "k6", "k0", "k3"]);
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "a limit and cursor walk returns every match exactly once, also when a document is deleted mid-walk",
       async () => {
         await using2(make, async (store) => {
@@ -854,20 +819,20 @@ function runDocumentStoreContract(name, make, opts = {}) {
               ...orderBy !== void 0 && { orderBy }
             };
             const whole = (await walk2(store, "col", params2)).flat();
-            expect6(ids(whole).sort()).toEqual(ids(docs).sort());
+            expect5(ids(whole).sort()).toEqual(ids(docs).sort());
             const anchor = whole[1];
             const walked = (await walk2(store, "col", params2, async (page) => {
               if (page === 1) await store.delete("col", anchor.id);
             })).flat();
-            expect6(new Set(ids(walked)).size).toBe(walked.length);
-            expect6(ids(walked).sort()).toEqual(ids(docs).sort());
+            expect5(new Set(ids(walked)).size).toBe(walked.length);
+            expect5(ids(walked).sort()).toEqual(ids(docs).sort());
             await store.put("col", anchor.id, anchor);
           }
         });
       },
       SLOW3
     );
-    it6(
+    it5(
       "a cursor issued under one orderBy is refused under another, and continues under its own",
       async () => {
         await using2(make, async (store) => {
@@ -882,25 +847,25 @@ function runDocumentStoreContract(name, make, opts = {}) {
             limit: 2
           };
           const first = await store.query("col", base);
-          expect6(first.nextCursor).not.toBeNull();
+          expect5(first.nextCursor).not.toBeNull();
           const cursor = first.nextCursor;
           const other = await rejection2(
             store.query("col", { ...base, orderBy: { field: "v", direction: "desc" }, cursor })
           );
-          expect6(other).toBeInstanceOf(Error);
+          expect5(other).toBeInstanceOf(Error);
           const next = await store.query("col", { ...base, cursor });
-          expect6(ids(next.items)).toEqual(["k2", "k3"]);
+          expect5(ids(next.items)).toEqual(["k2", "k3"]);
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "a document put with a ttl (seconds) is gone from get, query and batchGet once it expires",
       async () => {
         await using2(make, async (store) => {
           await store.put("col", "short", { id: "short", part: "p" }, { ttl: 1 });
           await store.put("col", "kept", { id: "kept", part: "p" });
-          expect6(await store.get("col", "short")).toEqual({ id: "short", part: "p" });
+          expect5(await store.get("col", "short")).toEqual({ id: "short", part: "p" });
           if (opts.clock !== void 0) {
             await opts.clock.advance(1001);
           } else {
@@ -909,15 +874,15 @@ function runDocumentStoreContract(name, make, opts = {}) {
               await new Promise((r) => setTimeout(r, 50));
             }
           }
-          expect6(await store.get("col", "short")).toBeNull();
+          expect5(await store.get("col", "short")).toBeNull();
           const all = await store.query("col", { partitionKey: { field: "part", value: "*" } });
-          expect6(ids(all.items)).toEqual(["kept"]);
-          expect6([...(await store.batchGet("col", ["short", "kept"])).keys()]).toEqual(["kept"]);
+          expect5(ids(all.items)).toEqual(["kept"]);
+          expect5([...(await store.batchGet("col", ["short", "kept"])).keys()]).toEqual(["kept"]);
         });
       },
       SLOW3
     );
-    it6(
+    it5(
       "a conditional put applies when the field is strictly equal, and otherwise fails condition-failed",
       async () => {
         await using2(make, async (store) => {
@@ -928,12 +893,12 @@ function runDocumentStoreContract(name, make, opts = {}) {
             { version: 2, label: "v2" },
             { conditionKey: "version", conditionValue: 1 }
           );
-          expect6(await store.get("col", "c")).toEqual({ version: 2, label: "v2" });
+          expect5(await store.get("col", "c")).toEqual({ version: 2, label: "v2" });
           for (const conditionValue of [1, "2"]) {
             const failed = await rejection2(
               store.put("col", "c", { version: 3 }, { conditionKey: "version", conditionValue })
             );
-            expect6(failed?.code).toBe("adapter.condition-failed");
+            expect5(failed?.code).toBe("adapter.condition-failed");
           }
           const absent = await rejection2(
             store.put(
@@ -943,14 +908,14 @@ function runDocumentStoreContract(name, make, opts = {}) {
               { conditionKey: "version", conditionValue: 1 }
             )
           );
-          expect6(absent?.code).toBe("adapter.condition-failed");
-          expect6(await store.get("col", "c")).toEqual({ version: 2, label: "v2" });
-          expect6(await store.get("col", "none")).toBeNull();
+          expect5(absent?.code).toBe("adapter.condition-failed");
+          expect5(await store.get("col", "c")).toEqual({ version: 2, label: "v2" });
+          expect5(await store.get("col", "none")).toBeNull();
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "batchPut stores every item; batchGet returns exactly the stored keys",
       async () => {
         await using2(make, async (store) => {
@@ -962,32 +927,32 @@ function runDocumentStoreContract(name, make, opts = {}) {
             ])
           );
           const got = await store.batchGet("col", ["x", "y", "missing"]);
-          expect6([...got.keys()].sort()).toEqual(["x", "y"]);
-          expect6(got.get("x")).toEqual({ n: 10 });
-          expect6(await store.get("col", "y")).toEqual({ n: 20 });
-          expect6((await store.batchGet("col", [])).size).toBe(0);
+          expect5([...got.keys()].sort()).toEqual(["x", "y"]);
+          expect5(got.get("x")).toEqual({ n: 10 });
+          expect5(await store.get("col", "y")).toEqual({ n: 20 });
+          expect5((await store.batchGet("col", [])).size).toBe(0);
         });
       },
       CASE_MS
     );
-    it6(
+    it5(
       "collections are isolated for get, query and delete",
       async () => {
         await using2(make, async (store) => {
           await store.put("colA", "key", { id: "key", part: "p", from: "A" });
           await store.put("colB", "key", { id: "key", part: "p", from: "B" });
-          expect6(await store.get("colA", "key")).toEqual({ id: "key", part: "p", from: "A" });
+          expect5(await store.get("colA", "key")).toEqual({ id: "key", part: "p", from: "A" });
           const inB = await store.query("colB", { partitionKey: { field: "part", value: "*" } });
-          expect6(inB.items).toEqual([{ id: "key", part: "p", from: "B" }]);
+          expect5(inB.items).toEqual([{ id: "key", part: "p", from: "B" }]);
           await store.delete("colA", "key");
-          expect6(await store.get("colB", "key")).toEqual({ id: "key", part: "p", from: "B" });
+          expect5(await store.get("colB", "key")).toEqual({ id: "key", part: "p", from: "B" });
         });
       },
       CASE_MS
     );
     const isolation = opts.isolation;
     if (isolation !== void 0) {
-      it6(
+      it5(
         "two stores under different prefixes never see each other\u2019s documents",
         async () => {
           const [one, two] = await isolation();
@@ -995,16 +960,16 @@ function runDocumentStoreContract(name, make, opts = {}) {
             await one.put("col", "shared", { id: "shared", part: "p", owner: "one" });
             await one.put("col", "one-only", { id: "one-only", part: "p", owner: "one" });
             await two.put("col", "shared", { id: "shared", part: "p", owner: "two" });
-            expect6(await one.get("col", "shared")).toEqual({
+            expect5(await one.get("col", "shared")).toEqual({
               id: "shared",
               part: "p",
               owner: "one"
             });
-            expect6(await two.get("col", "one-only")).toBeNull();
+            expect5(await two.get("col", "one-only")).toBeNull();
             const inTwo = await two.query("col", { partitionKey: { field: "part", value: "*" } });
-            expect6(inTwo.items).toEqual([{ id: "shared", part: "p", owner: "two" }]);
+            expect5(inTwo.items).toEqual([{ id: "shared", part: "p", owner: "two" }]);
             await one.delete("col", "shared");
-            expect6(await two.get("col", "shared")).toEqual({
+            expect5(await two.get("col", "shared")).toEqual({
               id: "shared",
               part: "p",
               owner: "two"
@@ -1024,28 +989,28 @@ function runDocumentStoreContract(name, make, opts = {}) {
 }
 
 // src/email.ts
-import { describe as describe6, expect as expect7, it as it7 } from "vitest";
+import { describe as describe5, expect as expect6, it as it6 } from "vitest";
 var MAIL = {
   template: "order-confirmation",
   to: "test@example.com",
   vars: { orderNumber: "ORD-001" }
 };
 function runEmailContract(name, build, options = {}) {
-  describe6(`EmailAdapter contract: ${name}`, () => {
-    it7(
+  describe5(`EmailAdapter contract: ${name}`, () => {
+    it6(
       "sendTransactional resolves with accepted or messageId",
       async () => {
         const adapter = await build();
         const result = await adapter.sendTransactional(MAIL);
-        expect7(typeof result.accepted).toBe("boolean");
+        expect6(typeof result.accepted).toBe("boolean");
       },
       CASE_MS
     );
-    it7(
+    it6(
       "syncCustomerToList resolves without throwing",
       async () => {
         const adapter = await build();
-        await expect7(
+        await expect6(
           adapter.syncCustomerToList({
             customerId: "cust-1",
             orderCount: 0,
@@ -1057,11 +1022,11 @@ function runEmailContract(name, build, options = {}) {
       },
       CASE_MS
     );
-    it7(
+    it6(
       "removeCustomerFromList resolves without throwing",
       async () => {
         const adapter = await build();
-        await expect7(adapter.removeCustomerFromList("cust-1")).resolves.not.toThrow();
+        await expect6(adapter.removeCustomerFromList("cust-1")).resolves.not.toThrow();
       },
       CASE_MS
     );
@@ -1075,13 +1040,13 @@ function runEmailContract(name, build, options = {}) {
 }
 
 // src/event-bus.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { describe as describe8, expect as expect9, it as it9 } from "vitest";
 
 // src/event-bus-delivery.ts
 import { randomUUID } from "crypto";
 import fc3 from "fast-check";
-import { describe as describe7, expect as expect8, it as it8 } from "vitest";
+import { describe as describe6, expect as expect7, it as it7 } from "vitest";
 var SLOW4 = 6e4;
 function event(type, payload = {}) {
   return {
@@ -1118,8 +1083,8 @@ async function closingAll(buses, body) {
 }
 var TYPES = ["order.created.v1", "order.paid.v1", "cart.updated.v1"];
 function eventBusDeliveryCases(make, opts) {
-  describe7("keeps the delivery contract", () => {
-    it8(
+  describe6("keeps the delivery contract", () => {
+    it7(
       "publish resolves only after every matching handler has finished: a 200 ms handler, named and unnamed, is done first",
       async () => {
         const bus = await make();
@@ -1140,14 +1105,14 @@ function eventBusDeliveryCases(make, opts) {
           const startedAt = Date.now();
           await bus.publish(event("contract.slow.v1"));
           const elapsed = Date.now() - startedAt;
-          expect8([...finished].sort()).toEqual(["named", "unnamed"]);
-          expect8(elapsed).toBeGreaterThanOrEqual(190);
+          expect7([...finished].sort()).toEqual(["named", "unnamed"]);
+          expect7(elapsed).toBeGreaterThanOrEqual(190);
         });
       },
       SLOW4
     );
-    it8(
-      "a throwing handler leaves publish resolved and every other matching handler called, event after event",
+    it7(
+      "a throwing named handler rejects publish with handler_failed naming it, and every other matching handler is called, event after event",
       async () => {
         const bus = await make();
         await closingAll([bus], async () => {
@@ -1162,14 +1127,23 @@ function eventBusDeliveryCases(make, opts) {
           await bus.subscribe("contract.boom.v1", async (e) => {
             received.push(e.id);
           });
-          const events = [event("contract.boom.v1"), event("contract.boom.v1"), event("contract.boom.v1")];
-          for (const e of events) await expect8(bus.publish(e)).resolves.toBeUndefined();
-          expect8(received).toEqual(events.map((e) => e.id));
+          const events = [
+            event("contract.boom.v1"),
+            event("contract.boom.v1"),
+            event("contract.boom.v1")
+          ];
+          for (const e of events) {
+            await expect7(bus.publish(e)).rejects.toMatchObject({
+              code: "adapter.handler_failed",
+              context: { eventId: e.id, failed: [{ subscription: "contract-throws" }] }
+            });
+          }
+          expect7(received).toEqual(events.map((e) => e.id));
         });
       },
       SLOW4
     );
-    it8(
+    it7(
       "replay reaches derived subscriptions only, in order; a later publish still reaches every subscription",
       async () => {
         const bus = await make();
@@ -1187,19 +1161,19 @@ function eventBusDeliveryCases(make, opts) {
           await bus.subscribe("contract.replay.v1", async (e) => void sideUnnamed.push(e.id));
           const replayed = [event("contract.replay.v1"), event("contract.replay.v1")];
           await bus.replay(replayed);
-          expect8(derived).toEqual(replayed.map((e) => e.id));
-          expect8(sideNamed).toEqual([]);
-          expect8(sideUnnamed).toEqual([]);
+          expect7(derived).toEqual(replayed.map((e) => e.id));
+          expect7(sideNamed).toEqual([]);
+          expect7(sideUnnamed).toEqual([]);
           const live = event("contract.replay.v1");
           await bus.publish(live);
-          expect8(derived).toEqual([...replayed, live].map((e) => e.id));
-          expect8(sideNamed).toEqual([live.id]);
-          expect8(sideUnnamed).toEqual([live.id]);
+          expect7(derived).toEqual([...replayed, live].map((e) => e.id));
+          expect7(sideNamed).toEqual([live.id]);
+          expect7(sideUnnamed).toEqual([live.id]);
         });
       },
       SLOW4
     );
-    it8(
+    it7(
       "publishBatch reaches each subscription with exactly its matching events, in batch order (wildcards and pattern arrays)",
       async () => {
         await fc3.assert(
@@ -1211,7 +1185,10 @@ function eventBusDeliveryCases(make, opts) {
                 const fence = event("contract.fence.v1");
                 const subs = [
                   { patterns: ["order.*", fence.type], name: void 0 },
-                  { patterns: ["cart.updated.v1", "order.paid.v1", fence.type], name: "contract-arr" },
+                  {
+                    patterns: ["cart.updated.v1", "order.paid.v1", fence.type],
+                    name: "contract-arr"
+                  },
                   { patterns: ["order.created.v1", fence.type], name: "contract-one" }
                 ];
                 const seen = subs.map(() => []);
@@ -1230,7 +1207,7 @@ function eventBusDeliveryCases(make, opts) {
                 );
                 for (const [i, sub] of subs.entries()) {
                   const expected = events.filter((e) => matches(sub.patterns, e.type));
-                  expect8(seen[i], sub.patterns.join("|")).toEqual([
+                  expect7(seen[i], sub.patterns.join("|")).toEqual([
                     ...expected.map((e) => e.id),
                     fence.id
                   ]);
@@ -1243,7 +1220,7 @@ function eventBusDeliveryCases(make, opts) {
       },
       SLOW4
     );
-    it8(
+    it7(
       "an unsubscribed handler, by bus.unsubscribe or by its own unsubscribe(), receives nothing more",
       async () => {
         const bus = await make();
@@ -1262,14 +1239,14 @@ function eventBusDeliveryCases(make, opts) {
           await b.unsubscribe();
           const after = [event("contract.unsub.v1"), event("contract.unsub.v1")];
           for (const e of after) await bus.publish(e);
-          expect8(kept).toEqual([before, ...after].map((e) => e.id));
-          expect8(gone).toEqual([before.id]);
-          expect8(goneToo).toEqual([before.id]);
+          expect7(kept).toEqual([before, ...after].map((e) => e.id));
+          expect7(gone).toEqual([before.id]);
+          expect7(goneToo).toEqual([before.id]);
         });
       },
       SLOW4
     );
-    it8(
+    it7(
       "on one instance, a named and an unnamed subscription each handle every event once",
       async () => {
         const bus = await make();
@@ -1282,17 +1259,17 @@ function eventBusDeliveryCases(make, opts) {
           await bus.subscribe("contract.both.v1", async (e) => void unnamed.push(e.id));
           const events = Array.from({ length: 6 }, () => event("contract.both.v1"));
           for (const e of events) await bus.publish(e);
-          expect8(named).toEqual(events.map((e) => e.id));
-          expect8(unnamed).toEqual(named);
+          expect7(named).toEqual(events.map((e) => e.id));
+          expect7(unnamed).toEqual(named);
         });
       },
       SLOW4
     );
     const second = opts.second;
     if (second === void 0) return;
-    describe7("two instances on the same streams", () => {
+    describe6("two instances on the same streams", () => {
       const N = 12;
-      it8(
+      it7(
         "one named subscription on both instances handles each of N events exactly once in total",
         async () => {
           const a = await make();
@@ -1312,13 +1289,13 @@ function eventBusDeliveryCases(make, opts) {
             await a.publish(event("contract.named.fence"));
             const ids2 = new Set(events.map((e) => e.id));
             const handled = [...byA, ...byB].filter((id) => ids2.has(id));
-            expect8(handled.length).toBe(events.length);
-            expect8([...handled].sort()).toEqual(events.map((e) => e.id).sort());
+            expect7(handled.length).toBe(events.length);
+            expect7([...handled].sort()).toEqual(events.map((e) => e.id).sort());
           });
         },
         SLOW4
       );
-      it8(
+      it7(
         "an unnamed subscription on each instance receives all N events, in order, on both",
         async () => {
           const a = await make();
@@ -1328,19 +1305,22 @@ function eventBusDeliveryCases(make, opts) {
             const onB = [];
             await a.subscribe("contract.fanout.*", async (e) => void onA.push(e.id));
             await b.subscribe("contract.fanout.*", async (e) => void onB.push(e.id));
-            const events = Array.from({ length: N }, (_, seq) => event("contract.fanout.x", { seq }));
+            const events = Array.from(
+              { length: N },
+              (_, seq) => event("contract.fanout.x", { seq })
+            );
             for (const e of events) await a.publish(e);
             const fenceB = event("contract.fanout.fence");
             await b.publish(fenceB);
             const ids2 = events.map((e) => e.id);
-            expect8(onA.slice(0, N)).toEqual(ids2);
-            expect8(onB.slice(0, N)).toEqual(ids2);
-            expect8(onB[N]).toBe(fenceB.id);
+            expect7(onA.slice(0, N)).toEqual(ids2);
+            expect7(onB.slice(0, N)).toEqual(ids2);
+            expect7(onB[N]).toBe(fenceB.id);
           });
         },
         SLOW4
       );
-      it8(
+      it7(
         "replay on one instance reaches its own derived handlers and nothing on the other instance",
         async () => {
           const a = await make();
@@ -1364,10 +1344,10 @@ function eventBusDeliveryCases(make, opts) {
             await a.replay(replayed);
             const fence = event("contract.rebuild.fence");
             await b.publish(fence);
-            expect8(derivedA.slice(0, replayed.length)).toEqual(replayed.map((e) => e.id));
+            expect7(derivedA.slice(0, replayed.length)).toEqual(replayed.map((e) => e.id));
             const ids2 = new Set(replayed.map((e) => e.id));
-            expect8(derivedB.filter((id) => ids2.has(id))).toEqual([]);
-            expect8(sideB).toEqual([fence.id]);
+            expect7(derivedB.filter((id) => ids2.has(id))).toEqual([]);
+            expect7(sideB).toEqual([fence.id]);
           });
         },
         SLOW4
@@ -1375,13 +1355,15 @@ function eventBusDeliveryCases(make, opts) {
       const timing = opts.timing;
       if (timing === void 0) return;
       const { claimIdleMs, ackTimeoutMs } = timing;
-      it8(
+      it7(
         "groups left by a stopped instance (never unsubscribed) do not delay publish on the other instance",
         async () => {
           const a = await make();
           const b = await second();
           await closingAll([a], async () => {
-            await b.subscribe("contract.left.*", async () => void 0, { name: "contract-left-behind" });
+            await b.subscribe("contract.left.*", async () => void 0, {
+              name: "contract-left-behind"
+            });
             await b.subscribe("contract.left.*", async () => void 0);
             await b.close();
             const handled = [];
@@ -1392,13 +1374,13 @@ function eventBusDeliveryCases(make, opts) {
             const startedAt = Date.now();
             await a.publish(e);
             const elapsed = Date.now() - startedAt;
-            expect8(handled).toEqual([e.id]);
-            expect8(elapsed).toBeLessThan(ackTimeoutMs / 2);
+            expect7(handled).toEqual([e.id]);
+            expect7(elapsed).toBeLessThan(ackTimeoutMs / 2);
           });
         },
         SLOW4
       );
-      it8(
+      it7(
         "an entry pending on a stopped consumer of a named group is handled by the live one after claimIdleMs and before ackTimeoutMs",
         async () => {
           const a = await make();
@@ -1438,10 +1420,10 @@ function eventBusDeliveryCases(make, opts) {
             );
             const claimed = byA.find((h) => h.id === stranded.id);
             const idle = claimed.at - receivedByB;
-            expect8(idle, "taken over before claimIdleMs").toBeGreaterThanOrEqual(claimIdleMs - 50);
-            expect8(idle, "taken over only after ackTimeoutMs").toBeLessThan(ackTimeoutMs);
-            expect8(byA.filter((h) => h.id === stranded.id).length).toBe(1);
-            expect8(publishMs, "a publish on the group waited out the timeout").toBeLessThan(
+            expect7(idle, "taken over before claimIdleMs").toBeGreaterThanOrEqual(claimIdleMs - 50);
+            expect7(idle, "taken over only after ackTimeoutMs").toBeLessThan(ackTimeoutMs);
+            expect7(byA.filter((h) => h.id === stranded.id).length).toBe(1);
+            expect7(publishMs, "a publish on the group waited out the timeout").toBeLessThan(
               ackTimeoutMs
             );
           } finally {
@@ -1452,7 +1434,7 @@ function eventBusDeliveryCases(make, opts) {
         },
         SLOW4
       );
-      it8(
+      it7(
         "an unnamed subscription unsubscribed while publish waits on it lets publish resolve well before ackTimeoutMs",
         async () => {
           const a = await make();
@@ -1471,8 +1453,8 @@ function eventBusDeliveryCases(make, opts) {
             const unsubscribedAt = Date.now();
             const unsubscribing = a.unsubscribe(sub);
             const outcome = await publishing;
-            expect8(typeof outcome, `publish rejected: ${String(outcome)}`).toBe("number");
-            expect8(outcome - unsubscribedAt).toBeLessThan(ackTimeoutMs / 2);
+            expect7(typeof outcome, `publish rejected: ${String(outcome)}`).toBe("number");
+            expect7(outcome - unsubscribedAt).toBeLessThan(ackTimeoutMs / 2);
             held.open();
             await unsubscribing;
           } finally {
@@ -1486,20 +1468,355 @@ function eventBusDeliveryCases(make, opts) {
   });
 }
 
+// src/event-bus-failure.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { describe as describe7, expect as expect8, it as it8 } from "vitest";
+var SLOW5 = 6e4;
+var SLOW_HANDLER_MS = 200;
+var IN_PROCESS_WINDOW_MS = 200;
+function event2(type, payload = {}) {
+  return {
+    id: `evt-${randomUUID2()}`,
+    type,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    source: "contract-failure",
+    correlationId: `corr-${randomUUID2()}`,
+    payload,
+    metadata: { storeId: "contract", environment: "development", version: "0.0.0" }
+  };
+}
+var delay2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function until2(check, label, ms) {
+  const deadline = Date.now() + ms;
+  while (!check()) {
+    if (Date.now() > deadline) throw new Error(`timed out after ${ms} ms waiting for ${label}`);
+    await delay2(10);
+  }
+}
+function gate2() {
+  let open;
+  const wait = new Promise((r) => {
+    open = r;
+  });
+  return { wait, open };
+}
+async function closing2(buses, body) {
+  try {
+    await body();
+  } finally {
+    for (const bus of buses) await bus.close();
+  }
+}
+async function settled(promise) {
+  const started = Date.now();
+  try {
+    await promise;
+    return { state: "resolved", error: void 0, at: Date.now(), ms: Date.now() - started };
+  } catch (error) {
+    return { state: "rejected", error, at: Date.now(), ms: Date.now() - started };
+  }
+}
+function failure(outcome) {
+  expect8(outcome.state, "publish resolved, so the failure was swallowed").toBe("rejected");
+  const e = outcome.error;
+  return {
+    name: String(e.name),
+    code: String(e.code),
+    message: String(e.message),
+    context: e.context ?? {}
+  };
+}
+var failedNames = (f) => (f.context.failed ?? []).map((x) => x.subscription);
+function eventBusFailureCases(make, opts) {
+  const window = opts.timing === void 0 ? IN_PROCESS_WINDOW_MS : 3 * opts.timing.claimIdleMs;
+  describe7("reports handler failures", () => {
+    it8(
+      "a named handler that throws rejects publish with handler_failed naming it alone, only after the other named handlers (one of them slow) have each run once and finished; a throwing unnamed handler is named nowhere; replay past a throwing derived handler resolves",
+      async () => {
+        const bus = await make();
+        await closing2([bus], async () => {
+          const type = "contract.failure.v1";
+          const ran = { a: 0, b: 0, c: 0 };
+          const finished = { b: void 0, c: void 0 };
+          await bus.subscribe(
+            type,
+            async () => {
+              ran.a += 1;
+              throw new Error("contract handler A refused");
+            },
+            { name: "contract-failure-a" }
+          );
+          await bus.subscribe(
+            type,
+            async () => {
+              ran.b += 1;
+              await delay2(SLOW_HANDLER_MS);
+              finished.b = Date.now();
+            },
+            { name: "contract-failure-b" }
+          );
+          await bus.subscribe(
+            type,
+            async () => {
+              ran.c += 1;
+              finished.c = Date.now();
+            },
+            { name: "contract-failure-c" }
+          );
+          await bus.subscribe(type, async () => {
+            throw new Error("contract admin tab refused");
+          });
+          const e = event2(type);
+          const outcome = await settled(bus.publish(e));
+          expect8(ran).toEqual({ a: 1, b: 1, c: 1 });
+          expect8(finished.b, "the slow handler finished before the rejection").toBeLessThanOrEqual(
+            outcome.at
+          );
+          expect8(finished.c).toBeLessThanOrEqual(outcome.at);
+          expect8(outcome.ms).toBeGreaterThanOrEqual(SLOW_HANDLER_MS - 10);
+          const rebuilt = [];
+          await bus.subscribe(
+            "contract.failure-replay.v1",
+            async () => {
+              throw new Error("contract projection refused");
+            },
+            { name: "contract-failure-projection-a", derived: true }
+          );
+          await bus.subscribe("contract.failure-replay.v1", async (r) => void rebuilt.push(r.id), {
+            name: "contract-failure-projection-b",
+            derived: true
+          });
+          const replayed = [
+            event2("contract.failure-replay.v1"),
+            event2("contract.failure-replay.v1")
+          ];
+          const replay = await settled(bus.replay(replayed));
+          expect8(replay.state).toBe("resolved");
+          expect8(rebuilt).toEqual(replayed.map((r) => r.id));
+          const f = failure(outcome);
+          expect8([f.name, f.code]).toEqual(["AdapterError", "adapter.handler_failed"]);
+          expect8([f.context.eventId, f.context.eventType]).toEqual([e.id, e.type]);
+          expect8(failedNames(f)).toEqual(["contract-failure-a"]);
+          expect8(f.context.failed?.[0]?.message).toContain("contract handler A refused");
+        });
+      },
+      SLOW5
+    );
+    it8(
+      "publishBatch of three events whose second fails a named handler hands all three, in order, to every subscription and only then rejects with handler_failed naming that event and subscription",
+      async () => {
+        const bus = await make();
+        await closing2([bus], async () => {
+          const type = "contract.failure-batch.v1";
+          const picky = [];
+          const other = [];
+          const unnamed = [];
+          await bus.subscribe(
+            type,
+            async (e) => {
+              picky.push(e.id);
+              if (e.payload.seq === 1)
+                throw new Error("contract picky refused");
+            },
+            { name: "contract-failure-picky" }
+          );
+          await bus.subscribe(
+            type,
+            async (e) => {
+              await delay2(50);
+              other.push(e.id);
+            },
+            { name: "contract-failure-other" }
+          );
+          await bus.subscribe(type, async (e) => {
+            await delay2(50);
+            unnamed.push(e.id);
+          });
+          const events = [0, 1, 2].map((seq) => event2(type, { seq }));
+          const seenAtRejection = [];
+          const outcome = await settled(
+            bus.publishBatch(events).catch((error) => {
+              seenAtRejection.push([...picky], [...other], [...unnamed]);
+              throw error;
+            })
+          );
+          const f = failure(outcome);
+          expect8(f.code).toBe("adapter.handler_failed");
+          expect8(f.context.eventId).toBe(events[1].id);
+          expect8(failedNames(f)).toEqual(["contract-failure-picky"]);
+          const ids2 = events.map((e) => e.id);
+          expect8(
+            seenAtRejection,
+            "what each subscription had been handed when the batch rejected"
+          ).toEqual([ids2, ids2, ids2]);
+        });
+      },
+      SLOW5
+    );
+    it8(
+      "publishing a rejected event again reaches every subscription again and resolves once the failed handler passes; in the window after the rejection the bus ran the failed handler only once per publish",
+      async () => {
+        const bus = await make();
+        await closing2([bus], async () => {
+          const type = "contract.failure-again.v1";
+          const ran = { a: 0, b: 0, c: 0, unnamed: 0 };
+          await bus.subscribe(
+            type,
+            async () => {
+              ran.a += 1;
+              if (ran.a === 1) throw new Error("contract handler A refused once");
+            },
+            { name: "contract-again-a" }
+          );
+          await bus.subscribe(type, async () => void (ran.b += 1), { name: "contract-again-b" });
+          await bus.subscribe(type, async () => void (ran.c += 1), { name: "contract-again-c" });
+          await bus.subscribe(type, async () => void (ran.unnamed += 1));
+          const e = event2(type);
+          const first = await settled(bus.publish(e));
+          expect8(failure(first).code).toBe("adapter.handler_failed");
+          await delay2(window);
+          const afterWindow = { ...ran };
+          expect8(afterWindow.a, "the failed handler ran again without a publish").toBe(1);
+          const second2 = await settled(bus.publish(e));
+          expect8(second2.state, String(second2.error)).toBe("resolved");
+          expect8(ran.a).toBe(2);
+          expect8(ran.b).toBe(2);
+          expect8(ran.c).toBe(ran.b);
+          expect8(ran.unnamed).toBe(ran.b);
+          expect8(ran.b - afterWindow.b, "the second publish reached B again").toBe(1);
+        });
+      },
+      SLOW5
+    );
+    const second = opts.second;
+    const timing = opts.timing;
+    if (second === void 0 || timing === void 0) return;
+    it8(
+      "a named handler that throws on another instance fails the publish on this one with handler_failed, not publish_timeout, well within ackTimeoutMs",
+      async () => {
+        const a = await make();
+        const b = await second();
+        const held = gate2();
+        let holding;
+        try {
+          const group = "contract-remote";
+          const hold = "contract.remote.hold";
+          const target = "contract.remote.target";
+          const ranOn = {};
+          const note = (id, where) => (ranOn[id] ??= []).push(where);
+          let aHolding = false;
+          await a.subscribe(
+            "contract.remote.*",
+            async (e2) => {
+              note(e2.id, "a");
+              if (e2.type === hold) {
+                aHolding = true;
+                await held.wait;
+              }
+            },
+            { name: group }
+          );
+          holding = settled(a.publish(event2(hold)));
+          await until2(() => aHolding, "a to take the holding entry", timing.ackTimeoutMs);
+          await b.subscribe(
+            "contract.remote.*",
+            async (e2) => {
+              if (e2.type === hold) return;
+              note(e2.id, "b");
+              throw new Error("contract remote handler refused");
+            },
+            { name: group }
+          );
+          const e = event2(target);
+          const outcome = await settled(a.publish(e));
+          expect8(ranOn[e.id], "the failing handler ran on the second instance only").toEqual(["b"]);
+          const f = failure(outcome);
+          expect8(f.code, f.message).toBe("adapter.handler_failed");
+          expect8(failedNames(f)).toEqual([group]);
+          expect8(outcome.ms).toBeLessThan(timing.ackTimeoutMs / 2);
+        } finally {
+          held.open();
+          await holding;
+          await a.close();
+          await b.close();
+        }
+      },
+      SLOW5
+    );
+    it8(
+      "a named handler that fails once on another instance, then passes on the second publish within ackTimeoutMs: the first publish rejects and the second resolves, and the handler ran twice",
+      async () => {
+        const a = await make();
+        const b = await second();
+        const held = gate2();
+        let holding;
+        try {
+          const group = "contract-remote-once";
+          const hold = "contract.remote-once.hold";
+          const target = "contract.remote-once.target";
+          const ranOn = {};
+          const note = (id, where) => (ranOn[id] ??= []).push(where);
+          let aHolding = false;
+          await a.subscribe(
+            "contract.remote-once.*",
+            async (e2) => {
+              note(e2.id, "a");
+              if (e2.type === hold) {
+                aHolding = true;
+                await held.wait;
+              }
+            },
+            { name: group }
+          );
+          holding = settled(a.publish(event2(hold)));
+          await until2(() => aHolding, "a to take the holding entry", timing.ackTimeoutMs);
+          let runs = 0;
+          await b.subscribe(
+            "contract.remote-once.*",
+            async (e2) => {
+              if (e2.type === hold) return;
+              note(e2.id, "b");
+              runs += 1;
+              if (runs === 1) throw new Error("contract remote handler refused once");
+            },
+            { name: group }
+          );
+          const e = event2(target);
+          const first = await settled(a.publish(e));
+          const again = await settled(a.publish(e));
+          expect8(ranOn[e.id], "the handler ran on the second instance, once per publish").toEqual([
+            "b",
+            "b"
+          ]);
+          expect8(failure(first).code).toBe("adapter.handler_failed");
+          expect8(again.at - first.at).toBeLessThan(timing.ackTimeoutMs);
+          expect8(again.state, String(again.error)).toBe("resolved");
+        } finally {
+          held.open();
+          await holding;
+          await a.close();
+          await b.close();
+        }
+      },
+      SLOW5
+    );
+  });
+}
+
 // src/event-bus.ts
-var SLOW5 = 3e4;
+var SLOW6 = 3e4;
 function makeEvent(type, payload = {}) {
   return {
-    id: `evt-${randomUUID2()}`,
+    id: `evt-${randomUUID3()}`,
     type,
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     source: "contract-tests",
-    correlationId: `corr-${randomUUID2()}`,
+    correlationId: `corr-${randomUUID3()}`,
     payload,
     metadata: { storeId: "test", environment: "development", version: "0.0.0" }
   };
 }
-var delay2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var delay3 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function using3(buses, body) {
   try {
     await body();
@@ -1509,96 +1826,121 @@ async function using3(buses, body) {
 }
 function runEventBusContract(name, make, opts = {}) {
   describe8(`EventBusAdapter contract: ${name}`, () => {
-    it9("publish resolves after the matching handler has finished, and never calls a non-matching one", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const received = [];
-        const other = [];
-        await bus.subscribe("test.event.v1", async (e) => {
-          await delay2(50);
-          received.push(e.payload);
+    it9(
+      "publish resolves after the matching handler has finished, and never calls a non-matching one",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const received = [];
+          const other = [];
+          await bus.subscribe("test.event.v1", async (e) => {
+            await delay3(50);
+            received.push(e.payload);
+          });
+          await bus.subscribe("test.other.v1", async (e) => void other.push(e));
+          await bus.publish(makeEvent("test.event.v1", { x: 1 }));
+          expect9(received).toEqual([{ x: 1 }]);
+          expect9(other).toEqual([]);
         });
-        await bus.subscribe("test.other.v1", async (e) => void other.push(e));
-        await bus.publish(makeEvent("test.event.v1", { x: 1 }));
-        expect9(received).toEqual([{ x: 1 }]);
-        expect9(other).toEqual([]);
-      });
-    }, CASE_MS);
-    it9("a handler that throws leaves publish resolved and every other handler called", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const results = [];
-        await bus.subscribe("error.test.v1", async () => {
-          throw new Error("boom");
+      },
+      CASE_MS
+    );
+    it9(
+      "a handler that throws leaves publish resolved and every other handler called",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const results = [];
+          await bus.subscribe("error.test.v1", async () => {
+            throw new Error("boom");
+          });
+          await bus.subscribe("error.test.v1", async () => void results.push("ok"));
+          await expect9(bus.publish(makeEvent("error.test.v1"))).resolves.toBeUndefined();
+          expect9(results).toEqual(["ok"]);
         });
-        await bus.subscribe("error.test.v1", async () => void results.push("ok"));
-        await expect9(bus.publish(makeEvent("error.test.v1"))).resolves.toBeUndefined();
-        expect9(results).toEqual(["ok"]);
-      });
-    }, CASE_MS);
-    it9("replay reaches derived subscriptions only", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const derived = [];
-        const sideEffect = [];
-        await bus.subscribe("replay.test.v1", async (e) => void derived.push(e.id), {
-          name: "contract-projection",
-          derived: true
+      },
+      CASE_MS
+    );
+    it9(
+      "replay reaches derived subscriptions only",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const derived = [];
+          const sideEffect = [];
+          await bus.subscribe("replay.test.v1", async (e) => void derived.push(e.id), {
+            name: "contract-projection",
+            derived: true
+          });
+          await bus.subscribe("replay.test.v1", async (e) => void sideEffect.push(e.id), {
+            name: "contract-side-effect"
+          });
+          const events = [makeEvent("replay.test.v1"), makeEvent("replay.test.v1")];
+          await bus.replay(events);
+          expect9(derived).toEqual(events.map((e) => e.id));
+          expect9(sideEffect).toEqual([]);
         });
-        await bus.subscribe("replay.test.v1", async (e) => void sideEffect.push(e.id), {
-          name: "contract-side-effect"
+      },
+      CASE_MS
+    );
+    it9(
+      "publishBatch reaches each subscription in batch order, through wildcards and pattern arrays",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const wildcard = [];
+          const listed = [];
+          await bus.subscribe("batch.*", async (e) => void wildcard.push(e.id));
+          await bus.subscribe(["batch.a.v1", "batch.c.v1"], async (e) => void listed.push(e.id), {
+            name: "contract-listed"
+          });
+          const events = ["batch.a.v1", "batch.b.v1", "batch.c.v1", "batch.a.v1"].map(
+            (t, seq) => makeEvent(t, { seq })
+          );
+          await bus.publishBatch(events);
+          expect9(wildcard).toEqual(events.map((e) => e.id));
+          expect9(listed).toEqual(events.filter((e) => e.type !== "batch.b.v1").map((e) => e.id));
         });
-        const events = [makeEvent("replay.test.v1"), makeEvent("replay.test.v1")];
-        await bus.replay(events);
-        expect9(derived).toEqual(events.map((e) => e.id));
-        expect9(sideEffect).toEqual([]);
-      });
-    }, CASE_MS);
-    it9("publishBatch reaches each subscription in batch order, through wildcards and pattern arrays", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const wildcard = [];
-        const listed = [];
-        await bus.subscribe("batch.*", async (e) => void wildcard.push(e.id));
-        await bus.subscribe(["batch.a.v1", "batch.c.v1"], async (e) => void listed.push(e.id), {
-          name: "contract-listed"
+      },
+      CASE_MS
+    );
+    it9(
+      "an unsubscribed handler receives nothing more",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const received = [];
+          const sub = await bus.subscribe("unsub.event.v1", async (e) => void received.push(e.id));
+          const before = makeEvent("unsub.event.v1");
+          await bus.publish(before);
+          await bus.unsubscribe(sub);
+          await bus.publish(makeEvent("unsub.event.v1"));
+          expect9(received).toEqual([before.id]);
         });
-        const events = ["batch.a.v1", "batch.b.v1", "batch.c.v1", "batch.a.v1"].map(
-          (t, seq) => makeEvent(t, { seq })
-        );
-        await bus.publishBatch(events);
-        expect9(wildcard).toEqual(events.map((e) => e.id));
-        expect9(listed).toEqual(events.filter((e) => e.type !== "batch.b.v1").map((e) => e.id));
-      });
-    }, CASE_MS);
-    it9("an unsubscribed handler receives nothing more", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const received = [];
-        const sub = await bus.subscribe("unsub.event.v1", async (e) => void received.push(e.id));
-        const before = makeEvent("unsub.event.v1");
-        await bus.publish(before);
-        await bus.unsubscribe(sub);
-        await bus.publish(makeEvent("unsub.event.v1"));
-        expect9(received).toEqual([before.id]);
-      });
-    }, CASE_MS);
-    it9("on one instance, a named and an unnamed subscription each handle every event once", async () => {
-      const bus = await make();
-      await using3([bus], async () => {
-        const named = [];
-        const unnamed = [];
-        await bus.subscribe("both.event.v1", async (e) => void named.push(e.id), {
-          name: "contract-named"
+      },
+      CASE_MS
+    );
+    it9(
+      "on one instance, a named and an unnamed subscription each handle every event once",
+      async () => {
+        const bus = await make();
+        await using3([bus], async () => {
+          const named = [];
+          const unnamed = [];
+          await bus.subscribe("both.event.v1", async (e) => void named.push(e.id), {
+            name: "contract-named"
+          });
+          await bus.subscribe("both.event.v1", async (e) => void unnamed.push(e.id));
+          const events = [makeEvent("both.event.v1"), makeEvent("both.event.v1")];
+          for (const e of events) await bus.publish(e);
+          expect9(named).toEqual(events.map((e) => e.id));
+          expect9(unnamed).toEqual(named);
         });
-        await bus.subscribe("both.event.v1", async (e) => void unnamed.push(e.id));
-        const events = [makeEvent("both.event.v1"), makeEvent("both.event.v1")];
-        for (const e of events) await bus.publish(e);
-        expect9(named).toEqual(events.map((e) => e.id));
-        expect9(unnamed).toEqual(named);
-      });
-    }, CASE_MS);
+      },
+      CASE_MS
+    );
     eventBusDeliveryCases(make, opts);
+    eventBusFailureCases(make, opts);
     healthAndDowntime(
       make,
       opts.unreachable,
@@ -1636,7 +1978,7 @@ function runEventBusContract(name, make, opts = {}) {
           expect9(onB.filter((id) => ids2.includes(id))).toEqual(ids2);
         });
       },
-      SLOW5
+      SLOW6
     );
   });
 }
@@ -1685,7 +2027,7 @@ function runMediaStorageContract(name, make, options) {
 }
 
 // src/payments.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import { describe as describe10, expect as expect11, it as it11 } from "vitest";
 var TOTAL = 1999;
 async function rejectionCode(call) {
@@ -1703,7 +2045,7 @@ function runPaymentsContract(name, build, options = {}) {
         const intent = await adapter.createPaymentIntent({
           amountMinor: 1e3,
           currency: "GBP",
-          orderRef: `contract-${randomUUID3()}`
+          orderRef: `contract-${randomUUID4()}`
         });
         expect11(intent.id).toBeTruthy();
         expect11(intent.clientSecret).toBeTruthy();
@@ -1738,11 +2080,11 @@ function runPaymentsContract(name, build, options = {}) {
         const intent = await adapter.createPaymentIntent({
           amountMinor: TOTAL,
           currency: "GBP",
-          orderRef: `contract-${randomUUID3()}`
+          orderRef: `contract-${randomUUID4()}`
         });
         if (intent.status !== "succeeded") await adapter.capturePayment(intent.id);
         const half = Math.floor(TOTAL / 2);
-        const key = `contract-refund-${randomUUID3()}`;
+        const key = `contract-refund-${randomUUID4()}`;
         const first = await adapter.refund(intent.id, half, "requested_by_customer", {
           idempotencyKey: key
         });
@@ -1788,11 +2130,11 @@ function runPaymentsContract(name, build, options = {}) {
 }
 
 // src/reviews.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 import fc4 from "fast-check";
 import { describe as describe11, expect as expect12, it as it12 } from "vitest";
 async function seed(adapter, count) {
-  const productId = `contract-reviews-${randomUUID4()}`;
+  const productId = `contract-reviews-${randomUUID5()}`;
   const seeded = [];
   for (let i = 0; i < count; i++) {
     const { review } = await adapter.submitReview({
@@ -1827,7 +2169,7 @@ function runReviewsContract(name, build, options = {}) {
       "submitReview returns the created review",
       async () => {
         const adapter = await build();
-        const productId = `contract-reviews-${randomUUID4()}`;
+        const productId = `contract-reviews-${randomUUID5()}`;
         const { review } = await adapter.submitReview({
           productId,
           customerId: null,
@@ -1908,13 +2250,13 @@ function runReviewsContract(name, build, options = {}) {
       build,
       options.unreachable,
       "getProductReviews()",
-      (adapter) => adapter.getProductReviews(`contract-reviews-${randomUUID4()}`, { limit: 1 })
+      (adapter) => adapter.getProductReviews(`contract-reviews-${randomUUID5()}`, { limit: 1 })
     );
   });
 }
 
 // src/search.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 import fc5 from "fast-check";
 import { describe as describe12, expect as expect13, it as it13 } from "vitest";
 
@@ -1958,7 +2300,7 @@ function tierOf(p, query) {
 
 // src/search.ts
 function runToken() {
-  return `t${randomUUID5().replace(/-/g, "").slice(0, 15)}`;
+  return `t${randomUUID6().replace(/-/g, "").slice(0, 15)}`;
 }
 var word = fc5.string({
   unit: fc5.constantFrom("a", "b", "c", "d", "1", "2"),
@@ -2029,7 +2371,7 @@ function expectExactWalk(pages, expected, limit, label) {
       expect13(page.items.length, `${label}: page ${i + 1} is empty`).toBeGreaterThan(0);
   }
 }
-var SLOW6 = 18e4;
+var SLOW7 = 18e4;
 function runSearchContract(name, build, options = {}) {
   const numRuns = options.numRuns ?? 25;
   describe12(`SearchAdapter contract: ${name}`, () => {
@@ -2062,7 +2404,7 @@ function runSearchContract(name, build, options = {}) {
       "remove deletes documents from index",
       async () => {
         const adapter = await build();
-        const tag = `remove-${randomUUID5()}`;
+        const tag = `remove-${randomUUID6()}`;
         await adapter.index([{ id: tag, type: "product", fields: { name: "To Remove" } }]);
         await adapter.remove([tag]);
         const result = await adapter.search("To Remove");
@@ -2161,7 +2503,7 @@ function runSearchContract(name, build, options = {}) {
             { numRuns }
           );
         },
-        SLOW6
+        SLOW7
       );
       if (options.ranking) {
         it13(
@@ -2226,7 +2568,7 @@ function runSearchContract(name, build, options = {}) {
               { numRuns }
             );
           },
-          SLOW6
+          SLOW7
         );
       }
       if (options.facets) {
@@ -2276,7 +2618,7 @@ function runSearchContract(name, build, options = {}) {
               { numRuns }
             );
           },
-          SLOW6
+          SLOW7
         );
       }
       describe12("hostile input", () => {
@@ -2355,7 +2697,7 @@ function runSearchContract(name, build, options = {}) {
               }
             );
           },
-          SLOW6
+          SLOW7
         );
         it13(
           "input with no terms returns no items, total 0 and no next page, over an index that holds products",
@@ -2395,7 +2737,7 @@ function runSearchContract(name, build, options = {}) {
               await adapter.remove(products.map((p) => p.id));
             }
           },
-          SLOW6
+          SLOW7
         );
         it13(
           "a malformed cursor (undecodable, negative, non-integer) rejects, and a cursor at or past total, as after a removal between two pages, is an empty page with nextCursor null",
@@ -2449,7 +2791,7 @@ function runSearchContract(name, build, options = {}) {
               await adapter.remove(products.map((p) => p.id));
             }
           },
-          SLOW6
+          SLOW7
         );
       });
     });
@@ -2542,8 +2884,72 @@ function adapterContext(slot, config, env = {}) {
   return { slot, config, logger: silent, env };
 }
 
-// src/security.ts
+// src/webhook.ts
 import { describe as describe15, expect as expect16, it as it16 } from "vitest";
+import {
+  webhookDeliveryProblem
+} from "@nymbalhq/types";
+function receiving(adapter) {
+  expect16(typeof adapter.receiveWebhook, "the adapter has no receiveWebhook").toBe("function");
+  return adapter;
+}
+async function receive(adapter, request) {
+  return receiving(adapter).receiveWebhook(request.rawBody, request.headers);
+}
+function runWebhookContract(name, build, options) {
+  describe15(`webhook contract: ${name}`, () => {
+    it16(
+      "idempotency: one delivery received twice gives one deliveryId and equal events",
+      () => using(build, async (adapter) => {
+        const first = await receive(adapter, options.delivery());
+        const second = await receive(adapter, options.delivery());
+        expect16(first.verified, "the signed delivery was not verified").toBe(true);
+        expect16(typeof first.deliveryId === "string" && first.deliveryId !== "").toBe(true);
+        expect16(second.deliveryId, "the same delivery got another deliveryId").toBe(
+          first.deliveryId
+        );
+        expect16(second.events).toEqual(first.events);
+      }),
+      CASE_MS
+    );
+    const tampered = options.tampered;
+    if (tampered !== void 0) {
+      it16(
+        "verification: a tampered delivery is not verified",
+        () => using(build, async (adapter) => {
+          const outcome = await receive(adapter, tampered()).then(
+            (delivery) => ({ verified: delivery.verified, code: null }),
+            (err) => ({
+              verified: false,
+              code: err?.code
+            })
+          );
+          expect16(outcome.verified, "a tampered delivery was verified").toBe(false);
+          if (outcome.code !== null) expect16(String(outcome.code)).toMatch(/webhook_invalid$/);
+        }),
+        CASE_MS
+      );
+    }
+    it16(
+      "namespace: every event is the adapter's own, declared and versioned",
+      () => using(build, async (adapter) => {
+        const delivery = await receive(adapter, options.delivery());
+        expect16(delivery.verified, "the signed delivery was not verified").toBe(true);
+        expect16(delivery.events.length, "the delivery carried no event to check").toBeGreaterThan(
+          0
+        );
+        expect16(
+          webhookDeliveryProblem(adapter.providerName, adapter.producesEvents, delivery),
+          "the kernel would refuse this delivery"
+        ).toBeNull();
+      }),
+      CASE_MS
+    );
+  });
+}
+
+// src/security.ts
+import { describe as describe16, expect as expect17, it as it17 } from "vitest";
 var testConfig = {
   rateLimit: {
     api: { requests: 100, window: "1m", action: "block" }
@@ -2557,24 +2963,24 @@ var testConfig = {
   }
 };
 function runSecurityContract(name, build, options = {}) {
-  describe15(`SecurityAdapter contract: ${name}`, () => {
-    it16(
+  describe16(`SecurityAdapter contract: ${name}`, () => {
+    it17(
       "validate accepts a valid config",
       async () => {
         const adapter = await build();
         const result = await adapter.validate(testConfig);
-        expect16(typeof result.valid).toBe("boolean");
-        expect16(Array.isArray(result.errors)).toBe(true);
+        expect17(typeof result.valid).toBe("boolean");
+        expect17(Array.isArray(result.errors)).toBe(true);
       },
       CASE_MS
     );
-    it16(
+    it17(
       "validate of empty config reports errors",
       async () => {
         const adapter = await build();
         const result = await adapter.validate({});
         if (!result.valid) {
-          expect16(result.errors.length).toBeGreaterThan(0);
+          expect17(result.errors.length).toBeGreaterThan(0);
         }
       },
       CASE_MS
@@ -2589,7 +2995,7 @@ function runSecurityContract(name, build, options = {}) {
 }
 
 // src/projection.ts
-import { describe as describe16, it as it17, expect as expect17 } from "vitest";
+import { describe as describe17, it as it18, expect as expect18 } from "vitest";
 function makeEvent2(id) {
   return {
     id,
@@ -2602,26 +3008,26 @@ function makeEvent2(id) {
   };
 }
 function runProjectionContract(opts) {
-  describe16("Projection idempotency contract", () => {
-    it17("processing the same event twice applies the mutation only once", async () => {
+  describe17("Projection idempotency contract", () => {
+    it18("processing the same event twice applies the mutation only once", async () => {
       const ctx = await opts.build();
-      const event2 = makeEvent2("dedup-evt-001");
-      await ctx.handle(event2);
-      await ctx.handle(event2);
-      expect17(await ctx.applicationCount()).toBe(1);
+      const event3 = makeEvent2("dedup-evt-001");
+      await ctx.handle(event3);
+      await ctx.handle(event3);
+      expect18(await ctx.applicationCount()).toBe(1);
     });
-    it17("distinct events each apply their mutation", async () => {
+    it18("distinct events each apply their mutation", async () => {
       const ctx = await opts.build();
       await ctx.handle(makeEvent2("distinct-evt-001"));
       await ctx.handle(makeEvent2("distinct-evt-002"));
-      expect17(await ctx.applicationCount()).toBe(2);
+      expect18(await ctx.applicationCount()).toBe(2);
     });
-    it17("after reprocessing a batch the count equals unique event count", async () => {
+    it18("after reprocessing a batch the count equals unique event count", async () => {
       const ctx = await opts.build();
       const events = [makeEvent2("batch-001"), makeEvent2("batch-002"), makeEvent2("batch-003")];
       for (const e of events) await ctx.handle(e);
       for (const e of events) await ctx.handle(e);
-      expect17(await ctx.applicationCount()).toBe(3);
+      expect18(await ctx.applicationCount()).toBe(3);
     });
   });
 }
@@ -2640,13 +3046,16 @@ var suites = {
   analytics: runAnalyticsContract,
   shipping: runShippingContract,
   tax: runTaxContract,
-  ai: runAiContract,
   documentStore: runDocumentStoreContract,
   eventBus: runEventBusContract,
-  media: (name, build, options = {}) => runMediaStorageContract(name, build, {
-    fetchUrl: fetchOverHttp,
-    ...options
-  })
+  media: (name, build, options = {}) => runMediaStorageContract(
+    name,
+    build,
+    {
+      fetchUrl: fetchOverHttp,
+      ...options
+    }
+  )
 };
 var contractSuites = suites;
 export {
@@ -2655,7 +3064,6 @@ export {
   adapterContext,
   contractSuites,
   matchesQuery,
-  runAiContract,
   runAnalyticsContract,
   runDocumentStoreContract,
   runEmailContract,
@@ -2668,6 +3076,7 @@ export {
   runSecurityContract,
   runShippingContract,
   runTaxContract,
+  runWebhookContract,
   searchTerms,
   toSearchDocument
 };