@relaybus/core 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,65 +1,15 @@
 'use strict';
 
+var chunk3OHMEMZA_cjs = require('./chunk-3OHMEMZA.cjs');
 var crypto = require('crypto');
-var os = require('os');
 var async_hooks = require('async_hooks');
+var os = require('os');
 
 // src/clock.ts
 var systemClock = {
   now: () => /* @__PURE__ */ new Date()
 };
 
-// src/errors.ts
-var RelayBusError = class extends Error {
-  // Explicit names survive minification, unlike `new.target.name`.
-  name = "RelayBusError";
-};
-var ConfigurationError = class extends RelayBusError {
-  name = "ConfigurationError";
-};
-var TransactionRequiredError = class extends RelayBusError {
-  name = "TransactionRequiredError";
-};
-var NonRetryableError = class extends RelayBusError {
-  name = "NonRetryableError";
-};
-var EventValidationError = class extends NonRetryableError {
-  constructor(message, issues) {
-    super(message);
-    this.issues = issues;
-  }
-  issues;
-  name = "EventValidationError";
-};
-var InvalidEnvelopeError = class extends NonRetryableError {
-  name = "InvalidEnvelopeError";
-};
-var LeaseLostError = class extends RelayBusError {
-  name = "LeaseLostError";
-};
-var HandlerTimeoutError = class extends RelayBusError {
-  name = "HandlerTimeoutError";
-};
-var DispatcherStoppedError = class extends RelayBusError {
-  name = "DispatcherStoppedError";
-};
-function toErrorInfo(error) {
-  if (error instanceof Error) {
-    return { name: error.name, message: error.message, stack: error.stack };
-  }
-  return { name: "NonError", message: safeStringify(error) };
-}
-function safeStringify(value) {
-  if (typeof value === "string") {
-    return value;
-  }
-  try {
-    return JSON.stringify(value) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}
-
 // src/duration.ts
 var MILLISECONDS_PER_UNIT = {
   ms: 1,
@@ -72,7 +22,7 @@ var DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
 function toMilliseconds(value, name) {
   if (typeof value === "number") {
     if (!Number.isFinite(value) || value < 0) {
-      throw new ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         `${name} must be a non-negative finite number of milliseconds, received ${value}`
       );
     }
@@ -80,7 +30,7 @@ function toMilliseconds(value, name) {
   }
   const match = DURATION_PATTERN.exec(value);
   if (match === null) {
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `${name} must look like '500ms', '30s', '5m', '1h' or '7d', received '${value}'`
     );
   }
@@ -91,54 +41,278 @@ var MAX_TIMER_DELAY_MS = 2147483647;
 function toTimerMilliseconds(value, name) {
   const milliseconds = toMilliseconds(value, name);
   if (milliseconds === 0) {
-    throw new ConfigurationError(`${name} must be greater than zero`);
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`${name} must be greater than zero`);
   }
   if (milliseconds > MAX_TIMER_DELAY_MS) {
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `${name} must not exceed ${MAX_TIMER_DELAY_MS}ms (about 24.8 days), received ${milliseconds}ms`
     );
   }
   return milliseconds;
 }
 
-// src/event.ts
-var EVENT_TYPE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,254}$/;
-function assertEventType(type) {
-  if (!EVENT_TYPE_PATTERN.test(type)) {
-    throw new ConfigurationError(
-      `Event type '${type}' must be 1-255 characters of letters, digits, '.', '_', ':', '/' or '-', starting with a letter or digit`
+// src/catalog.ts
+var EVENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var descriptions = /* @__PURE__ */ new WeakMap();
+function defineCatalog(events, options = {}) {
+  const label = options.name === void 0 ? "Catalog" : `Catalog '${options.name}'`;
+  const names = Object.keys(events);
+  if (names.length === 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`${label} must contain at least one event`);
+  }
+  const owners = /* @__PURE__ */ new Map();
+  const entries = names.map((name) => {
+    const eventClass = events[name];
+    if (!EVENT_NAME_PATTERN.test(name)) {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
+        `${label} entry '${name}' must be a valid identifier made of letters, digits and underscores because it names the handler method on${name} and its handler id`
+      );
+    }
+    if (typeof eventClass !== "function" || typeof eventClass.type !== "string") {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
+        `${label} entry '${name}' must be an event class created with defineEvent`
+      );
+    }
+    chunk3OHMEMZA_cjs.assertEventType(eventClass.type);
+    const owner = owners.get(eventClass.type);
+    if (owner !== void 0) {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
+        `${label} entries '${owner}' and '${name}' share the event type '${eventClass.type}'`
+      );
+    }
+    owners.set(eventClass.type, name);
+    return Object.freeze({ name, eventClass, type: eventClass.type, handlerName: `on${name}` });
+  });
+  const catalog = Object.freeze({ ...events });
+  descriptions.set(catalog, Object.freeze({ name: options.name, entries: Object.freeze(entries) }));
+  return catalog;
+}
+function describeCatalog(catalog) {
+  const description = descriptions.get(catalog);
+  if (description === void 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError("Expected a catalog created with defineCatalog");
+  }
+  return description;
+}
+function catalogLabel(catalog) {
+  const { name } = describeCatalog(catalog);
+  return name === void 0 ? "the catalog" : `catalog '${name}'`;
+}
+function selectCatalogEntries(catalog, events) {
+  const { entries } = describeCatalog(catalog);
+  if (events === void 0) {
+    return entries;
+  }
+  const label = catalogLabel(catalog);
+  if (events.length === 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `The events selected from ${label} must name at least one event; omit events to select all of them`
     );
   }
+  const selected = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (!entries.some((entry) => entry.name === event)) {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
+        `${capitalize(label)} has no event named '${String(event)}'; its events are ${entries.map((entry) => entry.name).join(", ")}`
+      );
+    }
+    if (selected.has(event)) {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(`Event '${String(event)}' of ${label} is selected twice`);
+    }
+    selected.add(event);
+  }
+  return entries.filter((entry) => selected.has(entry.name));
+}
+function capitalize(text) {
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+}
+function requireCatalogEntry(catalog, event) {
+  const entry = describeCatalog(catalog).entries.find((candidate) => candidate.type === event.type);
+  if (entry === void 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `Event type '${String(event.type)}' is not part of ${catalogLabel(catalog)}`
+    );
+  }
+  return entry;
+}
+function resolveCatalogHandlers(catalog, {
+  handlers,
+  options
+}) {
+  const { name } = describeCatalog(catalog);
+  const { idPrefix, events, ...subscribeOptions } = options;
+  const entries = selectCatalogEntries(catalog, events);
+  const lookup = handlers;
+  const missing = entries.filter((entry) => typeof lookup[entry.handlerName] !== "function");
+  if (missing.length > 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `Handlers for catalog ${name === void 0 ? "events" : `'${name}'`} lack methods: ${missing.map((entry) => entry.handlerName).join(", ")}`
+    );
+  }
+  const prefix = idPrefix ?? name ?? classNameOf(handlers);
+  if (prefix === void 0) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      "Cannot derive handler ids: name the catalog, pass an idPrefix or use a class instance as handlers"
+    );
+  }
+  return entries.map((entry) => {
+    const method = lookup[entry.handlerName];
+    return {
+      eventClass: entry.eventClass,
+      handle: (envelope, context) => method.call(handlers, envelope, context),
+      options: { ...subscribeOptions, id: `${prefix}.${entry.handlerName}` }
+    };
+  });
 }
-function defineEvent(type, options) {
-  assertEventType(type);
-  const schema = options?.schema;
-  return class DefinedEvent {
-    constructor(payload) {
-      this.payload = payload;
+function classNameOf(handlers) {
+  const className = handlers.constructor.name;
+  return className === "Object" || className === "" ? void 0 : className;
+}
+function assertExactHandlers(catalog, { entries, handlers }) {
+  const expected = new Set(entries.map((entry) => entry.handlerName));
+  const present = Object.keys(handlers);
+  const missing = [...expected].filter((handlerName) => !present.includes(handlerName));
+  const extra = present.filter((key) => !expected.has(key));
+  const notFunctions = present.filter(
+    (key) => expected.has(key) && typeof handlers[key] !== "function"
+  );
+  if (missing.length + extra.length + notFunctions.length > 0) {
+    const problems = [
+      ...missing.map((key) => `missing ${key}`),
+      ...extra.map((key) => `unexpected ${key}`),
+      ...notFunctions.map((key) => `${key} is not a function`)
+    ];
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `Handlers do not match ${catalogLabel(catalog)}: ${problems.join(", ")}`
+    );
+  }
+}
+function defineHandlers(catalog, handlers, options = {}) {
+  assertExactHandlers(catalog, {
+    entries: selectCatalogEntries(catalog, options.events),
+    handlers
+  });
+  return handlers;
+}
+
+// src/catalog-publisher.ts
+var CatalogPublisher = class {
+  #catalog;
+  #target;
+  #entries;
+  /**
+   * Whether the view publishes the event named `eventName`. Its parameter
+   * makes a view of some events unassignable to a view of more events, which
+   * the bivariant method parameters alone would allow.
+   */
+  #publishes;
+  /**
+   * Throws {@link ConfigurationError} when `catalog` was not created with
+   * `defineCatalog` or `options.events` names no event, an unknown event or
+   * the same event twice.
+   */
+  constructor(catalog, target, options = {}) {
+    this.#entries = selectCatalogEntries(catalog, options.events);
+    const names = new Set(this.#entries.map((entry) => entry.name));
+    this.#publishes = (eventName) => names.has(eventName);
+    this.#catalog = catalog;
+    this.#target = target;
+  }
+  /** Same as `bus.publish`, limited to the events of the view. */
+  async publish(event, options) {
+    this.#assertPublishable(event);
+    return this.#target.publish(event, options);
+  }
+  /** Same as `bus.publishAll`, limited to the events of the view. Nothing is stored unless every event belongs to it. */
+  async publishAll(events, options) {
+    for (const event of events) {
+      this.#assertPublishable(event);
     }
-    payload;
-    static type = type;
-    static schema = schema;
-    type = type;
-  };
+    return this.#target.publishAll(events, options);
+  }
+  #assertPublishable(event) {
+    const { name } = requireCatalogEntry(this.#catalog, event);
+    if (!this.#publishes(name)) {
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
+        `Event type '${event.type}' is not one of the events this view of ${catalogLabel(
+          this.#catalog
+        )} publishes (${this.#entries.map((entry) => entry.name).join(", ")})`
+      );
+    }
+  }
+};
+
+// src/catalog-coverage.ts
+var declarations = /* @__PURE__ */ new WeakSet();
+function consume(catalog, options = {}) {
+  return declare(catalog, { role: "consume", options });
+}
+function produce(catalog, options = {}) {
+  return declare(catalog, { role: "produce", options });
+}
+function declare(catalog, { role, options }) {
+  const entries = selectCatalogEntries(catalog, options.events);
+  const declaration = Object.freeze({
+    catalog,
+    role,
+    events: Object.freeze(entries.map((entry) => entry.name)),
+    entries
+  });
+  declarations.add(declaration);
+  return declaration;
+}
+function toCatalogRequirement(value) {
+  if (declarations.has(value)) {
+    const declaration = value;
+    return {
+      catalogName: describeCatalog(declaration.catalog).name,
+      entries: declaration.entries,
+      need: declaration.role === "consume" ? "handler" : "route"
+    };
+  }
+  const { name, entries } = describeCatalog(value);
+  return { catalogName: name, entries, need: "handler-or-route" };
 }
-async function validatePayload(type, schema, payload) {
-  if (schema === void 0) {
-    return payload;
+function assertCatalogsCovered(requirements, registrationsOf) {
+  const problems = /* @__PURE__ */ new Set();
+  let onlyBareCatalogs = true;
+  for (const { catalogName, entries, need } of requirements) {
+    for (const entry of entries) {
+      const problem = describeGap(entry, { need, registrations: registrationsOf(entry.type) });
+      if (problem !== void 0) {
+        problems.add(`${catalogName === void 0 ? "" : `${catalogName}.`}${problem}`);
+        onlyBareCatalogs &&= need === "handler-or-route";
+      }
+    }
   }
-  const result = await schema["~standard"].validate(payload);
-  if (result.issues !== void 0) {
-    const issues = result.issues.map((issue) => ({
-      message: issue.message,
-      path: issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment)
-    }));
-    throw new EventValidationError(
-      `Payload of '${type}' failed validation: ${issues.map((issue) => issue.message).join("; ")}`,
-      issues
+  if (problems.size > 0) {
+    const heading = onlyBareCatalogs ? "Catalog events without a handler or route:" : "Catalog events this service does not cover:";
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `${heading}
+${[...problems].map((line) => `  - ${line}`).join("\n")}`
     );
   }
-  return result.value;
+}
+function describeGap(entry, {
+  need,
+  registrations: { handlers, routes }
+}) {
+  const subject = `${entry.name} (${entry.type})`;
+  if (need === "handler-or-route") {
+    return handlers + routes > 0 ? void 0 : `${subject}: expected handler method ${entry.handlerName}`;
+  }
+  if (need === "handler") {
+    if (handlers > 0) {
+      return void 0;
+    }
+    const routeNote = routes > 0 ? "; its route to a transport does not handle it here" : "";
+    return `${subject}: consumed here, needs handler method ${entry.handlerName}${routeNote}`;
+  }
+  if (routes > 0) {
+    return void 0;
+  }
+  const handlerNote = handlers > 0 ? "; a local handler does not deliver it to other services" : "";
+  return `${subject}: produced here, needs a route to a transport${handlerNote}`;
 }
 
 // src/event-store.ts
@@ -148,20 +322,26 @@ var DELIVERY_STATUSES = [
   "completed",
   "dead"
 ];
+var UUID_BYTES = 16;
+var TIMESTAMP_BYTES = 6;
+var BYTE_VALUES = 256;
+var LOW_NIBBLE = 15;
+var VERSION_7 = 112;
+var VARIANT_PAYLOAD = 63;
+var RFC_9562_VARIANT = 128;
 function createUuidV7(timestamp = Date.now()) {
-  const bytes = crypto.randomBytes(16);
+  const bytes = crypto.randomBytes(UUID_BYTES);
   let remaining = timestamp;
-  for (let index = 5; index >= 0; index -= 1) {
-    bytes[index] = remaining % 256;
-    remaining = Math.floor(remaining / 256);
+  for (let index = TIMESTAMP_BYTES - 1; index >= 0; index -= 1) {
+    bytes[index] = remaining % BYTE_VALUES;
+    remaining = Math.floor(remaining / BYTE_VALUES);
   }
-  bytes[6] = bytes[6] & 15 | 112;
-  bytes[8] = bytes[8] & 63 | 128;
-  const hex = bytes.toString("hex");
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  bytes[6] = bytes[6] & LOW_NIBBLE | VERSION_7;
+  bytes[8] = bytes[8] & VARIANT_PAYLOAD | RFC_9562_VARIANT;
+  return bytes.toString("hex").replace(/^(.{8})(.{4})(.{4})(.{4})(.{12})$/, "$1-$2-$3-$4-$5");
 }
 
-// src/in-memory-event-store.ts
+// src/in-memory-transaction.ts
 var InMemoryTransaction = class {
   #operations = [];
   #finishers = [];
@@ -171,7 +351,7 @@ var InMemoryTransaction = class {
   }
   enqueue(operation) {
     if (this.#state !== "open") {
-      throw new ConfigurationError(`Cannot write through a ${this.#state} in-memory transaction`);
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(`Cannot write through a ${this.#state} in-memory transaction`);
     }
     this.#operations.push(operation);
   }
@@ -196,20 +376,26 @@ var InMemoryTransaction = class {
     }
   }
 };
+
+// src/in-memory-event-store.ts
+var DEFAULT_LIST_LIMIT = 100;
 var InMemoryEventStore = class {
   #events = /* @__PURE__ */ new Map();
   #deliveries = /* @__PURE__ */ new Map();
   #keySequences = /* @__PURE__ */ new Map();
   /** Row-lock emulation: event ids and ordering keys written by open transactions. */
   #locks = /* @__PURE__ */ new Map();
+  #writes = /* @__PURE__ */ new WeakMap();
   #generateIdentifier;
+  #retainCompleted;
   constructor(options = {}) {
     if (process.env["NODE_ENV"] === "production" && options.allowInProduction !== true) {
-      throw new ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         "InMemoryEventStore loses every event on restart. Use a database store in production, or pass allowInProduction: true"
       );
     }
     this.#generateIdentifier = options.generateIdentifier ?? (() => createUuidV7());
+    this.#retainCompleted = options.retainCompleted ?? false;
   }
   async transaction(work) {
     const transaction = new InMemoryTransaction();
@@ -222,6 +408,7 @@ var InMemoryEventStore = class {
       throw error;
     }
   }
+  // eslint-disable-next-line relaybus/max-two-params -- EventStore port signature
   async append(transaction, entries, now) {
     await this.#lock(
       transaction,
@@ -230,13 +417,15 @@ var InMemoryEventStore = class {
         ...entry.event.key === null ? [] : [`key:${entry.event.key}`]
       ])
     );
-    const pendingEventIds = /* @__PURE__ */ new Set();
-    const pendingDeliveryKeys = /* @__PURE__ */ new Set();
+    const written = this.#written(transaction);
+    const pendingEventIds = written.eventIds;
+    const pendingDeliveryKeys = written.deliveryKeys;
     const appendedEventIds = [];
     const duplicateEventIds = [];
     let appendedDeliveryCount = 0;
     for (const entry of entries) {
       const eventId = entry.event.id;
+      const serialized = serializeEnvelope(entry.event);
       const isDuplicate = this.#events.has(eventId) || pendingEventIds.has(eventId);
       if (isDuplicate) {
         duplicateEventIds.push(eventId);
@@ -244,47 +433,63 @@ var InMemoryEventStore = class {
         appendedEventIds.push(eventId);
         pendingEventIds.add(eventId);
       }
-      const newDeliveries = entry.deliveries.filter((delivery) => {
-        const deliveryKey = `${eventId}\0${delivery.handler}`;
-        if (pendingDeliveryKeys.has(deliveryKey) || this.#hasDelivery(eventId, delivery.handler)) {
-          return false;
-        }
-        pendingDeliveryKeys.add(deliveryKey);
-        return true;
-      });
+      const newDeliveries = this.#newDeliveries(entry, pendingDeliveryKeys);
       appendedDeliveryCount += newDeliveries.length;
-      const serialized = serializeEnvelope(entry.event);
       transaction.enqueue(() => {
-        if (!isDuplicate) {
-          this.#events.set(eventId, {
-            envelope: serialized,
-            sequence: this.#nextSequence(serialized.key)
-          });
-        }
-        const stored = this.#events.get(eventId);
-        for (const delivery of newDeliveries) {
-          this.#deliveries.set(delivery.id, {
-            id: delivery.id,
-            eventId,
-            handler: delivery.handler,
-            key: stored.envelope.key,
-            sequence: stored.sequence,
-            status: "pending",
-            attempts: 0,
-            availableAt: delivery.availableAt,
-            leaseOwner: null,
-            leaseToken: null,
-            leaseExpiresAt: null,
-            lastError: null,
-            createdAt: now,
-            updatedAt: now,
-            completedAt: null
-          });
-        }
+        this.#applyAppend({ eventId, serialized, isDuplicate, newDeliveries, now });
       });
     }
     return { appendedEventIds, duplicateEventIds, appendedDeliveryCount };
   }
