@bumail/queue 0.11.0 → 0.12.0

package/dist/conformance/index.js

@@ -0,0 +1,820 @@
+// src/conformance/describe-queue-store.ts
+import { afterEach, describe as describe5 } from "bun:test";
+
+// src/conformance/claims.ts
+import { describe, expect as expect2, test } from "bun:test";
+
+// src/conformance/setup.ts
+import { expect } from "bun:test";
+var bytes = (text) => new TextEncoder().encode(text);
+var T0 = Date.UTC(2026, 9, 1, 12);
+var MINUTE = 60000;
+var lease = { leaseMs: 10 * MINUTE };
+var result = (overrides = {}) => ({
+  now: T0 + MINUTE,
+  recipients: [],
+  nextAttemptAt: T0 + 30 * MINUTE,
+  attempts: 1,
+  delayNotified: false,
+  ...overrides
+});
+function entry(overrides = {}) {
+  return {
+    from: "mary@example.net",
+    to: ["joe@example.com", "ann@example.org"],
+    message: bytes(`Subject: Hi\r
+\r
+Hello\r
+`),
+    createdAt: T0,
+    ...overrides
+  };
+}
+async function rejects(promise, code) {
+  await expect(promise).rejects.toMatchObject({ name: "QueueError", code });
+}
+
+// src/conformance/claims.ts
+var lease2 = { leaseMs: 10 * MINUTE };
+var result2 = (overrides = {}) => ({
+  now: T0 + MINUTE,
+  recipients: [],
+  nextAttemptAt: T0 + 30 * MINUTE,
+  attempts: 1,
+  delayNotified: false,
+  ...overrides
+});
+function describeClaims(factories) {
+  describe("claims and leases", () => {
+    claiming(factories);
+    leasing(factories);
+    rescheduling(factories);
+  });
+}
+function claiming({ create }) {
+  test("claim takes a due item with a lease; nothing else is due", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    const claimed = await store.claim({ owner: "w1", now: T0, ...lease2 });
+    expect2(claimed?.id).toBe(item.id);
+    expect2(claimed?.lease).toEqual({
+      owner: "w1",
+      expiresAt: T0 + 10 * MINUTE
+    });
+    expect2((await store.get(item.id))?.lease?.owner).toBe("w1");
+    expect2(await store.claim({ owner: "w2", now: T0, ...lease2 })).toBeUndefined();
+  });
+  test("an item not yet due is not claimed", async () => {
+    const store = await create();
+    await store.add(entry({ createdAt: T0 + MINUTE }));
+    expect2(await store.claim({ owner: "w1", now: T0, ...lease2 })).toBeUndefined();
+    expect2(await store.claim({ owner: "w1", now: T0 + MINUTE, ...lease2 })).toBeDefined();
+  });
+  test("the earliest due is claimed first, then the oldest", async () => {
+    const store = await create();
+    const late = await store.add(entry({ createdAt: T0 + MINUTE }));
+    const first = await store.add(entry());
+    const second = await store.add(entry());
+    const now = T0 + MINUTE;
+    const order = [];
+    for (let i = 0;i < 3; i++) {
+      order.push((await store.claim({ owner: "w", now, ...lease2 }))?.id);
+    }
+    expect2(order).toEqual([first.id, second.id, late.id]);
+  });
+}
+function leasing({ create }) {
+  test("an expired lease is claimed again, and its old owner has lost it", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "crashed", now: T0, leaseMs: MINUTE });
+    expect2(await store.claim({ owner: "w2", now: T0 + MINUTE - 1, ...lease2 })).toBeUndefined();
+    const again = await store.claim({
+      owner: "w2",
+      now: T0 + MINUTE,
+      ...lease2
+    });
+    expect2(again?.id).toBe(item.id);
+    expect2(again?.lease?.owner).toBe("w2");
+    expect2(await store.renew(item.id, "crashed", T0 + 5 * MINUTE)).toBe(false);
+    expect2(await store.complete(item.id, "crashed", result2(), [])).toBeUndefined();
+    expect2(await store.reschedule(item.id, T0, "crashed")).toBe(false);
+    expect2((await store.get(item.id))?.lease?.owner).toBe("w2");
+  });
+  test("renew moves the expiry while the owner holds the lease", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, leaseMs: MINUTE });
+    expect2(await store.renew(item.id, "w1", T0 + 3 * MINUTE)).toBe(true);
+    expect2(await store.claim({ owner: "w2", now: T0 + 2 * MINUTE, ...lease2 })).toBeUndefined();
+    expect2(await store.renew("nope", "w1", T0)).toBe(false);
+  });
+}
+function rescheduling({ create }) {
+  test("reschedule with the owner gives the item back, due at the new time", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease2 });
+    expect2(await store.reschedule(item.id, T0 + MINUTE, "w2")).toBe(false);
+    expect2(await store.reschedule(item.id, T0 + MINUTE, "w1")).toBe(true);
+    const stored = await store.get(item.id);
+    expect2(stored?.lease).toBeUndefined();
+    expect2(stored?.nextAttemptAt).toBe(T0 + MINUTE);
+    expect2(stored?.attempts).toBe(0);
+  });
+  test("reschedule without an owner moves the time and leaves the lease alone", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease2 });
+    await store.complete(item.id, "w1", result2(), []);
+    expect2(await store.reschedule(item.id, T0 + MINUTE)).toBe(true);
+    expect2((await store.claim({ owner: "w2", now: T0 + MINUTE, ...lease2 }))?.id).toBe(item.id);
+    expect2(await store.reschedule(item.id, T0)).toBe(true);
+    expect2((await store.get(item.id))?.lease?.owner).toBe("w2");
+  });
+  test("claim refuses a bad request", async () => {
+    const store = await create();
+    await rejects(store.claim({ owner: "", now: T0, ...lease2 }), "INVALID");
+    await rejects(store.claim({ owner: "w", now: T0, leaseMs: 0 }), "INVALID");
+    await rejects(store.claim({ owner: "w", now: Number.NaN, ...lease2 }), "INVALID");
+    await rejects(store.reschedule("nope", T0, ""), "INVALID");
+  });
+}
+
+// src/conformance/concurrency.ts
+import { describe as describe2, expect as expect3, test as test2 } from "bun:test";
+var delivered = (now) => ({
+  now,
+  recipients: [
+    { address: "joe@example.com", status: "delivered" },
+    { address: "ann@example.org", status: "delivered" }
+  ],
+  nextAttemptAt: now,
+  attempts: 1,
+  delayNotified: false
+});
+async function work(store, owner, now) {
+  const taken = [];
+  for (;; ) {
+    await new Promise((resolve) => setTimeout(resolve, Math.random() * 2));
+    const item = await store.claim({ owner, now, leaseMs: 10 * MINUTE });
+    if (!item)
+      return taken;
+    taken.push(item.id);
+    await new Promise((resolve) => setTimeout(resolve, Math.random() * 2));
+    const done = await store.complete(item.id, owner, delivered(now), []);
+    expect3(done).toBeDefined();
+  }
+}
+function describeConcurrency({ create, share }) {
+  const shared = share ? test2 : test2.skip;
+  const note = share ? "" : " (skipped: harness has no share)";
+  describe2("several workers", () => {
+    shared(`many claimers race: every item is delivered once${note}`, async () => {
+      const store = await create();
+      const ids = new Set;
+      for (let i = 0;i < 60; i++)
+        ids.add((await store.add(entry())).id);
+      const workers = Array.from({ length: 8 }, (_, i) => work(share?.(store) ?? store, `w${i}`, T0));
+      const taken = (await Promise.all(workers)).flat();
+      expect3(taken.length).toBe(60);
+      expect3(new Set(taken)).toEqual(ids);
+      expect3(await store.count()).toBe(0);
+    });
+    shared(`a crashed worker’s items are claimed again once its leases expire${note}`, async () => {
+      const store = await create();
+      for (let i = 0;i < 5; i++)
+        await store.add(entry());
+      const crashed = [];
+      for (let i = 0;i < 5; i++) {
+        const item = await store.claim({
+          owner: "crashed",
+          now: T0,
+          leaseMs: MINUTE
+        });
+        if (item)
+          crashed.push(item.id);
+      }
+      expect3(crashed.length).toBe(5);
+      const other = share?.(store) ?? store;
+      expect3(await work(other, "w2", T0 + MINUTE - 1)).toEqual([]);
+      const recovered = await work(other, "w2", T0 + MINUTE);
+      expect3(new Set(recovered)).toEqual(new Set(crashed));
+      for (const id of crashed) {
+        expect3(await store.complete(id, "crashed", delivered(T0), [])).toBeUndefined();
+      }
+      expect3(await store.count()).toBe(0);
+    });
+  });
+}
+
+// src/conformance/items.ts
+import { describe as describe3, expect as expect5, test as test4 } from "bun:test";
+
+// src/conformance/dsn.ts
+import { expect as expect4, test as test3 } from "bun:test";
+function dsnParameters({ create }) {
+  const asked = {
+    ret: "HDRS",
+    envid: "QQ314159 + x=",
+    recipients: [
+      {
+        address: "joe@example.com",
+        notify: ["SUCCESS", "DELAY"],
+        orcpt: { type: "rfc822", address: "Joe.Original@example.com" }
+      },
+      { address: "ann@example.org", notify: "NEVER" }
+    ]
+  };
+  test3("RFC 3461 §4: ret, envid, notify and orcpt are kept by add, get, list and claim", async () => {
+    const store = await create();
+    const item = await store.add(entry(asked));
+    const kept = {
+      ret: "HDRS",
+      envid: "QQ314159 + x=",
+      recipients: [
+        {
+          address: "joe@example.com",
+          notify: ["SUCCESS", "DELAY"],
+          orcpt: { type: "rfc822", address: "Joe.Original@example.com" }
+        },
+        { address: "ann@example.org", notify: "NEVER" }
+      ]
+    };
+    expect4(item).toMatchObject(kept);
+    expect4(await store.get(item.id)).toEqual(item);
+    expect4((await store.list())[0]).toEqual(item);
+    expect4(await store.claim({ owner: "w1", now: T0, ...lease })).toMatchObject(kept);
+  });
+  test3("complete keeps them: the notify and orcpt of a deferred recipient, and the item level", async () => {
+    const store = await create();
+    const item = await store.add(entry(asked));
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const done = await store.complete(item.id, "w1", result({
+      recipients: [
+        {
+          address: "joe@example.com",
+          status: "deferred",
+          reply: { text: "try later" }
+        }
+      ]
+    }), []);
+    expect4(done?.item.recipients[0]).toMatchObject({
+      notify: ["SUCCESS", "DELAY"],
+      orcpt: { type: "rfc822", address: "Joe.Original@example.com" }
+    });
+    const again = await store.get(item.id);
+    expect4(again?.ret).toBe("HDRS");
+    expect4(again?.envid).toBe("QQ314159 + x=");
+    expect4(again?.recipients[1]?.notify).toBe("NEVER");
+  });
+  test3("an item added with none carries none: the fields are absent, as before", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    const read = await store.get(item.id);
+    for (const key of ["ret", "envid"]) {
+      expect4(read).not.toHaveProperty(key);
+    }
+    for (const r of read?.recipients ?? []) {
+      expect4(r).not.toHaveProperty("notify");
+      expect4(r).not.toHaveProperty("orcpt");
+    }
+  });
+  test3("RFC 6533: 50 emoji in a utf-8 ORCPT are within 500 characters, as the server counts them", async () => {
+    const store = await create();
+    const orcpt = { type: "utf-8", address: `${"\uD83D\uDE00".repeat(50)}@x` };
+    const item = await store.add(entry({ recipients: [{ address: "joe@example.com", orcpt }] }));
+    expect4(item.recipients[0]?.orcpt).toEqual(orcpt);
+    await expect4(store.add(entry({
+      recipients: [
+        {
+          address: "joe@example.com",
+          orcpt: { type: "rfc822", address: orcpt.address }
+        }
+      ]
+    }))).rejects.toMatchObject({ code: "INVALID" });
+  });
+  test3("RFC 6533: a utf-8 ORCPT of 500 characters (82 escapes) is kept, 506 is INVALID", async () => {
+    const store = await create();
+    const orcpt = (n) => ({
+      type: "utf-8",
+      address: `${"+".repeat(n)}@x`
+    });
+    const item = await store.add(entry({ recipients: [{ address: "joe@example.com", orcpt: orcpt(82) }] }));
+    expect4(item.recipients[0]?.orcpt).toEqual(orcpt(82));
+    await rejects(store.add(entry({
+      recipients: [{ address: "joe@example.com", orcpt: orcpt(83) }]
+    })), "INVALID");
+  });
+  test3("what is not a parameter is INVALID, the same for every store", async () => {
+    const store = await create();
+    const bad = [
+      { ret: "ALL" },
+      { envid: "" },
+      { envid: `a\r
+b` },
+      { envid: "x".repeat(101) },
+      { recipients: [{ address: "zed@example.com", notify: "NEVER" }] },
+      { recipients: [{ address: "joe@example.com", notify: "SOMETIMES" }] },
+      { recipients: [{ address: "joe@example.com", notify: [] }] },
+      {
+        recipients: [
+          { address: "joe@example.com", notify: ["DELAY", "DELAY"] }
+        ]
+      },
+      {
+        recipients: [{ address: "joe@example.com", orcpt: { type: "rfc822" } }]
+      },
+      {
+        recipients: [
+          { address: "joe@example.com" },
+          { address: "joe@example.com" }
+        ]
+      }
+    ];
+    for (const params of bad) {
+      await rejects(store.add(entry(params)), "INVALID");
+    }
+    expect4(await store.count()).toBe(0);
+  });
+}
+
+// src/conformance/items.ts
+function describeItems(factories) {
+  describe3("items", () => {
+    adding(factories);
+    listing(factories);
+    dsnParameters(factories);
+  });
+}
+function adding({ create }) {
+  test4("add keeps the envelope, every recipient pending, due at once", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    expect5(item).toMatchObject({
+      from: "mary@example.net",
+      recipients: [
+        { address: "joe@example.com", status: "pending" },
+        { address: "ann@example.org", status: "pending" }
+      ],
+      size: 22,
+      createdAt: T0,
+      nextAttemptAt: T0,
+      attempts: 0,
+      delayNotified: false
+    });
+    expect5(item.lease).toBeUndefined();
+    expect5(await store.get(item.id)).toEqual(item);
+    expect5(await store.count()).toBe(1);
+  });
+  test4("the null sender is kept as the empty string", async () => {
+    const store = await create();
+    const item = await store.add(entry({ from: "" }));
+    expect5((await store.get(item.id))?.from).toBe("");
+  });
+  test4("readMessage gives the bytes back, a copy each time", async () => {
+    const store = await create();
+    const message = bytes(`Subject: x\r
+\r
+body\r
+`);
+    const item = await store.add(entry({ message }));
+    message[0] = 0;
+    const read = await store.readMessage(item.id);
+    expect5(new TextDecoder().decode(read)).toBe(`Subject: x\r
+\r
+body\r
+`);
+    if (read)
+      read[0] = 0;
+    expect5((await store.readMessage(item.id))?.[0]).toBe(83);
+  });
+  test4("an item returned is a copy", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    const first = item.recipients[0];
+    if (first)
+      first.status = "failed";
+    expect5((await store.get(item.id))?.recipients[0]?.status).toBe("pending");
+  });
+  test4("an unknown id is undefined, not an error", async () => {
+    const store = await create();
+    expect5(await store.get("nope")).toBeUndefined();
+    expect5(await store.readMessage("nope")).toBeUndefined();
+    expect5(await store.cancel("nope")).toBeUndefined();
+    expect5(await store.reschedule("nope", T0)).toBe(false);
+  });
+  test4("an id no store could hold, a NUL or a lone surrogate in it, is unknown too", async () => {
+    const store = await create();
+    await store.add(entry());
+    for (const id of ["a\x00b", "a\uD83D"]) {
+      expect5(await store.get(id)).toBeUndefined();
+      expect5(await store.readMessage(id)).toBeUndefined();
+      expect5(await store.renew(id, "w1", T0)).toBe(false);
+      expect5(await store.reschedule(id, T0)).toBe(false);
+      expect5(await store.cancel(id)).toBeUndefined();
+    }
+    expect5(await store.count()).toBe(1);
+  });
+}
+function listing({ create }) {
+  test4("list gives the next due first, then the oldest, a page at a time", async () => {
+    const store = await create();
+    const a = await store.add(entry({ createdAt: T0 + 2 * MINUTE }));
+    const b = await store.add(entry({ createdAt: T0 }));
+    const c = await store.add(entry({ createdAt: T0 }));
+    const ids = (await store.list()).map((i) => i.id);
+    expect5(ids).toEqual([b.id, c.id, a.id]);
+    const page = await store.list({ offset: 1, limit: 1 });
+    expect5(page.map((i) => i.id)).toEqual([c.id]);
+  });
+  test4("list refuses a bad page", async () => {
+    const store = await create();
+    await rejects(store.list({ limit: 0 }), "INVALID");
+    await rejects(store.list({ offset: -1 }), "INVALID");
+  });
+  test4("cancel drops the item and its message, leased or not", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, leaseMs: MINUTE });
+    const cancelled = await store.cancel(item.id);
+    expect5(cancelled?.id).toBe(item.id);
+    expect5(await store.get(item.id)).toBeUndefined();
+    expect5(await store.readMessage(item.id)).toBeUndefined();
+    expect5(await store.count()).toBe(0);
+  });
+  test4("maxItems refuses an add past the limit with QUEUE_FULL", async () => {
+    const store = await create();
+    await store.add(entry(), { maxItems: 2 });
+    await store.add(entry(), { maxItems: 2 });
+    await rejects(store.add(entry(), { maxItems: 2 }), "QUEUE_FULL");
+    expect5(await store.count()).toBe(2);
+    await rejects(store.add(entry(), { maxItems: 0 }), "INVALID");
+  });
+  test4("add refuses what is not an item", async () => {
+    const store = await create();
+    await rejects(store.add(entry({ to: [] })), "INVALID");
+    await rejects(store.add(entry({ message: "text" })), "INVALID");
+    await rejects(store.add(entry({ createdAt: Number.NaN })), "INVALID");
+    await rejects(store.add(entry({ from: "a\x00@example.net" })), "INVALID");
+    await rejects(store.add(entry({ to: ["jo\uD83D@example.com"] })), "INVALID");
+    expect5(await store.count()).toBe(0);
+  });
+}
+
+// src/conformance/outcomes.ts
+import { describe as describe4, expect as expect8, test as test7 } from "bun:test";
+
+// src/conformance/complete-dsns.ts
+import { expect as expect6, test as test5 } from "bun:test";
+var dsn = (text) => entry({
+  from: "",
+  to: ["mary@example.net"],
+  message: bytes(`Subject: ${text}\r
+\r
+${text}\r
+`)
+});
+var delivered2 = result({
+  recipients: [
+    { address: "joe@example.com", status: "delivered" },
+    { address: "ann@example.org", status: "failed" }
+  ]
+});
+function completeDsns(factories) {
+  stored(factories);
+  leaseHeld(factories);
+  refused(factories);
+  notFinal(factories);
+}
+function stored({ create }) {
+  test5("complete stores its DSNs with the outcome: new ids, in the order given, due at once", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const done = await store.complete(item.id, "w1", delivered2, [
+      dsn("failed"),
+      dsn("relayed")
+    ]);
+    expect6(done?.item.id).toBe(item.id);
+    expect6(done?.dsns).toHaveLength(2);
+    const [first, second] = done?.dsns ?? [];
+    expect6(first?.id).not.toBe(second?.id);
+    expect6([first?.id, second?.id]).not.toContain(item.id);
+    expect6(first).toMatchObject({ from: "", attempts: 0 });
+    expect6(await store.get(item.id)).toBeUndefined();
+    for (const [kept, subject] of [
+      [first, "failed"],
+      [second, "relayed"]
+    ]) {
+      expect6(await store.get(kept?.id ?? "")).toEqual(kept);
+      expect6(new TextDecoder().decode(await store.readMessage(kept?.id ?? ""))).toContain(`Subject: ${subject}`);
+    }
+    expect6((await store.claim({ owner: "w2", now: T0 + MINUTE, ...lease }))?.id).toBe(first?.id);
+    expect6(await store.count()).toBe(2);
+  });
+}
+function leaseHeld({ create }) {
+  test5("complete by an owner that no longer holds the lease stores no DSN, and a second one by the first stores none twice", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    expect6(await store.complete(item.id, "w2", delivered2, [dsn("failed")])).toBeUndefined();
+    expect6(await store.count()).toBe(1);
+    expect6(await store.complete(item.id, "w1", delivered2, [dsn("failed")])).toBeDefined();
+    expect6(await store.count()).toBe(1);
+    expect6(await store.complete(item.id, "w1", delivered2, [dsn("failed")])).toBeUndefined();
+    expect6(await store.count()).toBe(1);
+  });
+}
+function refused({ create }) {
+  test5("a DSN that fails the checks of add refuses the whole call with INVALID: no outcome, no DSN", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    await rejects(store.complete(item.id, "w1", delivered2, [
+      dsn("failed"),
+      { ...dsn("bad"), to: [] }
+    ]), "INVALID");
+    expect6(await store.count()).toBe(1);
+    expect6(await store.get(item.id)).toMatchObject({
+      attempts: 0,
+      lease: { owner: "w1" }
+    });
+  });
+  test5("dsns that are not an array refuse the call with INVALID, nothing recorded", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    await rejects(store.complete(item.id, "w1", delivered2, undefined), "INVALID");
+    expect6(await store.get(item.id)).toMatchObject({ attempts: 0 });
+  });
+}
+function notFinal({ create }) {
+  test5("complete with no DSN returns an empty list; a not-final item stays with its DSNs beside it", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const none = await store.complete(item.id, "w1", result(), []);
+    expect6(none?.dsns).toEqual([]);
+    await store.claim({ owner: "w1", now: T0 + 30 * MINUTE, ...lease });
+    const deferred = result({
+      recipients: [{ address: "joe@example.com", status: "deferred" }],
+      attempts: 2,
+      delayNotified: true
+    });
+    const done = await store.complete(item.id, "w1", deferred, [
+      dsn("delayed")
+    ]);
+    expect6(done?.item.delayNotified).toBe(true);
+    expect6(done?.dsns).toHaveLength(1);
+    expect6(await store.count()).toBe(2);
+    expect6(await store.get(item.id)).toEqual(done?.item);
+  });
+}
+
+// src/conformance/doubt.ts
+import { expect as expect7, test as test6 } from "bun:test";
+function doubt({ create }) {
+  const deferred = (mayHaveReachedMx) => ({
+    address: "joe@example.com",
+    status: "deferred",
+    reply: { status: "4.4.2", text: "no reply to the final dot" },
+    ...mayHaveReachedMx === undefined ? {} : { mayHaveReachedMx }
+  });
+  test6("mayHaveReachedMx: recorded, read by get and list, and kept by a later outcome without it", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const done = await store.complete(item.id, "w1", result({ recipients: [deferred(true)] }), []);
+    expect7(done?.item.recipients[0]?.mayHaveReachedMx).toBe(true);
+    expect7(done?.item.recipients[1]).not.toHaveProperty("mayHaveReachedMx");
+    expect7((await store.get(item.id))?.recipients[0]?.mayHaveReachedMx).toBe(true);
+    expect7((await store.list())[0]?.recipients[0]?.mayHaveReachedMx).toBe(true);
+    await store.claim({ owner: "w1", now: T0 + 30 * MINUTE, ...lease });
+    const again = await store.complete(item.id, "w1", result({ recipients: [deferred()], attempts: 2 }), []);
+    expect7(again?.item.recipients[0]?.mayHaveReachedMx).toBe(true);
+    expect7((await store.get(item.id))?.recipients[0]?.mayHaveReachedMx).toBe(true);
+  });
+  test6("mayHaveReachedMx: an unmarked recipient has no such key", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    await store.complete(item.id, "w1", result({ recipients: [deferred()] }), []);
+    for (const r of (await store.get(item.id))?.recipients ?? []) {
+      expect7(r).not.toHaveProperty("mayHaveReachedMx");
+    }
+  });
+  test6("mayHaveReachedMx: a value other than true is INVALID, and the item stays as it was", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    for (const bad of [false, "true", 1, null]) {
+      await rejects(store.complete(item.id, "w1", result({ recipients: [deferred(bad)] }), []), "INVALID");
+    }
+    const kept = await store.get(item.id);
+    expect7(kept?.recipients[0]?.status).toBe("pending");
+    expect7(kept?.lease?.owner).toBe("w1");
+  });
+}
+function fallbackDoubt({ create }) {
+  const deferred = (mayHaveReachedFallback) => ({
+    address: "joe@example.com",
+    status: "deferred",
+    reply: { status: "4.4.2", text: "no reply to the final dot" },
+    ...mayHaveReachedFallback === undefined ? {} : { mayHaveReachedFallback }
+  });
+  test6("mayHaveReachedFallback: recorded, read by get and list, and kept by a later outcome without it", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const done = await store.complete(item.id, "w1", result({ recipients: [deferred(true)] }), []);
+    expect7(done?.item.recipients[0]?.mayHaveReachedFallback).toBe(true);
+    expect7(done?.item.recipients[1]).not.toHaveProperty("mayHaveReachedFallback");
+    expect7((await store.get(item.id))?.recipients[0]?.mayHaveReachedFallback).toBe(true);
+    expect7((await store.list())[0]?.recipients[0]?.mayHaveReachedFallback).toBe(true);
+    await store.claim({ owner: "w1", now: T0 + 30 * MINUTE, ...lease });
+    const again = await store.complete(item.id, "w1", result({ recipients: [deferred()], attempts: 2 }), []);
+    expect7(again?.item.recipients[0]?.mayHaveReachedFallback).toBe(true);
+    expect7((await store.get(item.id))?.recipients[0]?.mayHaveReachedFallback).toBe(true);
+  });
+  test6("mayHaveReachedFallback: an unmarked recipient has no such key", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    await store.complete(item.id, "w1", result({ recipients: [deferred()] }), []);
+    for (const r of (await store.get(item.id))?.recipients ?? []) {
+      expect7(r).not.toHaveProperty("mayHaveReachedFallback");
+    }
+  });
+  test6("mayHaveReachedFallback: a value other than true is INVALID, and the item stays as it was", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    for (const bad of [false, "true", 1, null]) {
+      await rejects(store.complete(item.id, "w1", result({ recipients: [deferred(bad)] }), []), "INVALID");
+    }
+    const kept = await store.get(item.id);
+    expect7(kept?.recipients[0]?.status).toBe("pending");
+    expect7(kept?.lease?.owner).toBe("w1");
+  });
+}
+
+// src/conformance/outcomes.ts
+function describeOutcomes(factories) {
+  describe4("outcomes", () => {
+    recording(factories);
+    refusing(factories);
+    finality(factories);
+    completeDsns(factories);
+    doubt(factories);
+    fallbackDoubt(factories);
+  });
+}
+function recording({ create }) {
+  test7("complete records each outcome, the schedule, and lets go of the lease", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const reply = {
+      code: 451,
+      status: "4.3.0",
+      text: "try later",
+      host: "mx.example.com"
+    };
+    const done = await store.complete(item.id, "w1", result({
+      recipients: [{ address: "joe@example.com", status: "deferred", reply }]
+    }), []);
+    expect8(done?.item.recipients).toEqual([
+      {
+        address: "joe@example.com",
+        status: "deferred",
+        reply,
+        updatedAt: T0 + MINUTE
+      },
+      { address: "ann@example.org", status: "pending" }
+    ]);
+    const stored = await store.get(item.id);
+    expect8(stored).toEqual(done?.item);
+    expect8(stored).toMatchObject({
+      nextAttemptAt: T0 + 30 * MINUTE,
+      attempts: 1
+    });
+    expect8(stored?.lease).toBeUndefined();
+    expect8(await store.claim({ owner: "w2", now: T0 + 29 * MINUTE, ...lease })).toBeUndefined();
+    expect8(await store.claim({ owner: "w2", now: T0 + 30 * MINUTE, ...lease })).toBeDefined();
+  });
+  test7("an item whose every recipient is final is dropped with its message", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const done = await store.complete(item.id, "w1", result({
+      recipients: [
+        {
+          address: "joe@example.com",
+          status: "delivered",
+          reply: { code: 250, text: "ok" }
+        },
+        {
+          address: "ann@example.org",
+          status: "failed",
+          reply: { code: 550, text: "no" }
+        }
+      ],
+      delayNotified: true
+    }), []);
+    expect8(done?.item.recipients.map((r) => r.status)).toEqual([
+      "delivered",
+      "failed"
+    ]);
+    expect8(done?.item.delayNotified).toBe(true);
+    expect8(await store.get(item.id)).toBeUndefined();
+    expect8(await store.readMessage(item.id)).toBeUndefined();
+    expect8(await store.count()).toBe(0);
+  });
+}
+function refusing({ create }) {
+  test7("an outcome holding a NUL or a lone surrogate is refused, and the item stays as it was", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    const bad = [
+      { code: 451, text: `${"a".repeat(8)}\uD83D` },
+      { code: 451, text: "nul \x00 here" },
+      { code: 451, text: "ok", host: "mx\uDC00.example.com" },
+      { code: 451, status: "4.3.0\x00", text: "ok" }
+    ];
+    for (const reply of bad) {
+      await rejects(store.complete(item.id, "w1", result({
+        recipients: [
+          { address: "joe@example.com", status: "deferred", reply }
+        ]
+      }), []), "INVALID");
+    }
+    await rejects(store.claim({ owner: "w\uD800", now: T0, ...lease }), "INVALID");
+    const stored = await store.get(item.id);
+    expect8(stored?.attempts).toBe(0);
+    expect8(stored?.lease?.owner).toBe("w1");
+    const done = await store.complete(item.id, "w1", result({
+      recipients: [
+        {
+          address: "joe@example.com",
+          status: "deferred",
+          reply: { code: 451, text: "Try later \uD83D\uDE00" }
+        }
+      ]
+    }), []);
+    expect8(done?.item.recipients[0]?.reply?.text).toBe("Try later \uD83D\uDE00");
+    expect8((await store.get(item.id))?.recipients[0]?.reply?.text).toBe("Try later \uD83D\uDE00");
+  });
+}
+function finality({ create }) {
+  test7("a final state is never changed by a later outcome", async () => {
+    const store = await create();
+    const item = await store.add(entry());
+    await store.claim({ owner: "w1", now: T0, ...lease });
+    await store.complete(item.id, "w1", result({
+      recipients: [{ address: "joe@example.com", status: "delivered" }]
+    }), []);
+    await store.claim({ owner: "w1", now: T0 + 30 * MINUTE, ...lease });
+    const after = await store.complete(item.id, "w1", result({
+      recipients: [{ address: "joe@example.com", status: "failed" }],
+      attempts: 2
+    }), []);
+    expect8(after?.item.recipients[0]?.status).toBe("delivered");
+  });
+}
+
+// src/conformance/describe-queue-store.ts
+function describeQueueStore(name, harness) {
+  describe5(`${name}: the QueueStore contract`, () => {
+    const created = [];
+    const factories = {
+      share: harness.share,
+      create: async () => {
+        const store = await harness.create();
+        created.push(store);
+        return store;
+      }
+    };
+    afterEach(async () => {
+      const stores = created.splice(0);
+      const settled = await Promise.allSettled(stores.map(async (store) => harness.dispose?.(store)));
+      const failed = settled.filter((r) => r.status === "rejected");
+      if (failed.length === 1)
+        throw failed[0]?.reason;
+      if (failed.length > 1)
+        throw new AggregateError(failed.map((r) => r.reason), "several stores failed to dispose");
+    });
+    describeItems(factories);
+    describeClaims(factories);
+    describeOutcomes(factories);
+    describeConcurrency(factories);
+  });
+}
+export {
+  describeQueueStore
+};
+
+//# debugId=434F5188249F7D1F64756E2164756E21
+//# sourceMappingURL=index.js.map