+  /**
+   * The deliveries of `entry` whose handler the event neither has nor gets earlier in the
+   * transaction; remembers them in `pendingDeliveryKeys`.
+   */
+  #newDeliveries(entry, pendingDeliveryKeys) {
+    const eventId = entry.event.id;
+    return entry.deliveries.filter((delivery) => {
+      const deliveryKey = `${eventId}\0${delivery.handler}`;
+      if (pendingDeliveryKeys.has(deliveryKey) || this.#events.get(eventId)?.handlers.has(delivery.handler) === true) {
+        return false;
+      }
+      pendingDeliveryKeys.add(deliveryKey);
+      return true;
+    });
+  }
+  /** Applies one entry of an append when its transaction commits. */
+  #applyAppend(input) {
+    const { eventId, serialized, isDuplicate, newDeliveries, now } = input;
+    if (!isDuplicate) {
+      this.#events.set(eventId, {
+        envelope: serialized,
+        sequence: this.#nextSequence(serialized.key),
+        createdAt: now,
+        handlers: /* @__PURE__ */ new Set(),
+        completedAt: null
+      });
+    }
+    const stored = this.#events.get(eventId);
+    for (const delivery of newDeliveries) {
+      stored.handlers.add(delivery.handler);
+      this.#deliveries.set(delivery.id, {
+        id: delivery.id,
+        eventId,
+        handler: delivery.handler,
+        key: stored.envelope.key,
+        sequence: stored.sequence,
+        status: "pending",
+        attempts: 0,
+        availableAt: delivery.availableAt,
+        leaseOwner: null,
+        leaseToken: null,
+        leaseExpiresAt: null,
+        lastError: null,
+        createdAt: now,
+        updatedAt: now,
+        completedAt: null
+      });
+    }
+  }
   async claim(request) {
     const handlers = new Set(request.handlers);
     const due = [...this.#deliveries.values()].filter((delivery) => handlers.has(delivery.handler) && isDue(delivery, request.now)).sort(compareDue);
@@ -313,21 +518,17 @@ var InMemoryEventStore = class {
     }
     return claimed;
   }
+  // eslint-disable-next-line relaybus/max-two-params -- EventStore port signature
   async extendLease(lease, leaseExpiresAt, now) {
     return this.#updateLeased(lease, (delivery) => {
       delivery.leaseExpiresAt = leaseExpiresAt;
       delivery.updatedAt = now;
     });
   }
+  // eslint-disable-next-line relaybus/max-two-params -- EventStore port signature
   async complete(lease, now, transaction) {
-    const finish = (delivery) => {
-      delivery.status = "completed";
-      delivery.completedAt = now;
-      delivery.updatedAt = now;
-      clearLease(delivery);
-    };
     if (transaction === void 0) {
-      return this.#updateLeased(lease, finish);
+      return this.#updateLeased(lease, (delivery) => this.#finish(delivery, now));
     }
     if (this.#findLeased(lease) === void 0) {
       return false;
@@ -335,11 +536,15 @@ var InMemoryEventStore = class {
     transaction.enqueue(() => {
       const delivery = this.#findLeased(lease);
       if (delivery !== void 0) {
-        finish(delivery);
+        this.#finish(delivery, now);
       }
     });
     return true;
   }
+  async completeMany(leases, now) {
+    return Promise.all(leases.map((lease) => this.complete(lease, now)));
+  }
+  // eslint-disable-next-line relaybus/max-two-params -- EventStore port signature
   async reschedule(lease, availableAt, error, now) {
     return this.#updateLeased(lease, (delivery) => {
       delivery.status = "pending";
@@ -358,6 +563,7 @@ var InMemoryEventStore = class {
       clearLease(delivery);
     });
   }
+  // eslint-disable-next-line relaybus/max-two-params -- EventStore port signature
   async bury(lease, error, now) {
     return this.#updateLeased(lease, (delivery) => {
       delivery.status = "dead";
@@ -367,8 +573,10 @@ var InMemoryEventStore = class {
     });
   }
   async listDeliveries(query) {
-    const limit = query.limit ?? 100;
-    return [...this.#deliveries.values()].filter((delivery) => matchesQuery(delivery, this.#events.get(delivery.eventId), query)).sort(
+    const limit = query.limit ?? DEFAULT_LIST_LIMIT;
+    return [...this.#deliveries.values()].filter(
+      (delivery) => matchesQuery(delivery, { event: this.#events.get(delivery.eventId), query })
+    ).sort(
       (left, right) => left.createdAt.getTime() - right.createdAt.getTime() || compareIds(left.id, right.id)
     ).slice(0, limit).map((delivery) => ({
       id: delivery.id,
@@ -410,17 +618,26 @@ var InMemoryEventStore = class {
         deletedDeliveries += 1;
       }
     }
+    return { deletedDeliveries, deletedEvents: this.#purgeEvents(request, touchedEventIds) };
+  }
+  /** Deletes the events no delivery references whose retention ran out; returns how many. */
+  #purgeEvents(request, touchedEventIds) {
     const referencedEventIds = new Set(
       [...this.#deliveries.values()].map((delivery) => delivery.eventId)
     );
+    const { orphanCutoff, completedCutoff } = eventCutoffs(request);
     let deletedEvents = 0;
-    for (const eventId of touchedEventIds) {
-      if (!referencedEventIds.has(eventId)) {
+    for (const [eventId, event] of [...this.#events]) {
+      if (referencedEventIds.has(eventId) || this.#locks.has(`event:${eventId}`)) {
+        continue;
+      }
+      const expired = event.completedAt === null ? touchedEventIds.has(eventId) || event.createdAt.getTime() < orphanCutoff : event.completedAt.getTime() < completedCutoff;
+      if (expired) {
         this.#events.delete(eventId);
         deletedEvents += 1;
       }
     }
-    return { deletedDeliveries, deletedEvents };
+    return deletedEvents;
   }
   async statistics(now) {
     const counts = {
@@ -446,6 +663,15 @@ var InMemoryEventStore = class {
    * until `transaction` finishes, the way a database holds row locks. Sorted
    * acquisition keeps two transactions from waiting on each other.
    */
+  /** The events and deliveries the transaction appended so far, which are not applied before it commits. */
+  #written(transaction) {
+    let written = this.#writes.get(transaction);
+    if (written === void 0) {
+      written = { eventIds: /* @__PURE__ */ new Set(), deliveryKeys: /* @__PURE__ */ new Set() };
+      this.#writes.set(transaction, written);
+    }
+    return written;
+  }
   async #lock(transaction, names) {
     for (const name of [...new Set(names)].sort()) {
       let held = this.#locks.get(name);
@@ -467,14 +693,6 @@ var InMemoryEventStore = class {
       });
     }
   }
-  #hasDelivery(eventId, handler) {
-    for (const delivery of this.#deliveries.values()) {
-      if (delivery.eventId === eventId && delivery.handler === handler) {
-        return true;
-      }
-    }
-    return false;
-  }
   #nextSequence(key) {
     if (key === null) {
       return null;
@@ -494,17 +712,27 @@ var InMemoryEventStore = class {
       return false;
     }
     for (const other of this.#deliveries.values()) {
-      if (other === delivery || other.handler !== delivery.handler || other.key !== delivery.key) {
-        continue;
-      }
-      const unfinishedPredecessor = other.sequence < delivery.sequence && (other.status === "pending" || other.status === "processing");
-      const runningUnderLiveLease = other.status === "processing" && other.leaseExpiresAt > now;
-      if (unfinishedPredecessor || runningUnderLiveLease) {
+      if (blocksKey(other, { delivery, now })) {
         return true;
       }
     }
     return false;
   }
+  /** Deletes a completed delivery, or marks it completed when a history is kept. */
+  #finish(delivery, now) {
+    const event = this.#events.get(delivery.eventId);
+    if (event.completedAt === null || event.completedAt < now) {
+      event.completedAt = now;
+    }
+    if (!this.#retainCompleted) {
+      this.#deliveries.delete(delivery.id);
+      return;
+    }
+    delivery.status = "completed";
+    delivery.completedAt = now;
+    delivery.updatedAt = now;
+    clearLease(delivery);
+  }
   #findLeased(lease) {
     const delivery = this.#deliveries.get(lease.deliveryId);
     if (delivery?.status === "processing" && delivery.leaseToken === lease.leaseToken) {
@@ -526,6 +754,21 @@ var InMemoryEventStore = class {
     return { ...copy, occurredAt: new Date(copy.occurredAt) };
   }
 };
+function blocksKey(other, { delivery, now }) {
+  if (other === delivery || other.handler !== delivery.handler || other.key !== delivery.key) {
+    return false;
+  }
+  const unfinishedPredecessor = other.sequence < delivery.sequence && (other.status === "pending" || other.status === "processing");
+  const runningUnderLiveLease = other.status === "processing" && other.leaseExpiresAt > now;
+  return unfinishedPredecessor || runningUnderLiveLease;
+}
+function eventCutoffs(request) {
+  const cutoffs = [request.completedBefore, request.deadBefore].filter((cutoff) => cutoff !== void 0).map((cutoff) => cutoff.getTime());
+  return {
+    orphanCutoff: cutoffs.length === 0 ? Number.NEGATIVE_INFINITY : Math.min(...cutoffs),
+    completedCutoff: request.completedBefore?.getTime() ?? Number.NEGATIVE_INFINITY
+  };
+}
 function serializeEnvelope(envelope) {
   return JSON.parse(JSON.stringify(envelope));
 }
@@ -550,7 +793,7 @@ function clearLease(delivery) {
   delivery.leaseToken = null;
   delivery.leaseExpiresAt = null;
 }
-function matchesQuery(delivery, event, query) {
+function matchesQuery(delivery, { event, query }) {
   return (query.status === void 0 || delivery.status === query.status) && (query.handler === void 0 || delivery.handler === query.handler) && (query.eventType === void 0 || event.envelope.type === query.eventType) && (query.eventId === void 0 || delivery.eventId === query.eventId);
 }
 function isPurgeable(delivery, request) {
@@ -562,210 +805,979 @@ function isPurgeable(delivery, request) {
   }
   return false;
 }
-var storage = new async_hooks.AsyncLocalStorage();
-function runInScope(scope, work) {
-  return storage.run({ ...storage.getStore(), ...scope }, work);
-}
-function runInIsolatedScope(scope, work) {
-  return storage.run(scope, work);
-}
-function getCurrentScope() {
-  return storage.getStore();
+
+// src/tracing.ts
+var TRACEPARENT_HEADER = "traceparent";
+var TRACESTATE_HEADER = "tracestate";
+var TRACEPARENT_FIELDS = "(?!0{32})[\\da-f]{32}-(?!0{16})[\\da-f]{16}-[\\da-f]{2}";
+var TRACEPARENT = new RegExp(
+  `^(?:00-${TRACEPARENT_FIELDS}|(?!00|ff)[\\da-f]{2}-${TRACEPARENT_FIELDS}(?:-.*)?)$`
+);
+function traceContextOf(headers) {
+  const traceparent = headers[TRACEPARENT_HEADER];
+  if (traceparent === void 0 || !TRACEPARENT.test(traceparent)) {
+    return void 0;
+  }
+  const tracestate = headers[TRACESTATE_HEADER];
+  return tracestate === void 0 ? { traceparent } : { traceparent, tracestate };
 }
 
-// src/retry-policy.ts
-var DEFAULT_RETRY_POLICY = {
-  attempts: 10,
-  initialDelayMs: 1e3,
-  factor: 2,
-  maxDelayMs: 6e5,
-  jitter: "full",
-  retryIf: void 0
-};
-var DEFAULT_ROUTE_RETRY_POLICY = {
-  attempts: Number.POSITIVE_INFINITY,
-  initialDelayMs: 1e3,
-  factor: 2,
-  maxDelayMs: 3e5,
-  jitter: "full",
-  retryIf: void 0
-};
-var JITTER_STRATEGIES = ["full", "equal", "none"];
-function createRetryPolicy(options, base = DEFAULT_RETRY_POLICY) {
-  const initialDelayMs = options?.initialDelay === void 0 ? base.initialDelayMs : toMilliseconds(options.initialDelay, "retry.initialDelay");
-  const policy = {
-    attempts: options?.attempts ?? base.attempts,
-    initialDelayMs,
-    factor: options?.factor ?? base.factor,
-    maxDelayMs: options?.maxDelay === void 0 ? (
-      // Raising only the initial delay must not trip the inherited cap.
-      Math.max(base.maxDelayMs, initialDelayMs)
-    ) : toMilliseconds(options.maxDelay, "retry.maxDelay"),
-    jitter: options?.jitter ?? base.jitter,
-    retryIf: options?.retryIf ?? base.retryIf
-  };
-  if (policy.attempts !== Number.POSITIVE_INFINITY && (!Number.isInteger(policy.attempts) || policy.attempts < 1)) {
-    throw new ConfigurationError(
-      `retry.attempts must be a positive integer or Infinity, received ${policy.attempts}`
+// src/bus-observation.ts
+function withTraceHeaders(options, headers) {
+  return Object.keys(headers).length === 0 ? options : { ...options, headers: { ...headers, ...options.headers } };
+}
+var BusObservation = class _BusObservation {
+  #notifier;
+  #tracer;
+  #clock;
+  #publishes;
+  #receives;
+  #sends;
+  constructor(input) {
+    this.#notifier = input.notifier;
+    this.#tracer = input.tracer;
+    this.#clock = input.clock;
+    this.#publishes = input.notifier.wants("onPublishFinished");
+    this.#receives = input.notifier.wants("onReceiveFinished");
+    this.#sends = input.notifier.wants("onTransportSent");
+  }
+  /** An observation, or undefined when no observer hook and no tracer would see anything. */
+  static create(input) {
+    const observed = input.tracer !== void 0 || ["onPublishFinished", "onReceiveFinished", "onTransportSent", "onBacklog"].some(
+      (method) => input.notifier.wants(method)
     );
+    return observed ? new _BusObservation(input) : void 0;
+  }
+  /** Runs a publish call inside the tracer's publish span, reporting its duration and outcome. */
+  async publish(input, run) {
+    const startedAt = this.#publishes ? this.#now() : 0;
+    const tracer = this.#tracer;
+    const traced = tracer?.publish === void 0 ? run({}) : tracer.publish(input, run);
+    if (!this.#publishes) {
+      return traced;
+    }
+    const report = (outcome, error) => {
+      this.#notifier.notify("onPublishFinished", {
+        eventTypes: input.eventTypes,
+        durationMs: this.#now() - startedAt,
+        outcome,
+        ...error === void 0 ? {} : { error: chunk3OHMEMZA_cjs.toErrorInfo(error) }
+      });
+    };
+    try {
+      const result = await traced;
+      report("success");
+      return result;
+    } catch (error) {
+      report("error", error);
+      throw error;
+    }
   }
-  if (!Number.isFinite(policy.factor) || policy.factor < 1) {
-    throw new ConfigurationError(`retry.factor must be at least 1, received ${policy.factor}`);
+  /** Runs `receive` for one event, reporting where it came from and what became of it. */
+  async receive(input, run) {
+    if (!this.#receives) {
+      return run();
+    }
+    const startedAt = this.#now();
+    try {
+      const outcome = await run();
+      this.#reportReceive(input, { outcome, startedAt, failure: void 0 });
+      return outcome;
+    } catch (error) {
+      const outcome = error instanceof chunk3OHMEMZA_cjs.InvalidEnvelopeError ? "invalid" : "error";
+      this.#reportReceive(input, { outcome, startedAt, failure: error });
+      throw error;
+    }
   }
-  if (policy.maxDelayMs < policy.initialDelayMs) {
-    throw new ConfigurationError("retry.maxDelay must not be smaller than retry.initialDelay");
+  #reportReceive({ envelope, origin }, report) {
+    const { headers } = envelope;
+    this.#notifier.notify("onReceiveFinished", {
+      transport: origin?.transport.name,
+      system: origin === void 0 ? void 0 : systemOf(origin.transport),
+      destination: origin?.destination,
+      eventType: textOrUndefined(envelope.type),
+      source: textOrUndefined(envelope.source),
+      traceContext: isObject(headers) ? traceContextOf(headers) : void 0,
+      outcome: report.outcome,
+      durationMs: this.#now() - report.startedAt,
+      ...report.failure === void 0 ? {} : { error: chunk3OHMEMZA_cjs.toErrorInfo(report.failure) }
+    });
   }
-  if (!JITTER_STRATEGIES.includes(policy.jitter)) {
-    throw new ConfigurationError(
-      `retry.jitter must be one of ${JITTER_STRATEGIES.join(", ")}, received '${String(policy.jitter)}'`
-    );
+  /** The handler of a route: sends inside the tracer's send span and reports each send. */
+  sender(transport, destination) {
+    if (this.#tracer?.send === void 0 && !this.#sends) {
+      return (envelope) => transport.publish(envelope, destination);
+    }
+    return (envelope) => this.#send({ envelope, transport, destination });
   }
-  return policy;
-}
-function computeRetryDelay(policy, failedAttempts, random = Math.random) {
-  const exponential = policy.initialDelayMs * policy.factor ** (failedAttempts - 1);
-  const capped = Math.min(policy.maxDelayMs, exponential);
-  switch (policy.jitter) {
-    case "full":
-      return Math.round(random() * capped);
-    case "equal":
-      return Math.round(capped / 2 + random() * capped / 2);
-    case "none":
-      return Math.round(capped);
+  async #send({ envelope, transport, destination }) {
+    const startedAt = this.#sends ? this.#now() : 0;
+    const system = systemOf(transport);
+    const run = (headers) => transport.publish(
+      Object.keys(headers).length === 0 ? envelope : { ...envelope, headers: { ...envelope.headers, ...headers } },
+      destination
+    );
+    const tracer = this.#tracer;
+    const sent = tracer?.send === void 0 ? run({}) : tracer.send({ envelope, transport: transport.name, system, destination }, run);
+    if (!this.#sends) {
+      return sent;
+    }
+    const report = (outcome, error) => {
+      this.#notifier.notify("onTransportSent", {
+        envelope,
+        transport: transport.name,
+        system,
+        destination,
+        durationMs: this.#now() - startedAt,
+        outcome,
+        ...error === void 0 ? {} : { error: chunk3OHMEMZA_cjs.toErrorInfo(error) }
+      });
+    };
+    try {
+      await sent;
+      report("success");
+    } catch (error) {
+      report("error", error);
+      throw error;
+    }
   }
-}
-function isRetryableError(policy, error) {
-  if (error instanceof NonRetryableError) {
-    return false;
+  /**
+   * Reads the backlog every `intervalMs` and reports it, when an observer wants it. A reading that
+   * is still running when the next one is due is not overlapped. Returns the cancel of the timer.
+   */
+  startBacklog({ intervalMs, statistics }) {
+    if (!this.#notifier.wants("onBacklog")) {
+      return void 0;
+    }
+    let reading = false;
+    return chunk3OHMEMZA_cjs.schedule(this.#clock, {
+      run: () => {
+        if (reading) {
+          return;
+        }
+        reading = true;
+        statistics().then((result) => this.#reportBacklog(result)).catch((error) => this.#notifier.failure("backlog", error)).finally(() => {
+          reading = false;
+        });
+      },
+      delayMs: intervalMs,
+      repeat: true,
+      unref: true
+    });
   }
-  if (policy.retryIf === void 0) {
-    return true;
+  #reportBacklog(statistics) {
+    const oldestDueAt = statistics.oldestDueAt;
+    this.#notifier.notify("onBacklog", {
+      pending: statistics.pending,
+      oldestPendingAgeMs: oldestDueAt === null ? 0 : Math.max(0, this.#now() - oldestDueAt.getTime()),
+      statistics
+    });
   }
-  try {
-    return policy.retryIf(error);
-  } catch {
-    return true;
+  #now() {
+    return this.#clock.now().getTime();
   }
+};
+function systemOf(transport) {
+  return transport.system ?? transport.name;
+}
+function textOrUndefined(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
 }
 
-// src/dispatcher.ts
-var COMPLETION_RETRY_DELAYS_MS = [50, 250, 1e3];
-var defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-var Dispatcher = class {
-  #dependencies;
-  #sleep;
-  #inFlight = /* @__PURE__ */ new Set();
-  #running = false;
-  #loop;
-  #wakeUp;
-  #wakeRequested = false;
-  constructor(dependencies) {
-    this.#dependencies = dependencies;
-    this.#sleep = dependencies.sleep ?? defaultSleep;
-  }
-  get isRunning() {
-    return this.#running;
+// src/dispatch-observation.ts
+var DispatchObservation = class _DispatchObservation {
+  #notifier;
+  #tracer;
+  #clock;
+  #claims;
+  #runs;
+  constructor(input) {
+    this.#notifier = input.notifier;
+    this.#tracer = input.tracer;
+    this.#clock = input.clock;
+    this.#claims = input.notifier.wants("onClaimFinished");
+    this.#runs = input.notifier.wants("onHandlerStarted") || input.notifier.wants("onHandlerFinished");
+  }
+  /** An observation, or undefined when no observer hook and no tracer would see anything. */
+  static create(input) {
+    const observation = new _DispatchObservation(input);
+    return observation.#claims || observation.#runs || input.tracer?.process !== void 0 ? observation : void 0;
+  }
+  /** Claims through `store`, reporting the query's size, lanes and duration. */
+  async claim(store, request) {
+    if (!this.#claims) {
+      return store.claim(request);
+    }
+    const startedAt = this.#clock.now().getTime();
+    const report = { handlers: request.handlers, requested: request.limit };
+    try {
+      const claimed = await store.claim(request);
+      this.#notifier.notify("onClaimFinished", {
+        ...report,
+        claimed: claimed.length,
+        lanes: new Set(claimed.map((delivery) => delivery.leaseToken)).size,
+        durationMs: this.#clock.now().getTime() - startedAt,
+        outcome: "success"
+      });
+      return claimed;
+    } catch (error) {
+      this.#notifier.notify("onClaimFinished", {
+        ...report,
+        claimed: 0,
+        lanes: 0,
+        durationMs: this.#clock.now().getTime() - startedAt,
+        outcome: "error",
+        error: chunk3OHMEMZA_cjs.toErrorInfo(error)
+      });
+      throw error;
+    }
   }
-  get inFlightCount() {
-    return this.#inFlight.size;
+  /** Runs a local handler inside the tracer's process span; routes are traced as sends instead. */
+  process(run, handle) {
+    const tracer = this.#tracer;
+    if (tracer?.process === void 0 || run.registration.forwardsToTransport) {
+      return handle();
+    }
+    return tracer.process({ delivery: run.delivery }, async () => handle());
   }
-  start() {
+  /** Reports the start of a handler run now and its end when `settled` settles, passing it through. */
+  async observe(run, settled) {
+    if (!this.#runs) {
+      await settled;
+      return;
+    }
+    const { delivery } = run;
+    const kind = run.registration.forwardsToTransport ? "route" : "handler";
+    const startedAt = this.#clock.now().getTime();
+    this.#notifier.notify("onHandlerStarted", {
+      delivery,
+      kind,
+      endToEndLatencyMs: startedAt - delivery.event.occurredAt.getTime()
+    });
+    try {
+      await settled;
+    } catch (error) {
+      const durationMs2 = this.#clock.now().getTime() - startedAt;
+      const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
+      this.#notifier.notify("onHandlerFinished", {
+        delivery,
+        kind,
+        durationMs: durationMs2,
+        outcome: "error",
+        error: errorInfo
+      });
+      throw error;
+    }
+    const durationMs = this.#clock.now().getTime() - startedAt;
+    this.#notifier.notify("onHandlerFinished", { delivery, kind, durationMs, outcome: "success" });
+  }
+};
+
+// src/completion-batcher.ts
+var CompletionBatcher = class {
+  #store;
+  #clock;
+  #settings;
+  #runningCount;
+  #pending = [];
+  #timer;
+  #closing = false;
+  /**
+   * @param runningCount Number of deliveries the dispatcher is running right
+   * now, including the ones waiting in this batcher.
+   */
+  constructor(store, clock, settings, runningCount) {
+    this.#store = store;
+    this.#clock = clock;
+    this.#settings = settings;
+    this.#runningCount = runningCount;
+  }
+  /**
+   * Queues a completion. Resolves with whether the lease was still held;
+   * rejects with the store error when the batch could not be written.
+   */
+  submit(lease) {
+    return new Promise((resolve, reject) => {
+      this.#pending.push({ lease, resolve, reject });
+      if (this.#closing || this.#pending.length >= this.#settings.maxBatchSize || this.#pending.length >= this.#runningCount()) {
+        this.#flush();
+      } else {
+        this.#timer ??= chunk3OHMEMZA_cjs.schedule(this.#clock, {
+          run: () => this.#flush(),
+          delayMs: this.#settings.windowMs
+        });
+      }
+    });
+  }
+  /**
+   * Shutdown has begun (or ended): while closing, nothing waits for company any more, so the completions
+   * already queued are written now and later ones at once.
+   */
+  setClosing(closing) {
+    this.#closing = closing;
+    if (closing && this.#pending.length > 0) {
+      this.#flush();
+    }
+  }
+  #flush() {
+    this.#timer?.();
+    this.#timer = void 0;
+    const batch = this.#pending;
+    this.#pending = [];
+    Promise.resolve().then(
+      () => this.#store.completeMany(
+        batch.map((entry) => entry.lease),
+        this.#clock.now()
+      )
+    ).then(
+      (outcomes) => batch.forEach((entry, index) => entry.resolve(outcomes[index])),
+      (error) => batch.forEach((entry) => entry.reject(error))
+    );
+  }
+};
+
+// src/delivery-timers.ts
+var DeliveryTimers = class {
+  #clock;
+  /** Cancel of every timer still waiting, with what its cancellation must also do. */
+  #waiting = /* @__PURE__ */ new Map();
+  constructor(clock) {
+    this.#clock = clock;
+  }
+  /** Runs `task.run` after `task.delayMs`; returns what cancels it. */
+  start(task) {
+    return this.#start(task, () => void 0);
+  }
+  /** Resolves after `milliseconds`, or at once when {@link DeliveryTimers.cancelAll} runs. */
+  sleep(milliseconds) {
+    return new Promise((resolve) => {
+      this.#start({ run: resolve, delayMs: milliseconds }, resolve);
+    });
+  }
+  cancelAll() {
+    for (const [cancel, onCancel] of [...this.#waiting]) {
+      cancel();
+      onCancel();
+    }
+  }
+  #start(task, onCancel) {
+    const cancel = () => {
+      cancelTimer();
+      this.#waiting.delete(cancel);
+    };
+    const cancelTimer = chunk3OHMEMZA_cjs.schedule(this.#clock, {
+      run: () => {
+        this.#waiting.delete(cancel);
+        task.run();
+      },
+      delayMs: task.delayMs
+    });
+    this.#waiting.set(cancel, onCancel);
+    return cancel;
+  }
+};
+
+// src/dispatcher-support.ts
+function pendingKey(delivery) {
+  return `${delivery.deliveryId}\0${delivery.leaseToken}`;
+}
+function rejectOnAbort(signal) {
+  return new Promise((_, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+var storage = new async_hooks.AsyncLocalStorage();
+function runInScope(scope, work) {
+  return storage.run({ ...storage.getStore(), ...scope }, work);
+}
+function runInIsolatedScope(scope, work) {
+  return storage.run(scope, work);
+}
+function getCurrentScope() {
+  return storage.getStore();
+}
+
+// src/shutdown-deadline.ts
+var DRAIN_SHARE = 0.8;
+var ShutdownDeadline = class {
+  #controller = new AbortController();
+  #drained;
+  #expired;
+  #cancelTimers;
+  constructor(clock, timeoutMs) {
+    let drain;
+    this.#drained = new Promise((resolve) => {
+      drain = () => resolve("timeout");
+    });
+    const signal = this.#controller.signal;
+    this.#expired = new Promise((resolve) => {
+      signal.addEventListener("abort", () => resolve("timeout"), { once: true });
+    });
+    this.#cancelTimers = [
+      chunk3OHMEMZA_cjs.schedule(clock, { run: drain, delayMs: Math.floor(timeoutMs * DRAIN_SHARE) }),
+      chunk3OHMEMZA_cjs.schedule(clock, { run: () => this.#controller.abort(), delayMs: timeoutMs })
+    ];
+  }
+  /** Aborted when the deadline passes. */
+  get signal() {
+    return this.#controller.signal;
+  }
+  get passed() {
+    return this.#controller.signal.aborted;
+  }
+  /** Waits for `work` until the deadline. Rejects when `work` rejects before it. */
+  race(work) {
+    return Promise.race([work.then(() => "done"), this.#expired]);
+  }
+  /** Waits for running handlers until the drain point, when they are aborted. */
+  raceDrain(work) {
+    return Promise.race([work.then(() => "done"), this.#drained]);
+  }
+  /** Cancels the timers once the shutdown is over. */
+  dispose() {
+    for (const cancel of this.#cancelTimers) {
+      cancel();
+    }
+  }
+};
+async function withinDeadline({ clock, timeoutMs }, work) {
+  const startedAt = clock.now().getTime();
+  const deadline = new ShutdownDeadline(clock, timeoutMs);
+  try {
+    const abandonedDeliveries = await work(deadline);
+    return {
+      graceful: !deadline.passed,
+      abandonedDeliveries,
+      durationMs: clock.now().getTime() - startedAt
+    };
+  } finally {
+    deadline.dispose();
+  }
+}
+
+// src/lease-heartbeat.ts
+var RENEWALS_PER_LEASE = 3;
+function startLeaseHeartbeat({ store, clock, notifier, settings }, { delivery, controller }) {
+  let confirmedExpiry = delivery.leaseExpiresAt.getTime();
+  let renewing = false;
+  const abortLeaseLost = (storeConfirmed = false) => {
+    controller.abort(
+      new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, { storeConfirmed })
+    );
+  };
+  return chunk3OHMEMZA_cjs.schedule(clock, {
+    run: () => {
+      const now = clock.now();
+      if (now.getTime() >= confirmedExpiry) {
+        abortLeaseLost();
+        return;
+      }
+      if (renewing) {
+        return;
+      }
+      renewing = true;
+      const expiry = now.getTime() + settings.leaseDurationMs;
+      store.extendLease(delivery, new Date(expiry), now).then((extended) => {
+        if (extended) {
+          confirmedExpiry = expiry;
+        } else {
+          abortLeaseLost(true);
+        }
+      }).catch((error) => notifier.failure("extend-lease", error)).finally(() => {
+        renewing = false;
+      });
+    },
+    delayMs: Math.max(1, Math.floor(settings.leaseDurationMs / RENEWALS_PER_LEASE)),
+    repeat: true,
+    unref: true
+  });
+}
+
+// src/retry-policy.ts
+var DEFAULT_RETRY_POLICY = {
+  attempts: 10,
+  initialDelayMs: 1e3,
+  factor: 2,
+  maxDelayMs: 6e5,
+  jitter: "full",
+  retryIf: void 0
+};
+var DEFAULT_ROUTE_RETRY_POLICY = {
+  attempts: Number.POSITIVE_INFINITY,
+  initialDelayMs: 1e3,
+  factor: 2,
+  maxDelayMs: 3e5,
+  jitter: "full",
+  retryIf: void 0
+};
+var JITTER_STRATEGIES = ["full", "equal", "none"];
+function createRetryPolicy(options, base = DEFAULT_RETRY_POLICY) {
+  const policy = mergeRetryPolicy(options, base);
+  assertValidRetryPolicy(policy);
+  return policy;
+}
+function mergeRetryPolicy(options, base) {
+  const overrides = options ?? {};
+  const initialDelayMs = overrides.initialDelay === void 0 ? base.initialDelayMs : toMilliseconds(overrides.initialDelay, "retry.initialDelay");
+  return {
+    attempts: overrides.attempts ?? base.attempts,
+    initialDelayMs,
+    factor: overrides.factor ?? base.factor,
+    maxDelayMs: overrides.maxDelay === void 0 ? (
+      // Raising only the initial delay must not trip the inherited cap.
+      Math.max(base.maxDelayMs, initialDelayMs)
+    ) : toMilliseconds(overrides.maxDelay, "retry.maxDelay"),
+    jitter: overrides.jitter ?? base.jitter,
+    retryIf: overrides.retryIf ?? base.retryIf
+  };
+}
+function assertValidRetryPolicy(policy) {
+  if (policy.attempts !== Number.POSITIVE_INFINITY && (!Number.isInteger(policy.attempts) || policy.attempts < 1)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `retry.attempts must be a positive integer or Infinity, received ${policy.attempts}`
+    );
+  }
+  if (!Number.isFinite(policy.factor) || policy.factor < 1) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`retry.factor must be at least 1, received ${policy.factor}`);
+  }
+  if (policy.maxDelayMs < policy.initialDelayMs) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError("retry.maxDelay must not be smaller than retry.initialDelay");
+  }
+  if (!JITTER_STRATEGIES.includes(policy.jitter)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `retry.jitter must be one of ${JITTER_STRATEGIES.join(", ")}, received '${String(policy.jitter)}'`
+    );
+  }
+}
+function computeRetryDelay(policy, failedAttempts, random = Math.random) {
+  const exponential = policy.initialDelayMs * policy.factor ** (failedAttempts - 1);
+  const capped = Math.min(policy.maxDelayMs, exponential);
+  switch (policy.jitter) {
+    case "full":
+      return Math.round(random() * capped);
+    case "equal":
+      return Math.round(capped / 2 + random() * capped / 2);
+    case "none":
+      return Math.round(capped);
+  }
+}
+function isRetryableError(policy, error) {
+  if (error instanceof chunk3OHMEMZA_cjs.NonRetryableError) {
+    return false;
+  }
+  if (policy.retryIf === void 0) {
+    return true;
+  }
+  try {
+    return policy.retryIf(error);
+  } catch {
+    return true;
+  }
+}
+
+// src/dispatcher.ts
+var FIRST_COMPLETION_RETRY_MS = 50;
+var SECOND_COMPLETION_RETRY_MS = 250;
+var LAST_COMPLETION_RETRY_MS = 1e3;
+var COMPLETION_RETRY_DELAYS_MS = [
+  FIRST_COMPLETION_RETRY_MS,
+  SECOND_COMPLETION_RETRY_MS,
+  LAST_COMPLETION_RETRY_MS
+];
+var WAKE_COOLDOWN_MS = 5;
+var QUIET_REFILL_MS = 10;
+var REFILL_FRACTION = 0.7;
+var Dispatcher = class {
+  #dependencies;
+  #sleep;
+  #inFlight = /* @__PURE__ */ new Set();
+  #completions;
+  #pending = /* @__PURE__ */ new Map();
+  #recoveryTimer;
+  #recovery;
+  #running = false;
+  #loop;
+  #wakeUp;
+  /** Free slots the claim the loop was woken for needs at least; undefined while nobody woke it. */
+  #signalledMinimum;
+  /** Free slots a claim needs unless the poll interval or the quiet refill time passed: claims refill in groups. */
+  #refillThreshold;
+  /** Handlers whose last claim got less than it asked for: the store has nothing more for them right now. */
+  #exhaustedHandlers = /* @__PURE__ */ new Set();
+  /** Grows with every wake-up: a claim that started before one must not mark a handler exhausted. */
+  #wakeGeneration = 0;
+  #lastClaimStartedAt = Number.NEGATIVE_INFINITY;
+  #cooldownTimer;
+  #refillScheduled = false;
+  #quietRefillTimer;
+  #unwatch;
+  #watching;
+  /** Set when a stop gave up at its deadline: the store may be closed, so nothing more is started or retried. */
+  #abandoned = false;
+  /** Stops the lease renewal (or transactional lease guard) of each delivery whose handler runs. */
+  #leaseKeepers = /* @__PURE__ */ new Map();
+  #timers;
+  constructor(dependencies) {
+    this.#dependencies = dependencies;
+    this.#timers = new DeliveryTimers(dependencies.clock);
+    this.#sleep = dependencies.sleep ?? ((milliseconds) => this.#timers.sleep(milliseconds));
+    const { store, clock, settings } = dependencies;
+    this.#refillThreshold = Math.ceil(
+      Math.min(settings.concurrency, settings.batchSize) * REFILL_FRACTION
+    );
+    const { completionBatchWindowMs: windowMs = 0, completionBatchSize: maxBatchSize = 1 } = settings;
+    if (store.completeMany !== void 0 && windowMs > 0) {
+      this.#completions = new CompletionBatcher(
+        { completeMany: (leases, now) => store.completeMany(leases, now) },
+        clock,
+        { windowMs, maxBatchSize },
+        () => this.#inFlight.size
+      );
+    }
+  }
+  get isRunning() {
+    return this.#running;
+  }
+  get inFlightCount() {
+    return this.#inFlight.size;
+  }
+  /**
+   * True while the store reports new deliveries to this dispatcher by itself (see
+   * {@link EventStore.watchNewDeliveries}), from every process: a publisher then has no reason to wake it.
+   */
+  get watchesNewDeliveries() {
+    return this.#unwatch !== void 0;
+  }
+  start() {
     if (this.#running) {
       return;
     }
     this.#running = true;
+    this.#completions?.setClosing(false);
+    this.#watching = this.#watchNewDeliveries();
     this.#loop = this.#runLoop();
   }
-  /** Shortens the wait before the next claim, for example right after a publish. */
+  /**
+   * Asks for a claim soon, for example right after a publish: at once after a quiet period, otherwise
+   * at the end of a short cooldown that merges the wake-ups arriving meanwhile into one claim.
+   */
   wake() {
-    this.#wakeRequested = true;
+    this.#exhaustedHandlers.clear();
+    this.#wakeGeneration += 1;
+    const wait = this.#lastClaimStartedAt + WAKE_COOLDOWN_MS - Date.now();
+    if (wait <= 0) {
+      this.#requestClaim();
+      return;
+    }
+    this.#cooldownTimer ??= chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+      run: () => {
+        this.#cooldownTimer = void 0;
+        this.#requestClaim();
+      },
+      delayMs: wait
+    });
+  }
+  /** Ends the current wait of the claim loop, or the next one at once, for a claim once `minimumFree` slots are free. */
+  #signal(minimumFree) {
+    this.#signalledMinimum = Math.min(this.#signalledMinimum ?? minimumFree, minimumFree);
     this.#wakeUp?.();
   }
   /**
-   * Stops claiming, waits up to the shutdown timeout for running handlers,
-   * then aborts the rest and releases their deliveries for another process.
+   * Starts listening to the store's reports of new deliveries. Polling stays the safety net: a store
+   * that cannot listen, or fails to, only costs latency, so a failure is reported and otherwise ignored.
    */
-  async stop() {
+  async #watchNewDeliveries() {
+    const { store, notifier } = this.#dependencies;
+    try {
+      const unwatch = await store.watchNewDeliveries?.(() => this.wake());
+      if (unwatch !== void 0 && !this.#running) {
+        await unwatch();
+        return;
+      }
+      this.#unwatch = unwatch;
+      if (unwatch !== void 0) {
+        this.wake();
+      }
+    } catch (error) {
+      notifier.failure("watch", error);
+    }
+  }
+  /** Stops listening to the store's reports of new deliveries. */
+  async #stopWatching() {
+    await this.#watching;
+    const unwatch = this.#unwatch;
+    this.#unwatch = void 0;
+    try {
+      await unwatch?.();
+    } catch (error) {
+      this.#dependencies.notifier.failure("watch", error);
+    }
+  }
+  /**
+   * Stops claiming and waits for running handlers until the drain point of `deadline` (default: the
+   * shutdown timeout from now), then aborts the rest and releases their deliveries for another
+   * process. Deliveries still in flight when the deadline itself passes are abandoned: their leases
+   * expire and they run again elsewhere. Resolves with how many were abandoned.
+   */
+  async stop(deadline) {
+    const { clock, settings } = this.#dependencies;
+    const own = deadline ?? new ShutdownDeadline(clock, settings.shutdownTimeoutMs);
+    try {
+      return await this.#stopWithin(own);
+    } finally {
+      if (deadline === void 0) {
+        own.dispose();
+      }
+    }
+  }
+  async #stopWithin(deadline) {
     if (!this.#running) {
-      return;
+      await this.#closeRecovery(deadline);
+      return 0;
     }
     this.#running = false;
-    this.wake();
-    const deadline = Date.now() + this.#dependencies.settings.shutdownTimeoutMs;
-    await this.#waitUntil(this.#loop, deadline);
+    this.#completions?.setClosing(true);
+    this.#cooldownTimer?.();
+    this.#cooldownTimer = void 0;
+    this.#quietRefillTimer?.();
+    this.#quietRefillTimer = void 0;
+    this.#signal(this.#refillThreshold);
+    await deadline.race(this.#stopWatching());
+    await deadline.race(this.#loop);
     const settled = Promise.allSettled([...this.#inFlight].map((delivery) => delivery.settled));
-    if (await this.#waitUntil(settled, deadline) === "timeout") {
+    if (await deadline.raceDrain(settled) === "timeout") {
       for (const delivery of this.#inFlight) {
-        delivery.controller.abort(new DispatcherStoppedError("relaybus dispatcher stopped"));
+        delivery.controller.abort(new chunk3OHMEMZA_cjs.DispatcherStoppedError("relaybus dispatcher stopped"));
+      }
+      if (await deadline.race(settled) === "timeout") {
+        return this.#abandon();
+      }
+    }
+    await this.#closeRecovery(deadline);
+    await deadline.race(this.#relinquish());
+    return 0;
+  }
+  /**
+   * The deadline passed with deliveries still in flight (aborted, their release not answered): forgets
+   * them and every settlement still to retry. Whatever they release or complete from now on may reach a
+   * closed store; a delivery whose state change is lost stays leased until the lease expires and then
+   * runs again (at-least-once).
+   */
+  #abandon() {
+    this.#abandoned = true;
+    for (const stopKeeping of this.#leaseKeepers.values()) {
+      stopKeeping();
+    }
+    this.#leaseKeepers.clear();
+    this.#timers.cancelAll();
+    this.#recoveryTimer?.();
+    this.#recoveryTimer = void 0;
+    this.#pending.clear();
+    return this.#inFlight.size;
+  }
+  /**
+   * Gives the settlements still pending one last try and forgets them. A pass of the timer may be inside the
+   * store: it ends before the last pass starts. A store that does not answer before the deadline gets no
+   * further call, since it may be closed right after.
+   */
+  async #closeRecovery(deadline) {
+    this.#recoveryTimer?.();
+    this.#recoveryTimer = void 0;
+    const lastTry = (async () => {
+      await this.#recovery;
+      await this.#recoverSettlements();
+    })();
+    await deadline.race(lastTry);
+    this.#pending.clear();
+  }
+  /**
+   * Retries every pending settlement once; a pass that is already running is the one returned. A store that
+   * still fails leaves the settlement for the next attempt (it was reported when it first failed).
+   */
+  #recoverSettlements() {
+    this.#recovery ??= this.#recoverAll().finally(() => {
+      this.#recovery = void 0;
+    });
+    return this.#recovery;
+  }
+  async #recoverAll() {
+    for (const [key, entry] of [...this.#pending]) {
+      if (this.#pending.get(key) !== entry) {
+        continue;
+      }
+      try {
+        const applied = await entry.settle();
+        this.#pending.delete(pendingKey(entry.delivery));
+        if (applied) {
+          entry.applied();
+        } else {
+          this.#dependencies.notifier.notify("onLeaseLost", { delivery: entry.delivery });
+        }
+      } catch {
       }
-      await settled;
+    }
+  }
+  #retain(entry) {
+    if (this.#abandoned) {
+      return;
+    }
+    this.#pending.set(pendingKey(entry.delivery), entry);
+    this.#recoveryTimer ??= chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+      run: () => void this.#recoverSettlements(),
+      delayMs: this.#dependencies.settings.pollIntervalMs,
+      repeat: true,
+      unref: true
+    });
+  }
+  /** Gives lease groups the owner no longer works on back to the store, so other workers need not wait for expiry. */
+  async #relinquish() {
+    const { store, clock, notifier, settings } = this.#dependencies;
+    try {
+      await store.relinquish?.(settings.owner, clock.now());
+    } catch (error) {
+      notifier.failure("relinquish", error);
     }
   }
   /** Claims one batch and resolves when every claimed delivery settled. Returns how many ran. */
   async processBatch() {
-    const started = await this.#claimAndStart();
+    const { started } = await this.#claimAndStart();
     await Promise.allSettled(started.map((delivery) => delivery.settled));
     return started.length;
   }
   async #waitUntil(work, deadline) {
-    let timer;
+    let cancel;
     const timedOut = new Promise((resolve) => {
-      timer = setTimeout(() => resolve("timeout"), Math.max(0, deadline - Date.now()));
+      cancel = chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+        run: () => resolve("timeout"),
+        delayMs: Math.max(0, deadline - Date.now())
+      });
     });
     const outcome = await Promise.race([work.then(() => "done"), timedOut]);
-    clearTimeout(timer);
+    cancel?.();
     return outcome;
   }
+  /**
+   * Claims until stopped. A claim that filled its batch is followed by the next one at once while enough
+   * slots are free. Otherwise the loop sleeps until a wake-up (a publish, a store notification, or enough
+   * deliveries settling to refill a group of slots) or the poll interval. Only the poll interval claims
+   * for fewer free slots than the refill threshold, so a busy dispatcher never claims slot by slot.
+   */
   async #runLoop() {
+    let minimumFree = 1;
     while (this.#running) {
-      let claimedCount = 0;
-      try {
-        claimedCount = (await this.#claimAndStart()).length;
-      } catch (error) {
-        this.#dependencies.notifier.failure("claim", error);
+      let round = { requested: 0, claimed: 0 };
+      if (this.#freeSlots() >= minimumFree) {
+        try {
+          round = await this.#claimAndStart();
+        } catch (error) {
+          this.#dependencies.notifier.failure("claim", error);
+        }
       }
-      if (claimedCount > 0 && this.#freeSlots() > 0) {
+      if (round.requested > 0 && round.claimed === round.requested && this.#freeSlots() >= this.#refillThreshold) {
+        minimumFree = this.#refillThreshold;
         continue;
       }
-      await this.#waitForWakeUp();
+      minimumFree = await this.#waitForWakeUp();
+      if (this.#freeSlots() < minimumFree) {
+        this.#requestClaim();
+      }
     }
   }
+  /** Waits for a wake-up or the poll interval. Resolves with the free slots the next claim needs. */
   async #waitForWakeUp() {
-    if (this.#wakeRequested) {
-      this.#wakeRequested = false;
-      return;
+    if (this.#signalledMinimum === void 0) {
+      await new Promise((resolve) => {
+        const cancel = chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+          run: () => {
+            this.#signalledMinimum = 1;
+            resolve();
+          },
+          delayMs: this.#dependencies.settings.pollIntervalMs
+        });
+        this.#wakeUp = () => {
+          cancel();
+          resolve();
+        };
+      });
+      this.#wakeUp = void 0;
     }
-    await new Promise((resolve) => {
-      const timer = setTimeout(done, this.#dependencies.settings.pollIntervalMs);
-      function done() {
-        clearTimeout(timer);
-        resolve();
+    const minimumFree = this.#signalledMinimum;
+    this.#signalledMinimum = void 0;
+    return minimumFree;
+  }
+  /**
+   * A delivery settled. Its slot is worth refilling when the store may have more for its handler: a keyed
+   * delivery unblocks the next one of its key, a delivery that did not succeed may be due again at once
+   * (a retry without delay, a release), and a handler whose last claim was full may have a backlog.
+   */
+  #onSettled(delivery, succeeded) {
+    if (delivery.event.key !== null || !succeeded || !this.#exhaustedHandlers.has(delivery.handler)) {
+      this.#requestClaim();
+    }
+  }
+  /**
+   * Asks the loop for a claim. Once a group of slots is free the claim waits only for the deliveries
+   * settling in the same tick, so they are claimed for together; fewer free slots are refilled when no
+   * claim started for a short while. With no free slot the next settlement asks again.
+   */
+  #requestClaim() {
+    const free = this.#freeSlots();
+    if (free >= this.#refillThreshold) {
+      if (!this.#refillScheduled) {
+        this.#refillScheduled = true;
+        setImmediate(() => {
+          this.#refillScheduled = false;
+          this.#signal(this.#refillThreshold);
+        });
       }
-      this.#wakeUp = done;
-    });
-    this.#wakeUp = void 0;
-    this.#wakeRequested = false;
+    } else if (free > 0) {
+      this.#quietRefillTimer ??= chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+        run: () => {
+          this.#quietRefillTimer = void 0;
+          this.#signal(1);
+        },
+        delayMs: Math.max(0, this.#lastClaimStartedAt + QUIET_REFILL_MS - Date.now())
+      });
+    }
   }
   #freeSlots() {
     return this.#dependencies.settings.concurrency - this.#inFlight.size;
   }
+  /** Claims for every handler with room and starts what was claimed. */
   async #claimAndStart() {
-    const { store, registry, clock, settings } = this.#dependencies;
+    const { store, registry, clock, settings, observation } = this.#dependencies;
     const started = [];
+    let requested = 0;
     for (const request of this.#planClaims(registry.all())) {
       const now = clock.now();
-      const claimed = await store.claim({
+      const wakeGeneration = this.#wakeGeneration;
+      this.#lastClaimStartedAt = Date.now();
+      this.#quietRefillTimer?.();
+      this.#quietRefillTimer = void 0;
+      requested += request.limit;
+      const claim = {
         handlers: request.handlers,
         limit: request.limit,
         leaseOwner: settings.owner,
         leaseExpiresAt: new Date(now.getTime() + settings.leaseDurationMs),
         now
-      });
-      for (const delivery of claimed) {
+      };
+      const claimed = await (observation === void 0 ? store.claim(claim) : observation.claim(store, claim));
+      for (const handler of request.handlers) {
+        if (claimed.length < request.limit && wakeGeneration === this.#wakeGeneration) {
+          this.#exhaustedHandlers.add(handler);
+        } else {
+          this.#exhaustedHandlers.delete(handler);
+        }
+      }
+      for (const delivery of this.#abandoned ? [] : claimed) {
         started.push(this.#start(delivery));
       }
     }
-    return started;
+    return { requested, claimed: started.length, started };
   }
   /** One claim for handlers without a concurrency limit, one per limited handler with room. */
   #planClaims(registrations) {
@@ -776,22 +1788,25 @@ var Dispatcher = class {
       if (registration.concurrency === null || free === 0) {
         continue;
       }
-      const room = registration.concurrency - this.#countInFlight(registration.id);
+      const room = registration.concurrency - this.#countInFlight(registration);
       const limit = Math.min(room, free);
       if (limit > 0) {
-        plans.push({ handlers: [registration.id], limit });
+        plans.push({ handlers: [...registration.claimIds], limit });
         free -= limit;
       }
     }
     if (unlimited.length > 0 && free > 0) {
-      plans.push({ handlers: unlimited.map((registration) => registration.id), limit: free });
+      plans.push({
+        handlers: unlimited.flatMap((registration) => registration.claimIds),
+        limit: free
+      });
     }
     return plans;
   }
-  #countInFlight(handler) {
+  #countInFlight(registration) {
     let count = 0;
     for (const delivery of this.#inFlight) {
-      if (delivery.handler === handler) {
+      if (registration.claimIds.includes(delivery.handler)) {
         count += 1;
       }
     }
@@ -799,56 +1814,82 @@ var Dispatcher = class {
   }
   #start(delivery) {
     const controller = new AbortController();
+    let succeeded = false;
     const entry = {
       handler: delivery.handler,
       controller,
-      settled: Promise.resolve().then(() => this.#execute(delivery, controller)).catch((error) => this.#dependencies.notifier.failure("dispatch", error)).finally(() => {
+      settled: Promise.resolve().then(async () => {
+        succeeded = await this.#execute(delivery, controller);
+      }).catch((error) => this.#dependencies.notifier.failure("dispatch", error)).finally(() => {
         this.#inFlight.delete(entry);
-        this.wake();
+        this.#onSettled(delivery, succeeded);
       })
     };
     this.#inFlight.add(entry);
     return entry;
   }
+  /** Runs one delivery. Resolves true when its handler succeeded, so the delivery is done for good. */
   async #execute(delivery, controller) {
     const { registry, notifier, clock } = this.#dependencies;
     const registration = registry.get(delivery.handler);
+    for (const key of [...this.#pending.keys()].filter(
+      (pending) => pending.startsWith(`${delivery.deliveryId}\0`)
+    )) {
+      this.#pending.delete(key);
+    }
     notifier.notify("onDeliveryStarted", { delivery });
     const startedAt = clock.now().getTime();
     if (delivery.attempt > registration.retry.attempts) {
       await this.#bury(
         delivery,
-        new RelayBusError(
+        new chunk3OHMEMZA_cjs.AttemptsExhaustedError(
           `Delivery reached attempt ${delivery.attempt} of ${registration.retry.attempts} after its lease expired`
         )
       );
-      return;
+      return false;
     }
     let stopHeartbeat = () => void 0;
     try {
-      stopHeartbeat = registration.transactional ? await this.#guardTransactionalLease(registration, delivery, controller) : this.#startHeartbeat(delivery, controller);
-      const outcome = await this.#runHandler(registration, delivery, controller);
+      stopHeartbeat = registration.transactional ? await this.#guardTransactionalLease(registration, { delivery, controller }) : startLeaseHeartbeat(this.#dependencies, { delivery, controller });
+      this.#leaseKeepers.set(delivery, stopHeartbeat);
+      const outcome = await this.#runHandler(registration, { delivery, controller });
+      const durationMs = clock.now().getTime() - startedAt;
       if (outcome === "completed") {
-        notifier.notify("onDeliverySucceeded", {
+        notifier.notify("onDeliverySucceeded", { delivery, durationMs });
+      } else {
+        this.#retain({
           delivery,
-          durationMs: clock.now().getTime() - startedAt
+          settle: () => this.#complete(delivery),
+          applied: () => notifier.notify("onDeliverySucceeded", { delivery, durationMs })
         });
       }
+      return true;
     } catch (error) {
-      if (error instanceof LeaseLostError) {
+      if (this.#abandoned) {
+        return false;
+      }
+      if (error instanceof chunk3OHMEMZA_cjs.LeaseLostError) {
         notifier.notify("onLeaseLost", { delivery });
-      } else if (error instanceof DispatcherStoppedError) {
+        if (!error.storeConfirmed) {
+          await this.#giveBack(registration, { delivery, error });
+        }
+      } else if (error instanceof chunk3OHMEMZA_cjs.DispatcherStoppedError) {
         await this.#release(delivery);
       } else {
-        await this.#fail(registration, delivery, error);
+        await this.#fail(registration, { delivery, error });
       }
+      return false;
     } finally {
       stopHeartbeat();
+      this.#leaseKeepers.delete(delivery);
     }
   }
-  async #runHandler(registration, delivery, controller) {
+  async #runHandler(registration, {
+    delivery,
+    controller
+  }) {
     const { store, clock } = this.#dependencies;
-    const payload = await validatePayload(
+    const payload = await chunk3OHMEMZA_cjs.validatePayload(
       delivery.event.type,
       registration.schema,
       delivery.event.payload
@@ -856,14 +1897,16 @@ var Dispatcher = class {
     const event = { ...delivery.event, payload };
     if (registration.transactional) {
       await store.transaction(async (transaction) => {
-        await this.#invoke(registration, event, delivery, controller, transaction);
+        await this.#invoke({ registration, event, delivery, controller, transaction });
         if (!await store.complete(delivery, clock.now(), transaction)) {
-          throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+          throw new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+            storeConfirmed: true
+          });
         }
       });
       return "completed";
     }
-    await this.#invoke(registration, event, delivery, controller, void 0);
+    await this.#invoke({ registration, event, delivery, controller, transaction: void 0 });
     return this.#confirmCompletion(delivery);
   }
   /**
@@ -871,11 +1914,14 @@ var Dispatcher = class {
    * still held. Gives up to lease expiry, which reruns the handler: at-least-once.
    */
   async #confirmCompletion(delivery) {
-    const { store, clock, notifier } = this.#dependencies;
+    const { notifier } = this.#dependencies;
     for (let attempt = 0; ; attempt += 1) {
+      if (this.#abandoned) {
+        return "unconfirmed";
+      }
       let completed;
       try {
-        completed = await store.complete(delivery, clock.now());
+        completed = await this.#complete(delivery);
       } catch (error) {
         const delay = COMPLETION_RETRY_DELAYS_MS[attempt];
         if (delay === void 0) {
@@ -886,12 +1932,20 @@ var Dispatcher = class {
         continue;
       }
       if (!completed) {
-        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+        throw new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+          storeConfirmed: true
+        });
       }
       return "completed";
     }
   }
-  async #invoke(registration, event, delivery, controller, transaction) {
+  /** Records one completion, grouped with its neighbours when the store can complete many at once. */
+  #complete(delivery) {
+    const { store, clock } = this.#dependencies;
+    return this.#completions === void 0 ? store.complete(delivery, clock.now()) : this.#completions.submit(delivery);
+  }
+  async #invoke(input) {
+    const { registration, event, delivery, controller, transaction } = input;
     const context = {
       deliveryId: delivery.deliveryId,
       handler: delivery.handler,
@@ -904,28 +1958,37 @@ var Dispatcher = class {
     if (controller.signal.aborted) {
       throw controller.signal.reason;
     }
+    const handle = () => runInIsolatedScope(scope, () => registration.handle(event, context));
+    const { observation } = this.#dependencies;
     const work = Promise.resolve().then(
-      () => runInIsolatedScope(scope, () => registration.handle(event, context))
+      observation === void 0 ? handle : () => observation.process({ registration, delivery }, handle)
     );
     work.catch(() => void 0);
-    let timer;
+    let cancelTimeout;
     if (registration.timeoutMs !== null) {
       const timeoutMs = registration.timeoutMs;
-      timer = setTimeout(() => {
-        controller.abort(
-          new HandlerTimeoutError(
-            `Handler '${registration.id}' did not settle within ${timeoutMs}ms`
-          )
-        );
-      }, timeoutMs);
+      cancelTimeout = this.#timers.start({
+        run: () => {
+          controller.abort(
+            new chunk3OHMEMZA_cjs.HandlerTimeoutError(
+              `Handler '${registration.id}' did not settle within ${timeoutMs}ms`
+            )
+          );
+        },
+        delayMs: timeoutMs
+      });
     }
     try {
-      await Promise.race([work, rejectOnAbort(controller.signal)]);
+      const settled = Promise.race([work, rejectOnAbort(controller.signal)]);
+      await (observation === void 0 ? settled : observation.observe({ registration, delivery }, settled));
     } catch (error) {
-      await this.#awaitAbandonedHandler(work, error, transaction !== void 0);
+      await this.#awaitAbandonedHandler(work, {
+        reason: error,
+        transactional: transaction !== void 0
+      });
       throw error;
     } finally {
-      clearTimeout(timer);
+      cancelTimeout?.();
     }
   }
   /**
@@ -935,7 +1998,7 @@ var Dispatcher = class {
    * Transactional handlers are always awaited; others for one lease duration,
    * except at shutdown, which already waited.
    */
-  async #awaitAbandonedHandler(work, reason, transactional) {
+  async #awaitAbandonedHandler(work, { reason, transactional }) {
     const settledWork = work.then(
       () => void 0,
       () => void 0
@@ -944,7 +2007,7 @@ var Dispatcher = class {
       await settledWork;
       return;
     }
-    if (reason instanceof DispatcherStoppedError) {
+    if (reason instanceof chunk3OHMEMZA_cjs.DispatcherStoppedError) {
       return;
     }
     const deadline = Date.now() + this.#dependencies.settings.leaseDurationMs;
@@ -957,72 +2020,42 @@ var Dispatcher = class {
    * lease is extended once to cover the handler timeout, and the handler is
    * aborted when that lease ends.
    */
-  async #guardTransactionalLease(registration, delivery, controller) {
+  async #guardTransactionalLease(registration, {
+    delivery,
+    controller
+  }) {
     const { store, clock, settings } = this.#dependencies;
     const now = clock.now();
     let expiry = delivery.leaseExpiresAt.getTime();
     if (registration.timeoutMs !== null && now.getTime() + registration.timeoutMs >= expiry) {
       expiry = now.getTime() + registration.timeoutMs + settings.leaseDurationMs;
       if (!await store.extendLease(delivery, new Date(expiry), now)) {
-        throw new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`);
+        throw new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, {
+          storeConfirmed: true
+        });
       }
     }
-    const timer = setTimeout(
-      () => {
-        controller.abort(new LeaseLostError(`Lease on delivery ${delivery.deliveryId} expired`));
-      },
-      Math.max(0, expiry - clock.now().getTime())
-    );
-    timer.unref();
-    return () => clearTimeout(timer);
-  }
-  /**
-   * Renews the lease every third of its duration. A worker that cannot renew
-   * aborts its handler once the last confirmed expiry passes, because another
-   * worker may then claim the delivery (self-fencing).
-   */
-  #startHeartbeat(delivery, controller) {
-    const { store, clock, notifier, settings } = this.#dependencies;
-    let confirmedExpiry = delivery.leaseExpiresAt.getTime();
-    let renewing = false;
-    const abortLeaseLost = () => {
-      controller.abort(new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`));
-    };
-    const timer = setInterval(
-      () => {
-        const now = clock.now();
-        if (now.getTime() >= confirmedExpiry) {
-          abortLeaseLost();
-          return;
-        }
-        if (renewing) {
-          return;
-        }
-        renewing = true;
-        const expiry = now.getTime() + settings.leaseDurationMs;
-        store.extendLease(delivery, new Date(expiry), now).then((extended) => {
-          if (extended) {
-            confirmedExpiry = expiry;
-          } else {
-            abortLeaseLost();
-          }
-        }).catch((error) => notifier.failure("extend-lease", error)).finally(() => {
-          renewing = false;
-        });
+    return chunk3OHMEMZA_cjs.schedule(clock, {
+      run: () => {
+        controller.abort(new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} expired`));
       },
-      Math.max(1, Math.floor(settings.leaseDurationMs / 3))
-    );
-    timer.unref();
-    return () => clearInterval(timer);
+      delayMs: Math.max(0, expiry - clock.now().getTime()),
+      unref: true
+    });
   }
-  async #fail(registration, delivery, error) {
-    const { store, clock, random, notifier } = this.#dependencies;
+  async #fail(registration, { delivery, error }) {
     const policy = registration.retry;
     if (delivery.attempt >= policy.attempts || !isRetryableError(policy, error)) {
       await this.#bury(delivery, error);
       return;
     }
-    const errorInfo = toErrorInfo(error);
+    await this.#reschedule(registration, { delivery, error });
+  }
+  /** Schedules the next attempt with the retry policy's backoff. */
+  async #reschedule(registration, { delivery, error }) {
+    const { store, clock, random, notifier } = this.#dependencies;
+    const policy = registration.retry;
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     const now = clock.now();
     const availableAt = new Date(
       now.getTime() + computeRetryDelay(policy, delivery.attempt, random)
@@ -1032,6 +2065,11 @@ var Dispatcher = class {
       rescheduled = await store.reschedule(delivery, availableAt, errorInfo, now);
     } catch (storeError) {
       notifier.failure("reschedule", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.reschedule(delivery, availableAt, errorInfo, now),
+        applied: () => notifier.notify("onDeliveryRetryScheduled", { delivery, error: errorInfo, availableAt })
+      });
       return;
     }
     if (rescheduled) {
@@ -1042,12 +2080,17 @@ var Dispatcher = class {
   }
   async #bury(delivery, error) {
     const { store, clock, notifier } = this.#dependencies;
-    const errorInfo = toErrorInfo(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     let buried;
     try {
       buried = await store.bury(delivery, errorInfo, clock.now());
     } catch (storeError) {
       notifier.failure("bury", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.bury(delivery, errorInfo, clock.now()),
+        applied: () => notifier.notify("onDeliveryDead", { delivery, error: errorInfo })
+      });
       return;
     }
     if (buried) {
@@ -1056,6 +2099,21 @@ var Dispatcher = class {
       notifier.notify("onLeaseLost", { delivery });
     }
   }
+  /**
+   * A worker that only noticed locally that its lease ran out may still own the delivery in the
+   * store, where other deliveries of its lane keep renewing the lane: it must not stay in flight
+   * for ever. The attempt took longer than its lease, so it counts as a failed attempt (an
+   * exhausted delivery is dead-lettered, whatever a custom `retryIf` says): a handler that always
+   * outlives its lease cannot run for ever at attempt 1. If the lease is gone for real the store
+   * refuses and nothing changes. The lost lease was reported already.
+   */
+  async #giveBack(registration, { delivery, error }) {
+    if (delivery.attempt >= registration.retry.attempts) {
+      await this.#bury(delivery, error);
+    } else {
+      await this.#reschedule(registration, { delivery, error });
+    }
+  }
   async #release(delivery) {
     const { store, clock, notifier } = this.#dependencies;
     let released;
@@ -1063,6 +2121,11 @@ var Dispatcher = class {
       released = await store.release(delivery, clock.now());
     } catch (storeError) {
       notifier.failure("release", storeError);
+      this.#retain({
+        delivery,
+        settle: () => store.release(delivery, clock.now()),
+        applied: () => notifier.notify("onDeliveryReleased", { delivery })
+      });
       return;
     }
     if (released) {
@@ -1072,51 +2135,64 @@ var Dispatcher = class {
     }
   }
 };
-function rejectOnAbort(signal) {
-  return new Promise((_, reject) => {
-    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
-  });
-}
 
 // src/handler-registry.ts
 var HANDLER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,254}$/;
 var HandlerRegistry = class {
   #byId = /* @__PURE__ */ new Map();
+  #byClaimId = /* @__PURE__ */ new Map();
   #byEventType = /* @__PURE__ */ new Map();
   register(input, defaults) {
     const { options } = input;
     if (!HANDLER_ID_PATTERN.test(options.id)) {
-      throw new ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         `Handler id '${options.id}' must be 1-255 characters of letters, digits, '.', '_', ':', '/' or '-'`
       );
     }
-    if (this.#byId.has(options.id)) {
-      throw new ConfigurationError(`Handler id '${options.id}' is already registered`);
-    }
-    if (options.concurrency !== void 0 && (!Number.isInteger(options.concurrency) || options.concurrency < 1)) {
-      throw new ConfigurationError(
-        `Concurrency of handler '${options.id}' must be a positive integer, received ${options.concurrency}`
-      );
+    const claimIds = [options.id, ...input.legacyIds ?? []];
+    this.#assertUnregistered(claimIds);
+    if (options.concurrency !== void 0) {
+      chunk3OHMEMZA_cjs.assertPositiveInteger(options.concurrency, `Concurrency of handler '${options.id}'`);
     }
     const registration = {
       id: options.id,
-      eventType: input.eventType,
+      eventTypes: input.eventTypes,
+      claimIds,
       schema: input.schema,
       handle: input.handle,
       retry: createRetryPolicy(options.retry, defaults.retry),
-      timeoutMs: resolveTimeout(options.timeout, defaults.timeoutMs, options.id),
+      timeoutMs: resolveTimeout(options.timeout, {
+        fallback: defaults.timeoutMs,
+        handlerId: options.id
+      }),
       concurrency: options.concurrency ?? null,
       transactional: options.transactional ?? false,
       forwardsToTransport: input.forwardsToTransport
     };
-    this.#byId.set(registration.id, registration);
-    const forType = this.#byEventType.get(registration.eventType) ?? [];
-    forType.push(registration);
-    this.#byEventType.set(registration.eventType, forType);
+    this.#index(registration);
     return registration;
   }
+  #assertUnregistered(claimIds) {
+    for (const id of claimIds) {
+      if (this.#byClaimId.has(id)) {
+        throw new chunk3OHMEMZA_cjs.ConfigurationError(`Handler id '${id}' is already registered`);
+      }
+    }
+  }
+  #index(registration) {
+    this.#byId.set(registration.id, registration);
+    for (const id of registration.claimIds) {
+      this.#byClaimId.set(id, registration);
+    }
+    for (const eventType of registration.eventTypes) {
+      const forType = this.#byEventType.get(eventType) ?? [];
+      forType.push(registration);
+      this.#byEventType.set(eventType, forType);
+    }
+  }
+  /** The registration that runs deliveries stored under `id`, its own id or a legacy one. */
   get(id) {
-    return this.#byId.get(id);
+    return this.#byClaimId.get(id);
   }
   forEventType(eventType) {
     return this.#byEventType.get(eventType) ?? [];
@@ -1125,7 +2201,7 @@ var HandlerRegistry = class {
     return [...this.#byId.values()];
   }
 };
-function resolveTimeout(timeout, fallback, handlerId) {
+function resolveTimeout(timeout, { fallback, handlerId }) {
   if (timeout === void 0) {
     return fallback;
   }
@@ -1135,77 +2211,315 @@ function resolveTimeout(timeout, fallback, handlerId) {
   return toTimerMilliseconds(timeout, `Timeout of handler '${handlerId}'`);
 }
 
-// src/notifier.ts
-var Notifier = class {
-  #observers;
-  #logger;
-  constructor(observers, logger) {
-    this.#observers = observers;
-    this.#logger = logger;
-  }
-  notify(method, argument) {
-    for (const observer of this.#observers) {
-      try {
-        observer[method]?.call(
-          observer,
-          argument
-        );
-      } catch (error) {
-        this.#reportObserverFailure(observer, error);
-      }
+// src/notifier.ts
+var Notifier = class {
+  #observers;
+  #logger;
+  /** Hooks at least one observer implements, so callers skip building events nobody reads. */
+  #implemented;
+  constructor(observers, logger) {
+    this.#observers = observers;
+    this.#logger = logger;
+    this.#implemented = new Set(
+      observers.flatMap((observer) => hookNames(observer))
+    );
+  }
+  /** True when some observer implements `method`. */
+  wants(method) {
+    return this.#implemented.has(method);
+  }
+  notify(method, argument) {
+    for (const observer of this.#observers) {
+      try {
+        observer[method]?.call(
+          observer,
+          argument
+        );
+      } catch (error) {
+        this.#reportObserverFailure(observer, error);
+      }
+    }
+  }
+  failure(stage, error) {
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
+    this.#logger.error(
+      `[Notifier](failure) relaybus ${stage} failed | ${errorInfo.name}: ${errorInfo.message}`
+    );
+    for (const observer of this.#observers) {
+      try {
+        observer.onFailure?.({ stage, error: errorInfo });
+      } catch (observerError) {
+        this.#logObserverFailure(observerError);
+      }
+    }
+  }
+  #reportObserverFailure(failedObserver, error) {
+    this.#logObserverFailure(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
+    for (const observer of this.#observers) {
+      if (observer === failedObserver) {
+        continue;
+      }
+      try {
+        observer.onFailure?.({ stage: "observer", error: errorInfo });
+      } catch (observerError) {
+        this.#logObserverFailure(observerError);
+      }
+    }
+  }
+  #logObserverFailure(error) {
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
+    this.#logger.warn(
+      `[Notifier](logObserverFailure) relaybus observer threw | ${errorInfo.name}: ${errorInfo.message}`
+    );
+  }
+};
+function hookNames(observer) {
+  const names = [];
+  for (let target = observer; target !== null && target !== Object.prototype; target = Object.getPrototypeOf(target)) {
+    names.push(
+      ...Object.getOwnPropertyNames(target).filter(
+        (name) => typeof observer[name] === "function"
+      )
+    );
+  }
+  return names;
+}
+
+// src/received-envelope.ts
+function normalizeEnvelope(envelope) {
+  if (typeof envelope.id !== "string" || envelope.id.length === 0) {
+    throw new chunk3OHMEMZA_cjs.InvalidEnvelopeError("Received event has no id");
+  }
+  if (typeof envelope.type !== "string") {
+    throw new chunk3OHMEMZA_cjs.InvalidEnvelopeError(`Received event ${envelope.id} has no type`);
+  }
+  try {
+    chunk3OHMEMZA_cjs.assertEventType(envelope.type);
+  } catch (error) {
+    throw new chunk3OHMEMZA_cjs.InvalidEnvelopeError(chunk3OHMEMZA_cjs.toErrorInfo(error).message);
+  }
+  const occurredAt = toDate(envelope.occurredAt);
+  if (occurredAt === void 0) {
+    throw new chunk3OHMEMZA_cjs.InvalidEnvelopeError(`Received event ${envelope.id} has an invalid occurredAt`);
+  }
+  return {
+    id: envelope.id,
+    type: envelope.type,
+    source: typeof envelope.source === "string" ? envelope.source : "unknown",
+    key: optionalText(envelope.key),
+    payload: envelope.payload,
+    headers: { ...envelope.headers },
+    correlationId: optionalText(envelope.correlationId),
+    causationId: optionalText(envelope.causationId),
+    occurredAt
+  };
+}
+function toDate(value) {
+  const date = typeof value === "string" ? new Date(value) : value;
+  return date instanceof Date && !Number.isNaN(date.getTime()) ? date : void 0;
+}
+function optionalText(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+var DEFAULTS = {
+  concurrency: 10,
+  pollInterval: "1s",
+  leaseDuration: "30s",
+  shutdownTimeout: "30s",
+  completionBatchWindow: "2ms",
+  completionBatchSize: 200,
+  completedRetention: "7d",
+  retentionInterval: "1h",
+  routeTimeoutMs: 3e4,
+  transactionTimeout: "5s"
+};
+function oneOf(value, { allowed, name }) {
+  if (!allowed.includes(value)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `${name} must be one of ${allowed.map((option) => `'${option}'`).join(", ")}, received '${String(value)}'`
+    );
+  }
+  return value;
+}
+function isDispatcherEnabled(options) {
+  return options.dispatcher?.enabled ?? true;
+}
+function resolveBacklogInterval(options) {
+  return options.backlogInterval === void 0 ? void 0 : toTimerMilliseconds(options.backlogInterval, "backlogInterval");
+}
+function resolveTransactionTimeout(options) {
+  return toTimerMilliseconds(
+    options.transactionTimeout ?? DEFAULTS.transactionTimeout,
+    "transactionTimeout"
+  );
+}
+function createHandlerDefaults(options) {
+  return {
+    retry: createRetryPolicy(options.retry),
+    timeoutMs: options.handlerTimeout === void 0 || options.handlerTimeout === false ? null : toTimerMilliseconds(options.handlerTimeout, "handlerTimeout")
+  };
+}
+function createDispatcherSettings(options, generateIdentifier) {
+  const dispatcher = options ?? {};
+  const concurrency = chunk3OHMEMZA_cjs.assertPositiveInteger(
+    dispatcher.concurrency ?? DEFAULTS.concurrency,
+    "dispatcher.concurrency"
+  );
+  return {
+    owner: `${os.hostname()}:${process.pid}:${generateIdentifier()}`,
+    concurrency,
+    batchSize: chunk3OHMEMZA_cjs.assertPositiveInteger(dispatcher.batchSize ?? concurrency, "dispatcher.batchSize"),
+    ...createDispatcherTimings(dispatcher)
+  };
+}
+function createDispatcherTimings(dispatcher) {
+  return {
+    pollIntervalMs: toTimerMilliseconds(
+      dispatcher.pollInterval ?? DEFAULTS.pollInterval,
+      "dispatcher.pollInterval"
+    ),
+    leaseDurationMs: toTimerMilliseconds(
+      dispatcher.leaseDuration ?? DEFAULTS.leaseDuration,
+      "dispatcher.leaseDuration"
+    ),
+    shutdownTimeoutMs: toTimerMilliseconds(
+      dispatcher.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
+      "dispatcher.shutdownTimeout"
+    ),
+    completionBatchWindowMs: toMilliseconds(
+      dispatcher.completionBatchWindow ?? DEFAULTS.completionBatchWindow,
+      "dispatcher.completionBatchWindow"
+    ),
+    completionBatchSize: chunk3OHMEMZA_cjs.assertPositiveInteger(
+      dispatcher.completionBatchSize ?? DEFAULTS.completionBatchSize,
+      "dispatcher.completionBatchSize"
+    )
+  };
+}
+function createRetentionSettings(options) {
+  const completed = options?.completed ?? DEFAULTS.completedRetention;
+  const dead = options?.dead ?? false;
+  return {
+    completedMs: completed === false ? null : toMilliseconds(completed, "retention.completed"),
+    deadMs: dead === false ? null : toMilliseconds(dead, "retention.dead"),
+    intervalMs: toTimerMilliseconds(
+      options?.interval ?? DEFAULTS.retentionInterval,
+      "retention.interval"
+    )
+  };
+}
+
+// src/route-groups.ts
+var TRANSPORT_HANDLER_PREFIX = "relaybus.transport";
+function groupRoutes(routes) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const type = routedType(route.event);
+    const destination = route.destination ?? type;
+    const id = `${TRANSPORT_HANDLER_PREFIX}:${route.transport}:${destination}`;
+    const group = groups.get(id);
+    if (group === void 0) {
+      groups.set(id, createGroup(route, { id, destination, type }));
+    } else {
+      addRoute(group, { route, type, destination });
     }
   }
-  failure(stage, error) {
-    const errorInfo = toErrorInfo(error);
-    this.#logger.error(
-      `[Notifier](failure) relaybus ${stage} failed | ${errorInfo.name}: ${errorInfo.message}`
+  return [...groups.values()];
+}
+function createGroup(route, {
+  id,
+  destination,
+  type
+}) {
+  return {
+    transport: route.transport,
+    destination,
+    id,
+    eventTypes: [type],
+    legacyIds: [`${id}:${type}`],
+    route,
+    ...resolveSettings(route, id)
+  };
+}
+function addRoute(group, {
+  route,
+  type,
+  destination
+}) {
+  const target = `'${group.destination}' of transport '${group.transport}'`;
+  if (route.transport !== group.transport) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `Routes to ${target} and to '${destination}' of transport '${route.transport}' would share the handler id '${group.id}'; rename the transport or the destination`
     );
-    for (const observer of this.#observers) {
-      try {
-        observer.onFailure?.({ stage, error: errorInfo });
-      } catch (observerError) {
-        this.#logObserverFailure(observerError);
-      }
-    }
   }
-  #reportObserverFailure(failedObserver, error) {
-    this.#logObserverFailure(error);
-    const errorInfo = toErrorInfo(error);
-    for (const observer of this.#observers) {
-      if (observer === failedObserver) {
-        continue;
-      }
-      try {
-        observer.onFailure?.({ stage: "observer", error: errorInfo });
-      } catch (observerError) {
-        this.#logObserverFailure(observerError);
-      }
-    }
+  if (group.eventTypes.includes(type)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`Event type ${type} is routed to ${target} twice`);
   }
-  #logObserverFailure(error) {
-    const errorInfo = toErrorInfo(error);
-    this.#logger.warn(
-      `[Notifier](notify) relaybus observer threw | ${errorInfo.name}: ${errorInfo.message}`
+  const { retry, timeoutMs } = resolveSettings(route, group.id);
+  if (timeoutMs !== group.timeoutMs || !sameRetryPolicy(retry, group.retry)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
+      `Routes to ${target} must share retry and timeout, because their events are sent in one queue per key | types=${group.eventTypes[0]},${type}`
     );
   }
-};
+  group.eventTypes.push(type);
+  group.legacyIds.push(`${group.id}:${type}`);
+}
+function resolveSettings(route, id) {
+  return {
+    retry: createRetryPolicy(route.retry, DEFAULT_ROUTE_RETRY_POLICY),
+    timeoutMs: route.timeout === void 0 ? DEFAULTS.routeTimeoutMs : toTimerMilliseconds(route.timeout, `Timeout of handler '${id}'`)
+  };
+}
+function sameRetryPolicy(left, right) {
+  return Object.keys(left).every(
+    (field) => left[field] === right[field]
+  );
+}
+function routedType(event) {
+  const type = typeof event === "string" ? event : event.type;
+  chunk3OHMEMZA_cjs.assertEventType(type);
+  return type;
+}
+
+// src/transaction-budget.ts
+async function runBudgetedTransaction(store, { clock, timeoutMs, work }) {
+  const startedAt = clock.now().getTime();
+  const overrun = () => clock.now().getTime() - startedAt >= timeoutMs;
+  let committing = false;
+  try {
+    return await store.transaction(
+      async (transaction) => {
+        committing = false;
+        const result = await work(transaction);
+        if (overrun()) {
+          throw createTimeoutError(timeoutMs, void 0);
+        }
+        committing = true;
+        return result;
+      },
+      { timeoutMs }
+    );
+  } catch (error) {
+    if (error instanceof chunk3OHMEMZA_cjs.TransactionTimeoutError || committing || !overrun()) {
+      throw error;
+    }
+    throw createTimeoutError(timeoutMs, error);
+  }
+}
+function createTimeoutError(timeoutMs, cause) {
+  const message = `The transaction ran past its ${timeoutMs} ms budget (transactionTimeout) and was rolled back. The usual cause is a slow call to another service (HTTP, gRPC, a broker, a lock) inside the transaction: make external calls before the transaction starts or after it commits, or raise transactionTimeout`;
+  return cause === void 0 ? new chunk3OHMEMZA_cjs.TransactionTimeoutError(message) : new chunk3OHMEMZA_cjs.TransactionTimeoutError(`${message} | cause=${chunk3OHMEMZA_cjs.toErrorInfo(cause).message}`, { cause });
+}
 
 // src/relay-bus.ts
-var DEFAULTS = {
-  concurrency: 10,
-  pollInterval: "1s",
-  leaseDuration: "30s",
-  shutdownTimeout: "30s",
-  completedRetention: "7d",
-  retentionInterval: "1h",
-  routeTimeoutMs: 3e4
-};
-var TRANSPORT_HANDLER_PREFIX = "relaybus.transport";
+var DEFAULT_DRAIN_BATCHES = 1e3;
 var WAKE_DELAY_MS = 25;
 var RelayBus = class {
   #store;
   #source;
   #transactionMode;
+  #transactionTimeoutMs;
   #transactionResolver;
   #unroutedEvents;
   #registry = new HandlerRegistry();
@@ -1218,61 +2532,83 @@ var RelayBus = class {
   #generateIdentifier;
   #dispatcher;
   #dispatcherEnabled;
+  #catalogRequirements = [];
   #setupStore;
   #retention;
   #retentionTimer;
+  #observation;
+  #backlogIntervalMs;
+  #backlogTimer;
+  #shutdownTimeoutMs;
   #state = "idle";
   #starting;
   #stopping;
   constructor(options) {
     this.#store = options.store;
     this.#source = options.source ?? "relaybus";
-    this.#transactionMode = oneOf(
-      options.transactionMode ?? "required",
-      ["required", "optional"],
-      "transactionMode"
-    );
-    this.#unroutedEvents = oneOf(
-      options.unroutedEvents ?? "warn",
-      ["warn", "throw"],
-      "unroutedEvents"
-    );
+    this.#transactionMode = oneOf(options.transactionMode ?? "required", {
+      allowed: ["required", "optional"],
+      name: "transactionMode"
+    });
+    this.#unroutedEvents = oneOf(options.unroutedEvents ?? "warn", {
+      allowed: ["warn", "throw"],
+      name: "unroutedEvents"
+    });
     this.#transactionResolver = options.transactionResolver;
-    this.#defaults = {
-      retry: createRetryPolicy(options.retry),
-      timeoutMs: options.handlerTimeout === void 0 || options.handlerTimeout === false ? null : toTimerMilliseconds(options.handlerTimeout, "handlerTimeout")
-    };
+    this.#transactionTimeoutMs = resolveTransactionTimeout(options);
+    this.#defaults = createHandlerDefaults(options);
     this.#logger = options.logger ?? console;
     this.#notifier = new Notifier(options.observers ?? [], this.#logger);
     this.#clock = options.clock ?? systemClock;
+    this.#observation = BusObservation.create({
+      notifier: this.#notifier,
+      tracer: options.tracer,
+      clock: this.#clock
+    });
+    this.#backlogIntervalMs = resolveBacklogInterval(options);
     this.#generateIdentifier = options.generateIdentifier ?? (() => createUuidV7());
     this.#setupStore = options.setupStore ?? true;
     this.#retention = createRetentionSettings(options.retention);
+    this.#subscriptions = options.subscriptions ?? [];
+    this.#registerConnections(options);
+    this.#dispatcherEnabled = isDispatcherEnabled(options);
+    const settings = createDispatcherSettings(options.dispatcher, this.#generateIdentifier);
+    this.#shutdownTimeoutMs = settings.shutdownTimeoutMs;
+    this.#dispatcher = this.#createDispatcher(settings, options);
+  }
+  #createDispatcher(settings, options) {
+    return new Dispatcher({
+      store: this.#store,
+      registry: this.#registry,
+      clock: this.#clock,
+      random: options.random ?? Math.random,
+      notifier: this.#notifier,
+      settings,
+      observation: DispatchObservation.create({
+        notifier: this.#notifier,
+        tracer: options.tracer,
+        clock: this.#clock
+      })
+    });
+  }
+  /** Registers the transports, then the routes, checks the subscriptions and registers the catalogs. */
+  #registerConnections(options) {
     for (const transport of options.transports ?? []) {
       if (this.#transports.has(transport.name)) {
-        throw new ConfigurationError(`Transport name '${transport.name}' is used twice`);
+        throw new chunk3OHMEMZA_cjs.ConfigurationError(`Transport name '${transport.name}' is used twice`);
       }
       this.#transports.set(transport.name, transport);
     }
-    for (const route of options.routes ?? []) {
-      this.#registerRoute(route);
-    }
-    this.#subscriptions = options.subscriptions ?? [];
+    this.#registerRoutes(options.routes ?? []);
     for (const subscription of this.#subscriptions) {
       const transport = this.#requireTransport(subscription.transport);
       if (transport.subscribe === void 0) {
-        throw new ConfigurationError(`Transport '${transport.name}' cannot subscribe`);
+        throw new chunk3OHMEMZA_cjs.ConfigurationError(`Transport '${transport.name}' cannot subscribe`);
       }
     }
-    this.#dispatcherEnabled = options.dispatcher?.enabled ?? true;
-    this.#dispatcher = new Dispatcher({
-      store: this.#store,
-      registry: this.#registry,
-      clock: this.#clock,
-      random: options.random ?? Math.random,
-      notifier: this.#notifier,
-      settings: createDispatcherSettings(options.dispatcher, this.#generateIdentifier)
-    });
+    for (const catalog of options.catalogs ?? []) {
+      this.registerCatalog(catalog);
+    }
   }
   get store() {
     return this.#store;
@@ -1292,11 +2628,12 @@ var RelayBus = class {
     }
     return true;
   }
+  // eslint-disable-next-line relaybus/max-two-params -- public RelayBus.subscribe signature
   subscribe(event, handler, options) {
     const { type, schema } = describeEvent(event);
     this.#registry.register(
       {
-        eventType: type,
+        eventTypes: [type],
         schema,
         handle: handler,
         options,
@@ -1305,9 +2642,34 @@ var RelayBus = class {
       this.#defaults
     );
   }
+  // eslint-disable-next-line relaybus/max-two-params -- public RelayBus.subscribeCatalog signature
+  subscribeCatalog(catalog, handlers, options = {}) {
+    for (const binding of resolveCatalogHandlers(catalog, { handlers, options })) {
+      this.subscribe(binding.eventClass, binding.handle, binding.options);
+    }
+  }
+  /**
+   * Adds a catalog, or a `consume` / `produce` declaration, to the checks
+   * `start()` runs; `start()` throws a {@link ConfigurationError} naming each
+   * event that is not covered and what it lacks. Equivalent to the `catalogs`
+   * option.
+   */
+  registerCatalog(catalog) {
+    this.#catalogRequirements.push(toCatalogRequirement(catalog));
+  }
+  /**
+   * A view of this bus that publishes only the events of `catalog`, or only
+   * the events named in `options.events` (for example the events this service
+   * produces). Other events fail to compile and are rejected at runtime.
+   */
+  forCatalog(catalog, options = {}) {
+    return new CatalogPublisher(catalog, this, options);
+  }
   /** Registered handlers and routes, for diagnostics. */
   handlers() {
-    return this.#registry.all().map(toDescriptor);
+    return this.#registry.all().flatMap(
+      (registration) => registration.eventTypes.map((eventType) => toDescriptor(registration, eventType))
+    );
   }
   /**
    * Stores an event in the current transaction. Handlers run after the
@@ -1315,21 +2677,32 @@ var RelayBus = class {
    * have been written when the id already exists.
    */
   async publish(event, options = {}) {
-    const [envelope] = await this.#publish([event], options, options.id);
+    const [envelope] = await this.#observedPublish([event], { options, id: options.id });
     return envelope;
   }
   /** Stores several events atomically, in order, sharing one correlation id. */
   async publishAll(events, options = {}) {
-    return this.#publish(events, options, void 0);
+    return this.#observedPublish(events, { options, id: void 0 });
   }
   /**
    * Runs `work` in a new store transaction. `publish` calls inside it join the
-   * transaction without passing it explicitly.
+   * transaction without passing it explicitly. The transaction is held to `transactionTimeout`
+   * and rolled back with a {@link TransactionTimeoutError} when it runs past it.
    */
   async transaction(work) {
-    return this.#store.transaction(
-      (transaction) => runInScope({ transaction }, () => work(transaction))
-    );
+    return runBudgetedTransaction(this.#store, {
+      clock: this.#clock,
+      timeoutMs: this.#transactionTimeoutMs,
+      work: (transaction) => runInScope({ transaction }, () => work(transaction))
+    });
+  }
+  /**
+   * The transaction `publish` would join right now: the one of the enclosing `bus.transaction`
+   * (or `@RelayBusTransaction()` method, or transactional handler), else the one
+   * `transactionResolver` finds. Repositories use it to write in the same transaction.
+   */
+  currentTransaction() {
+    return getCurrentScope()?.transaction ?? this.#transactionResolver?.();
   }
   /**
    * Stores an event received from a broker and schedules it for local handlers.
@@ -1337,7 +2710,13 @@ var RelayBus = class {
    * only after it resolves. Throws {@link InvalidEnvelopeError} for malformed
    * events, which transports should dead-letter instead of redelivering.
    */
-  async receive(envelope) {
+  receive(envelope) {
+    return this.#observation === void 0 ? this.#receive(envelope) : this.#observedReceive(envelope, void 0);
+  }
+  #observedReceive(envelope, origin) {
+    return this.#observation.receive({ envelope, origin }, () => this.#receive(envelope));
+  }
+  async #receive(envelope) {
     const normalized = normalizeEnvelope(envelope);
     const registrations = this.#registry.forEventType(normalized.type).filter((registration) => !registration.forwardsToTransport);
     if (registrations.length === 0) {
@@ -1366,10 +2745,11 @@ var RelayBus = class {
    */
   async start() {
     if (this.#state !== "idle") {
-      throw new RelayBusError(
+      throw new chunk3OHMEMZA_cjs.LifecycleError(
         this.#state === "stopped" ? "A stopped relaybus cannot be started again; create a new instance" : `Cannot start a relaybus that is ${this.#state}`
       );
     }
+    assertCatalogsCovered(this.#catalogRequirements, (type) => this.#registrationsOf(type));
     this.#state = "starting";
     this.#starting = this.#startComponents();
     try {
@@ -1379,21 +2759,43 @@ var RelayBus = class {
     }
   }
   /**
-   * Stops dispatching, waits for running handlers, closes transports and the
-   * store. Waits for a start in progress first. Safe to call more than once.
+   * Stops claiming, waits for running handlers, hands back leases, closes transports and the store,
+   * all within `options.timeout` (default `dispatcher.shutdownTimeout`). When the deadline passes it
+   * aborts the handlers still running, force-closes what relaybus opened itself (never pools or
+   * clients the application passed in) and resolves anyway: it never rejects because of the
+   * deadline. Abandoned deliveries stay leased until their lease expires and then run again
+   * (at-least-once). Waits for a start in progress first. Safe to call more than once: later calls
+   * get the result of the first.
    */
-  async stop() {
+  async stop(options = {}) {
+    const timeoutMs = options.timeout === void 0 ? this.#shutdownTimeoutMs : toTimerMilliseconds(options.timeout, "timeout");
     if (this.#stopping !== void 0) {
       return this.#stopping;
     }
-    if (this.#state === "starting") {
-      await this.#starting.catch(() => void 0);
+    if (this.#state !== "running" && this.#state !== "starting") {
+      return this.#stopOutsideRun(timeoutMs);
     }
-    if (this.#state !== "running") {
-      return;
+    this.#stopping = this.#stopComponents(timeoutMs);
+    const result = await this.#stopping;
+    if (!result.graceful) {
+      this.#logger.warn(
+        `[RelayBus](stop) Shutdown deadline passed, forced close | abandoned=${result.abandonedDeliveries} | timeoutMs=${timeoutMs}`
+      );
+    }
+    return result;
+  }
+  /**
+   * A bus that is not running: an idle one only settles what batches run by hand left behind (and
+   * stays startable); a stopped one has nothing left to do.
+   */
+  async #stopOutsideRun(timeoutMs) {
+    if (this.#state !== "idle") {
+      return { graceful: true, abandonedDeliveries: 0, durationMs: 0 };
     }
-    this.#stopping = this.#stopComponents();
-    return this.#stopping;
+    return withinDeadline(
+      { clock: this.#clock, timeoutMs },
+      (deadline) => this.#dispatcher.stop(deadline)
+    );
   }
   /**
    * Claims and runs one batch of due deliveries, resolving when they settle.
@@ -1406,7 +2808,7 @@ var RelayBus = class {
    * Runs batches until nothing is due. Deliveries scheduled in the future
    * (retries, delays) are not waited for. Intended for tests.
    */
-  async drain(maxBatches = 1e3) {
+  async drain(maxBatches = DEFAULT_DRAIN_BATCHES) {
     let total = 0;
     for (let batch = 0; batch < maxBatches; batch += 1) {
       const processed = await this.runOnce();
@@ -1415,7 +2817,7 @@ var RelayBus = class {
       }
       total += processed;
     }
-    throw new RelayBusError(`drain did not finish within ${maxBatches} batches`);
+    throw new chunk3OHMEMZA_cjs.DrainIncompleteError(`drain did not finish within ${maxBatches} batches`);
   }
   listDeliveries(query = {}) {
     return this.#store.listDeliveries(query);
@@ -1457,41 +2859,128 @@ var RelayBus = class {
       }
       for (const subscription of this.#subscriptions) {
         const transport = this.#transports.get(subscription.transport);
-        await transport.subscribe(subscription.destinations, async (envelope) => {
-          await this.receive(envelope);
-        });
+        await transport.subscribe(
+          subscription.destinations,
+          async (envelope, message) => {
+            await (this.#observation === void 0 ? this.#receive(envelope) : this.#observedReceive(envelope, { transport, destination: message?.destination }));
+          },
+          this.#subscriptionHooks(transport)
+        );
       }
     } catch (error) {
-      await this.#closeTransports();
+      await withinDeadline(
+        { clock: this.#clock, timeoutMs: this.#shutdownTimeoutMs },
+        async (deadline) => {
+          await this.#closeTransports(deadline);
+          return 0;
+        }
+      );
       this.#state = "stopped";
       throw error;
     }
+    if (this.#state !== "starting") {
+      throw new chunk3OHMEMZA_cjs.LifecycleError("relaybus was stopped before it finished starting");
+    }
     if (this.#dispatcherEnabled) {
       this.#dispatcher.start();
     }
-    if (this.#retention.completedMs !== null || this.#retention.deadMs !== null) {
-      this.#retentionTimer = setInterval(() => {
-        this.purgeExpired().catch(() => void 0);
-      }, this.#retention.intervalMs);
-      this.#retentionTimer.unref();
-    }
+    this.#scheduleRetention();
+    this.#scheduleBacklog();
     this.#state = "running";
     this.#logger.log(
-      `[RelayBus](start) relaybus started | handlers=${this.#registry.all().length} dispatcher=${this.#dispatcherEnabled}`
+      `[RelayBus](startComponents) relaybus started | handlers=${this.#registry.all().length} dispatcher=${this.#dispatcherEnabled}`
     );
   }
-  async #stopComponents() {
-    this.#state = "stopping";
-    clearInterval(this.#retentionTimer);
+  /** What a transport may report back while subscribed; undefined when no observer wants it. */
+  #subscriptionHooks(transport) {
+    if (!this.#notifier.wants("onInvalidMessage")) {
+      return void 0;
+    }
+    return {
+      onInvalidMessage: ({ destination, error }) => {
+        const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
+        this.#notifier.notify("onInvalidMessage", {
+          transport: transport.name,
+          system: transport.system ?? transport.name,
+          destination,
+          reason: errorInfo.message,
+          error: errorInfo
+        });
+      }
+    };
+  }
+  /** Applies the retention policy every `retention.interval` while the bus runs, when it deletes anything. */
+  #scheduleRetention() {
+    if (this.#retention.completedMs !== null || this.#retention.deadMs !== null) {
+      this.#retentionTimer = chunk3OHMEMZA_cjs.schedule(this.#clock, {
+        run: () => {
+          this.purgeExpired().catch(() => void 0);
+        },
+        delayMs: this.#retention.intervalMs,
+        repeat: true,
+        unref: true
+      });
+    }
+  }
+  /** Reports the backlog every `backlogInterval` while the bus runs, when an observer wants it. */
+  #scheduleBacklog() {
+    if (this.#backlogIntervalMs !== void 0) {
+      this.#backlogTimer = this.#observation?.startBacklog({
+        intervalMs: this.#backlogIntervalMs,
+        statistics: () => this.statistics()
+      });
+    }
+  }
+  /**
+   * Waits for a start in progress (a failed start leaves nothing to stop), then stops the dispatcher
+   * and closes the transports and the store. A start still running at the deadline is given up: the
+   * transports and the store are force-closed and the start rejects when it resumes.
+   */
+  async #stopComponents(timeoutMs) {
     try {
-      await this.#dispatcher.stop();
-      await this.#closeTransports();
-      await this.#store.close?.();
+      return await withinDeadline({ clock: this.#clock, timeoutMs }, async (deadline) => {
+        if (this.#state === "starting") {
+          const started = await deadline.race(this.#starting.catch(() => void 0));
+          if (started === "timeout") {
+            this.#state = "stopping";
+            await this.#closeConnections(deadline);
+            return 0;
+          }
+        }
+        if (this.#state !== "running") {
+          return 0;
+        }
+        this.#state = "stopping";
+        this.#retentionTimer?.();
+        this.#backlogTimer?.();
+        const abandoned = await this.#dispatcher.stop(deadline);
+        await this.#closeConnections(deadline);
+        return abandoned;
+      });
     } finally {
       this.#state = "stopped";
     }
   }
-  async #publish(events, options, id) {
+  async #closeConnections(deadline) {
+    await this.#closeTransports(deadline);
+    const options = { signal: deadline.signal };
+    await deadline.race(Promise.resolve(this.#store.close?.(options)));
+  }
+  /** Publishes inside the tracer's span, with its trace headers, when the bus is observed. */
+  #observedPublish(events, input) {
+    const observation = this.#observation;
+    if (observation === void 0) {
+      return this.#publish(events, input);
+    }
+    return observation.publish(
+      { eventTypes: events.map((event) => String(event.type)) },
+      (headers) => this.#publish(events, { ...input, options: withTraceHeaders(input.options, headers) })
+    );
+  }
+  async #publish(events, {
+    options,
+    id
+  }) {
     if (events.length === 0) {
       return [];
     }
@@ -1499,10 +2988,27 @@ var RelayBus = class {
     const delayMs = options.delay === void 0 ? 0 : toMilliseconds(options.delay, "delay");
     const availableAt = new Date(now.getTime() + delayMs);
     const scope = getCurrentScope();
+    const entries = await this.#createEntries({ events, options, id, scope, now, availableAt });
+    const deliverable = entries.filter((entry) => entry.deliveries.length > 0);
+    if (deliverable.length > 0) {
+      await this.#appendDeliverable({ entries: deliverable, options, scope, now, delayMs });
+    }
+    return entries.map((entry) => entry.event);
+  }
+  /** One entry per event, in order: its envelope and a delivery for every registration of its type. */
+  async #createEntries(input) {
+    const { events, options, id, scope, now, availableAt } = input;
     const entries = [];
     let correlationId = options.correlationId ?? scope?.event?.correlationId ?? scope?.event?.id;
     for (const event of events) {
-      const envelope = await this.#createEnvelope(event, options, id, scope, now, correlationId);
+      const envelope = await this.#createEnvelope({
+        event,
+        options,
+        id,
+        scope,
+        now,
+        correlationId
+      });
       correlationId = envelope.correlationId;
       const registrations = this.#registry.forEventType(envelope.type);
       if (registrations.length === 0) {
@@ -1515,37 +3021,42 @@ var RelayBus = class {
         )
       });
     }
-    const deliverable = entries.filter((entry) => entry.deliveries.length > 0);
-    if (deliverable.length > 0) {
-      const result = await this.#appendInTransaction(deliverable, options, scope, now);
-      const appended = new Set(result.appendedEventIds);
-      const published = deliverable.map((entry) => entry.event).filter((envelope) => appended.has(envelope.id));
-      if (published.length > 0) {
-        this.#notifier.notify("onPublished", {
-          envelopes: published,
-          deliveries: result.appendedDeliveryCount
-        });
-        if (delayMs === 0) {
-          this.#scheduleWake();
-        }
+    return entries;
+  }
+  /** Appends the entries that have deliveries, reports what was new and wakes the dispatcher when it is due now. */
+  async #appendDeliverable(input) {
+    const { entries, options, scope, now, delayMs } = input;
+    const result = await this.#appendInTransaction(entries, { options, scope, now });
+    const appended = new Set(result.appendedEventIds);
+    const published = entries.map((entry) => entry.event).filter((envelope) => appended.has(envelope.id));
+    if (published.length > 0) {
+      this.#notifier.notify("onPublished", {
+        envelopes: published,
+        deliveries: result.appendedDeliveryCount
+      });
+      if (delayMs === 0) {
+        this.#scheduleWake();
       }
     }
-    return entries.map((entry) => entry.event);
   }
   #reportUnrouted(envelope) {
     const message = `No handler or route for event type, event not stored | type=${envelope.type} id=${envelope.id}`;
     if (this.#unroutedEvents === "throw") {
-      throw new ConfigurationError(message);
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(message);
     }
-    this.#logger.warn(`[RelayBus](publish) ${message}`);
+    this.#logger.warn(`[RelayBus](reportUnrouted) ${message}`);
   }
-  async #appendInTransaction(entries, options, scope, now) {
+  async #appendInTransaction(entries, {
+    options,
+    scope,
+    now
+  }) {
     const transaction = options.transaction ?? scope?.transaction ?? this.#transactionResolver?.();
     if (transaction !== void 0) {
       return this.#store.append(transaction, entries, now);
     }
     if (this.#transactionMode === "required") {
-      throw new TransactionRequiredError(
+      throw new chunk3OHMEMZA_cjs.TransactionRequiredError(
         "publish found no transaction. Pass { transaction }, publish inside bus.transaction(), configure transactionResolver, or set transactionMode to optional"
       );
     }
@@ -1553,24 +3064,25 @@ var RelayBus = class {
       (ownTransaction) => this.#store.append(ownTransaction, entries, now)
     );
   }
-  async #createEnvelope(event, options, id, scope, now, correlationId) {
+  async #createEnvelope(input) {
+    const { event, options, id, scope, now, correlationId } = input;
     if (typeof event.type !== "string") {
-      throw new ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         "publish expects an instance of a class created with defineEvent"
       );
     }
-    assertEventType(event.type);
+    chunk3OHMEMZA_cjs.assertEventType(event.type);
     const schema = event.constructor.schema;
-    const payload = await validatePayload(event.type, schema, event.payload);
+    const payload = await chunk3OHMEMZA_cjs.validatePayload(event.type, schema, event.payload);
     if (options.key !== void 0 && options.key.length === 0) {
-      throw new ConfigurationError("key must not be empty");
+      throw new chunk3OHMEMZA_cjs.ConfigurationError("key must not be empty");
     }
     const eventId = id ?? this.#generateIdentifier();
     return {
       id: eventId,
       type: event.type,
       source: this.#source,
-      key: options.key ?? null,
+      key: options.key ?? chunk3OHMEMZA_cjs.keyFromDefinition(event, payload),
       payload,
       headers: { ...options.headers },
       correlationId: correlationId ?? eventId,
@@ -1581,17 +3093,31 @@ var RelayBus = class {
   #createDelivery(registration, availableAt) {
     return { id: this.#generateIdentifier(), handler: registration.id, availableAt };
   }
-  #registerRoute(route) {
-    const transport = this.#requireTransport(route.transport);
-    const { type } = describeEvent(route.event);
-    const destination = route.destination ?? type;
+  #registrationsOf(eventType) {
+    const registrations = this.#registry.forEventType(eventType);
+    const routes = registrations.filter((registration) => registration.forwardsToTransport).length;
+    return { handlers: registrations.length - routes, routes };
+  }
+  #registerRoutes(routes) {
+    for (const route of routes) {
+      this.#requireTransport(route.transport);
+    }
+    for (const group of groupRoutes(routes)) {
+      this.#registerRoute(group);
+    }
+  }
+  /** Registers one handler for every route to a destination, so a key's events reach it in commit order. */
+  #registerRoute(group) {
+    const transport = this.#transports.get(group.transport);
+    const { route, destination } = group;
     this.#registry.register(
       {
-        eventType: type,
+        eventTypes: group.eventTypes,
+        legacyIds: group.legacyIds,
         schema: void 0,
-        handle: (envelope) => transport.publish(envelope, destination),
+        handle: this.#observation?.sender(transport, destination) ?? ((envelope) => transport.publish(envelope, destination)),
         options: {
-          id: `${TRANSPORT_HANDLER_PREFIX}:${transport.name}:${destination}:${type}`,
+          id: group.id,
           ...route.retry === void 0 ? {} : { retry: route.retry },
           ...route.timeout === void 0 ? {} : { timeout: route.timeout }
         },
@@ -1603,32 +3129,38 @@ var RelayBus = class {
   #requireTransport(name) {
     const transport = this.#transports.get(name);
     if (transport === void 0) {
-      throw new ConfigurationError(`No transport named '${name}' is configured`);
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(`No transport named '${name}' is configured`);
     }
     return transport;
   }
   #scheduleWake() {
-    if (this.#state !== "running") {
+    if (this.#state !== "running" || this.#dispatcher.watchesNewDeliveries) {
       return;
     }
-    setTimeout(() => this.#dispatcher.wake(), WAKE_DELAY_MS).unref();
+    chunk3OHMEMZA_cjs.schedule(this.#clock, {
+      run: () => this.#dispatcher.wake(),
+      delayMs: WAKE_DELAY_MS,
+      unref: true
+    });
   }
-  async #closeTransports() {
+  /** Closes every transport, each at most until the deadline; past it they are asked to force. */
+  async #closeTransports(deadline) {
+    const options = { signal: deadline.signal };
     for (const transport of this.#transports.values()) {
       try {
-        await transport.close();
+        await deadline.race(transport.close(options));
       } catch (error) {
         this.#logger.error(
-          `[RelayBus](closeTransports) Failed to close transport | transport=${transport.name} error=${toErrorInfo(error).message}`
+          `[RelayBus](closeTransports) Failed to close transport | transport=${transport.name} error=${chunk3OHMEMZA_cjs.toErrorInfo(error).message}`
         );
       }
     }
   }
 };
-function toDescriptor(registration) {
+function toDescriptor(registration, eventType) {
   return {
     id: registration.id,
-    eventType: registration.eventType,
+    eventType,
     retry: registration.retry,
     timeoutMs: registration.timeoutMs,
     concurrency: registration.concurrency,
@@ -1638,122 +3170,102 @@ function toDescriptor(registration) {
 }
 function describeEvent(event) {
   if (typeof event === "string") {
-    assertEventType(event);
+    chunk3OHMEMZA_cjs.assertEventType(event);
     return { type: event, schema: void 0 };
   }
-  assertEventType(event.type);
+  chunk3OHMEMZA_cjs.assertEventType(event.type);
   return { type: event.type, schema: event.schema };
 }
-function normalizeEnvelope(envelope) {
-  if (typeof envelope.id !== "string" || envelope.id.length === 0) {
-    throw new InvalidEnvelopeError("Received event has no id");
-  }
-  if (typeof envelope.type !== "string") {
-    throw new InvalidEnvelopeError(`Received event ${envelope.id} has no type`);
-  }
-  try {
-    assertEventType(envelope.type);
-  } catch (error) {
-    throw new InvalidEnvelopeError(toErrorInfo(error).message);
-  }
-  const occurredAt = toDate(envelope.occurredAt);
-  if (occurredAt === void 0) {
-    throw new InvalidEnvelopeError(`Received event ${envelope.id} has an invalid occurredAt`);
-  }
-  return {
-    id: envelope.id,
-    type: envelope.type,
-    source: typeof envelope.source === "string" ? envelope.source : "unknown",
-    key: optionalText(envelope.key),
-    payload: envelope.payload,
-    headers: { ...envelope.headers },
-    correlationId: optionalText(envelope.correlationId),
-    causationId: optionalText(envelope.causationId),
-    occurredAt
-  };
-}
-function toDate(value) {
-  const date = typeof value === "string" ? new Date(value) : value;
-  return date instanceof Date && !Number.isNaN(date.getTime()) ? date : void 0;
-}
-function optionalText(value) {
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function oneOf(value, allowed, name) {
-  if (!allowed.includes(value)) {
-    throw new ConfigurationError(
-      `${name} must be one of ${allowed.map((option) => `'${option}'`).join(", ")}, received '${String(value)}'`
-    );
-  }
-  return value;
-}
-function positiveInteger(value, name) {
-  if (!Number.isInteger(value) || value < 1) {
-    throw new ConfigurationError(`${name} must be a positive integer, received ${value}`);
-  }
-  return value;
-}
-function createDispatcherSettings(options, generateIdentifier) {
-  const concurrency = positiveInteger(
-    options?.concurrency ?? DEFAULTS.concurrency,
-    "dispatcher.concurrency"
-  );
-  return {
-    owner: `${os.hostname()}:${process.pid}:${generateIdentifier()}`,
-    concurrency,
-    batchSize: positiveInteger(options?.batchSize ?? concurrency, "dispatcher.batchSize"),
-    pollIntervalMs: toTimerMilliseconds(
-      options?.pollInterval ?? DEFAULTS.pollInterval,
-      "dispatcher.pollInterval"
-    ),
-    leaseDurationMs: toTimerMilliseconds(
-      options?.leaseDuration ?? DEFAULTS.leaseDuration,
-      "dispatcher.leaseDuration"
-    ),
-    shutdownTimeoutMs: toTimerMilliseconds(
-      options?.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
-      "dispatcher.shutdownTimeout"
-    )
-  };
-}
-function createRetentionSettings(options) {
-  const completed = options?.completed ?? DEFAULTS.completedRetention;
-  const dead = options?.dead ?? false;
-  return {
-    completedMs: completed === false ? null : toMilliseconds(completed, "retention.completed"),
-    deadMs: dead === false ? null : toMilliseconds(dead, "retention.dead"),
-    intervalMs: toTimerMilliseconds(
-      options?.interval ?? DEFAULTS.retentionInterval,
-      "retention.interval"
-    )
-  };
-}
 
-exports.ConfigurationError = ConfigurationError;
+Object.defineProperty(exports, "AttemptsExhaustedError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.AttemptsExhaustedError; }
+});
+Object.defineProperty(exports, "ConfigurationError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.ConfigurationError; }
+});
+Object.defineProperty(exports, "DispatcherStoppedError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.DispatcherStoppedError; }
+});
+Object.defineProperty(exports, "DrainIncompleteError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.DrainIncompleteError; }
+});
+Object.defineProperty(exports, "EventValidationError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.EventValidationError; }
+});
+Object.defineProperty(exports, "HandlerTimeoutError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.HandlerTimeoutError; }
+});
+Object.defineProperty(exports, "InvalidEnvelopeError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.InvalidEnvelopeError; }
+});
+Object.defineProperty(exports, "LeaseLostError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.LeaseLostError; }
+});
+Object.defineProperty(exports, "LifecycleError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.LifecycleError; }
+});
+Object.defineProperty(exports, "NonRetryableError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.NonRetryableError; }
+});
+Object.defineProperty(exports, "RelayBusError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.RelayBusError; }
+});
+Object.defineProperty(exports, "TransactionRequiredError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.TransactionRequiredError; }
+});
+Object.defineProperty(exports, "TransactionTimeoutError", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.TransactionTimeoutError; }
+});
+Object.defineProperty(exports, "assertEventType", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.assertEventType; }
+});
+Object.defineProperty(exports, "defineEvent", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.defineEvent; }
+});
+Object.defineProperty(exports, "toErrorInfo", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.toErrorInfo; }
+});
+Object.defineProperty(exports, "validatePayload", {
+  enumerable: true,
+  get: function () { return chunk3OHMEMZA_cjs.validatePayload; }
+});
+exports.CatalogPublisher = CatalogPublisher;
 exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
 exports.DEFAULT_ROUTE_RETRY_POLICY = DEFAULT_ROUTE_RETRY_POLICY;
 exports.DELIVERY_STATUSES = DELIVERY_STATUSES;
-exports.DispatcherStoppedError = DispatcherStoppedError;
-exports.EventValidationError = EventValidationError;
-exports.HandlerTimeoutError = HandlerTimeoutError;
 exports.InMemoryEventStore = InMemoryEventStore;
 exports.InMemoryTransaction = InMemoryTransaction;
-exports.InvalidEnvelopeError = InvalidEnvelopeError;
-exports.LeaseLostError = LeaseLostError;
 exports.MAX_TIMER_DELAY_MS = MAX_TIMER_DELAY_MS;
-exports.NonRetryableError = NonRetryableError;
 exports.RelayBus = RelayBus;
-exports.RelayBusError = RelayBusError;
-exports.TransactionRequiredError = TransactionRequiredError;
-exports.assertEventType = assertEventType;
+exports.TRACEPARENT_HEADER = TRACEPARENT_HEADER;
+exports.TRACESTATE_HEADER = TRACESTATE_HEADER;
 exports.computeRetryDelay = computeRetryDelay;
+exports.consume = consume;
 exports.createRetryPolicy = createRetryPolicy;
 exports.createUuidV7 = createUuidV7;
-exports.defineEvent = defineEvent;
+exports.defineCatalog = defineCatalog;
+exports.defineHandlers = defineHandlers;
+exports.describeCatalog = describeCatalog;
 exports.isRetryableError = isRetryableError;
+exports.produce = produce;
 exports.systemClock = systemClock;
-exports.toErrorInfo = toErrorInfo;
 exports.toMilliseconds = toMilliseconds;
-exports.validatePayload = validatePayload;
+exports.traceContextOf = traceContextOf;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map