@relaybus/core 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -1,74 +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";
-  /**
-   * Whether the store said so (a fenced write returned false). A worker that only noticed
-   * locally that its lease ran out may still own the delivery in the store and has to give it back.
-   */
-  storeConfirmed;
-  constructor(message, options = {}) {
-    super(message);
-    this.storeConfirmed = options.storeConfirmed ?? false;
-  }
-};
-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,
@@ -81,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}`
       );
     }
@@ -89,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}'`
     );
   }
@@ -100,56 +41,16 @@ 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`
-    );
-  }
-}
-function defineEvent(type, options) {
-  assertEventType(type);
-  const schema = options?.schema;
-  return class DefinedEvent {
-    constructor(payload) {
-      this.payload = payload;
-    }
-    payload;
-    static type = type;
-    static schema = schema;
-    type = type;
-  };
-}
-async function validatePayload(type, schema, payload) {
-  if (schema === void 0) {
-    return payload;
-  }
-  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
-    );
-  }
-  return result.value;
-}
-
 // src/catalog.ts
 var EVENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var descriptions = /* @__PURE__ */ new WeakMap();
@@ -157,25 +58,25 @@ 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 ConfigurationError(`${label} must contain at least one event`);
+    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 ConfigurationError(
+      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 ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         `${label} entry '${name}' must be an event class created with defineEvent`
       );
     }
-    assertEventType(eventClass.type);
+    chunk3OHMEMZA_cjs.assertEventType(eventClass.type);
     const owner = owners.get(eventClass.type);
     if (owner !== void 0) {
-      throw new ConfigurationError(
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(
         `${label} entries '${owner}' and '${name}' share the event type '${eventClass.type}'`
       );
     }
@@ -189,7 +90,7 @@ function defineCatalog(events, options = {}) {
 function describeCatalog(catalog) {
   const description = descriptions.get(catalog);
   if (description === void 0) {
-    throw new ConfigurationError("Expected a catalog created with defineCatalog");
+    throw new chunk3OHMEMZA_cjs.ConfigurationError("Expected a catalog created with defineCatalog");
   }
   return description;
 }
@@ -204,19 +105,19 @@ function selectCatalogEntries(catalog, events) {
   }
   const label = catalogLabel(catalog);
   if (events.length === 0) {
-    throw new ConfigurationError(
+    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 ConfigurationError(
+      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 ConfigurationError(`Event '${String(event)}' of ${label} is selected twice`);
+      throw new chunk3OHMEMZA_cjs.ConfigurationError(`Event '${String(event)}' of ${label} is selected twice`);
     }
     selected.add(event);
   }
@@ -228,26 +129,29 @@ function capitalize(text) {
 function requireCatalogEntry(catalog, event) {
   const entry = describeCatalog(catalog).entries.find((candidate) => candidate.type === event.type);
   if (entry === void 0) {
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `Event type '${String(event.type)}' is not part of ${catalogLabel(catalog)}`
     );
   }
   return entry;
 }
-function resolveCatalogHandlers(catalog, handlers, options) {
+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 ConfigurationError(
+    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 ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       "Cannot derive handler ids: name the catalog, pass an idPrefix or use a class instance as handlers"
     );
   }
@@ -264,7 +168,7 @@ function classNameOf(handlers) {
   const className = handlers.constructor.name;
   return className === "Object" || className === "" ? void 0 : className;
 }
-function assertExactHandlers(catalog, entries, handlers) {
+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));
@@ -278,13 +182,16 @@ function assertExactHandlers(catalog, entries, handlers) {
       ...extra.map((key) => `unexpected ${key}`),
       ...notFunctions.map((key) => `${key} is not a function`)
     ];
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `Handlers do not match ${catalogLabel(catalog)}: ${problems.join(", ")}`
     );
   }
 }
 function defineHandlers(catalog, handlers, options = {}) {
-  assertExactHandlers(catalog, selectCatalogEntries(catalog, options.events), handlers);
+  assertExactHandlers(catalog, {
+    entries: selectCatalogEntries(catalog, options.events),
+    handlers
+  });
   return handlers;
 }
 
@@ -326,7 +233,7 @@ var CatalogPublisher = class {
   #assertPublishable(event) {
     const { name } = requireCatalogEntry(this.#catalog, event);
     if (!this.#publishes(name)) {
-      throw new ConfigurationError(
+      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(", ")})`
@@ -338,12 +245,12 @@ var CatalogPublisher = class {
 // src/catalog-coverage.ts
 var declarations = /* @__PURE__ */ new WeakSet();
 function consume(catalog, options = {}) {
-  return declare(catalog, "consume", options);
+  return declare(catalog, { role: "consume", options });
 }
 function produce(catalog, options = {}) {
-  return declare(catalog, "produce", options);
+  return declare(catalog, { role: "produce", options });
 }
-function declare(catalog, role, options) {
+function declare(catalog, { role, options }) {
   const entries = selectCatalogEntries(catalog, options.events);
   const declaration = Object.freeze({
     catalog,
@@ -371,7 +278,7 @@ function assertCatalogsCovered(requirements, registrationsOf) {
   let onlyBareCatalogs = true;
   for (const { catalogName, entries, need } of requirements) {
     for (const entry of entries) {
-      const problem = describeGap(entry, need, registrationsOf(entry.type));
+      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";
@@ -380,13 +287,16 @@ function assertCatalogsCovered(requirements, registrationsOf) {
   }
   if (problems.size > 0) {
     const heading = onlyBareCatalogs ? "Catalog events without a handler or route:" : "Catalog events this service does not cover:";
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `${heading}
 ${[...problems].map((line) => `  - ${line}`).join("\n")}`
     );
   }
 }
-function describeGap(entry, need, { handlers, routes }) {
+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}`;
@@ -412,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 = [];
@@ -435,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);
   }
@@ -460,6 +376,9 @@ 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();
@@ -471,7 +390,7 @@ var InMemoryEventStore = class {
   #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"
       );
     }
@@ -489,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,
@@ -513,50 +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.#events.get(eventId)?.handlers.has(delivery.handler) === true) {
-          return false;
-        }
-        pendingDeliveryKeys.add(deliveryKey);
-        return true;
-      });
+      const newDeliveries = this.#newDeliveries(entry, pendingDeliveryKeys);
       appendedDeliveryCount += newDeliveries.length;
       transaction.enqueue(() => {
-        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
-          });
-        }
+        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);
@@ -585,12 +518,14 @@ 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) {
     if (transaction === void 0) {
       return this.#updateLeased(lease, (delivery) => this.#finish(delivery, now));
@@ -609,6 +544,7 @@ var InMemoryEventStore = class {
   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";
@@ -627,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";
@@ -636,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,
@@ -679,12 +618,14 @@ 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 cutoffs = [request.completedBefore, request.deadBefore].filter((cutoff) => cutoff !== void 0).map((cutoff) => cutoff.getTime());
-    const orphanCutoff = cutoffs.length === 0 ? Number.NEGATIVE_INFINITY : Math.min(...cutoffs);
-    const completedCutoff = request.completedBefore?.getTime() ?? Number.NEGATIVE_INFINITY;
+    const { orphanCutoff, completedCutoff } = eventCutoffs(request);
     let deletedEvents = 0;
     for (const [eventId, event] of [...this.#events]) {
       if (referencedEventIds.has(eventId) || this.#locks.has(`event:${eventId}`)) {
@@ -696,7 +637,7 @@ var InMemoryEventStore = class {
         deletedEvents += 1;
       }
     }
-    return { deletedDeliveries, deletedEvents };
+    return deletedEvents;
   }
   async statistics(now) {
     const counts = {
@@ -771,12 +712,7 @@ 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;
       }
     }
@@ -818,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));
 }
@@ -842,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) {
@@ -855,6 +806,276 @@ function isPurgeable(delivery, request) {
   return false;
 }
 
+// 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/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;
+    }
+  }
+  /** 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;
+    }
+  }
+  #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) }
+    });
+  }
+  /** 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 });
+  }
+  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;
+    }
+  }
+  /**
+   * 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
+    });
+  }
+  #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
+    });
+  }
+  #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/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;
+    }
+  }
+  /** 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());
+  }
+  /** 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;
@@ -884,7 +1105,10 @@ var CompletionBatcher = class {
       if (this.#closing || this.#pending.length >= this.#settings.maxBatchSize || this.#pending.length >= this.#runningCount()) {
         this.#flush();
       } else {
-        this.#timer ??= setTimeout(() => this.#flush(), this.#settings.windowMs);
+        this.#timer ??= chunk3OHMEMZA_cjs.schedule(this.#clock, {
+          run: () => this.#flush(),
+          delayMs: this.#settings.windowMs
+        });
       }
     });
   }
@@ -899,7 +1123,7 @@ var CompletionBatcher = class {
     }
   }
   #flush() {
-    clearTimeout(this.#timer);
+    this.#timer?.();
     this.#timer = void 0;
     const batch = this.#pending;
     this.#pending = [];
@@ -914,6 +1138,57 @@ var CompletionBatcher = class {
     );
   }
 };
+
+// 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);
@@ -925,6 +1200,102 @@ 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,
@@ -944,35 +1315,42 @@ var DEFAULT_ROUTE_RETRY_POLICY = {
 };
 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,
+  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: options?.factor ?? base.factor,
-    maxDelayMs: options?.maxDelay === void 0 ? (
+    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(options.maxDelay, "retry.maxDelay"),
-    jitter: options?.jitter ?? base.jitter,
-    retryIf: options?.retryIf ?? base.retryIf
+    ) : 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 ConfigurationError(
+    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 ConfigurationError(`retry.factor must be at least 1, received ${policy.factor}`);
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`retry.factor must be at least 1, received ${policy.factor}`);
   }
   if (policy.maxDelayMs < policy.initialDelayMs) {
-    throw new ConfigurationError("retry.maxDelay must not be smaller than retry.initialDelay");
+    throw new chunk3OHMEMZA_cjs.ConfigurationError("retry.maxDelay must not be smaller than retry.initialDelay");
   }
   if (!JITTER_STRATEGIES.includes(policy.jitter)) {
-    throw new ConfigurationError(
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(
       `retry.jitter must be one of ${JITTER_STRATEGIES.join(", ")}, received '${String(policy.jitter)}'`
     );
   }
-  return policy;
 }
 function computeRetryDelay(policy, failedAttempts, random = Math.random) {
   const exponential = policy.initialDelayMs * policy.factor ** (failedAttempts - 1);
@@ -987,7 +1365,7 @@ function computeRetryDelay(policy, failedAttempts, random = Math.random) {
   }
 }
 function isRetryableError(policy, error) {
-  if (error instanceof NonRetryableError) {
+  if (error instanceof chunk3OHMEMZA_cjs.NonRetryableError) {
     return false;
   }
   if (policy.retryIf === void 0) {
@@ -1001,11 +1379,17 @@ function isRetryableError(policy, error) {
 }
 
 // src/dispatcher.ts
-var COMPLETION_RETRY_DELAYS_MS = [50, 250, 1e3];
+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 defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 var Dispatcher = class {
   #dependencies;
   #sleep;
@@ -1031,9 +1415,15 @@ var Dispatcher = class {
   #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.#sleep = dependencies.sleep ?? defaultSleep;
+    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
@@ -1082,10 +1472,13 @@ var Dispatcher = class {
       this.#requestClaim();
       return;
     }
-    this.#cooldownTimer ??= setTimeout(() => {
-      this.#cooldownTimer = void 0;
-      this.#requestClaim();
-    }, wait);
+    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) {
@@ -1124,33 +1517,66 @@ var Dispatcher = class {
     }
   }
   /**
-   * Stops claiming, waits up to the shutdown timeout for running handlers,
-   * then aborts the rest and releases their deliveries for another process.
+   * 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() {
+  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) {
-      await this.#closeRecovery(Date.now() + this.#dependencies.settings.shutdownTimeoutMs);
-      return;
+      await this.#closeRecovery(deadline);
+      return 0;
     }
     this.#running = false;
     this.#completions?.setClosing(true);
-    clearTimeout(this.#cooldownTimer);
+    this.#cooldownTimer?.();
     this.#cooldownTimer = void 0;
-    clearTimeout(this.#quietRefillTimer);
+    this.#quietRefillTimer?.();
     this.#quietRefillTimer = void 0;
     this.#signal(this.#refillThreshold);
-    const deadline = Date.now() + this.#dependencies.settings.shutdownTimeoutMs;
-    await this.#waitUntil(this.#stopWatching(), deadline);
-    await this.#waitUntil(this.#loop, deadline);
+    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 settled;
     }
     await this.#closeRecovery(deadline);
-    await this.#waitUntil(this.#relinquish(), 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
@@ -1158,13 +1584,13 @@ var Dispatcher = class {
    * further call, since it may be closed right after.
    */
   async #closeRecovery(deadline) {
-    clearInterval(this.#recoveryTimer);
+    this.#recoveryTimer?.();
     this.#recoveryTimer = void 0;
     const lastTry = (async () => {
       await this.#recovery;
       await this.#recoverSettlements();
     })();
-    await this.#waitUntil(lastTry, deadline);
+    await deadline.race(lastTry);
     this.#pending.clear();
   }
   /**
@@ -1195,12 +1621,16 @@ var Dispatcher = class {
     }
   }
   #retain(entry) {
+    if (this.#abandoned) {
+      return;
+    }
     this.#pending.set(pendingKey(entry.delivery), entry);
-    this.#recoveryTimer ??= setInterval(
-      () => void this.#recoverSettlements(),
-      this.#dependencies.settings.pollIntervalMs
-    );
-    this.#recoveryTimer.unref();
+    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() {
@@ -1218,12 +1648,15 @@ var Dispatcher = class {
     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;
   }
   /**
@@ -1257,12 +1690,15 @@ var Dispatcher = class {
   async #waitForWakeUp() {
     if (this.#signalledMinimum === void 0) {
       await new Promise((resolve) => {
-        const timer = setTimeout(() => {
-          this.#signalledMinimum = 1;
-          resolve();
-        }, this.#dependencies.settings.pollIntervalMs);
+        const cancel = chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+          run: () => {
+            this.#signalledMinimum = 1;
+            resolve();
+          },
+          delayMs: this.#dependencies.settings.pollIntervalMs
+        });
         this.#wakeUp = () => {
-          clearTimeout(timer);
+          cancel();
           resolve();
         };
       });
@@ -1298,13 +1734,13 @@ var Dispatcher = class {
         });
       }
     } else if (free > 0) {
-      this.#quietRefillTimer ??= setTimeout(
-        () => {
+      this.#quietRefillTimer ??= chunk3OHMEMZA_cjs.schedule(this.#dependencies.clock, {
+        run: () => {
           this.#quietRefillTimer = void 0;
           this.#signal(1);
         },
-        Math.max(0, this.#lastClaimStartedAt + QUIET_REFILL_MS - Date.now())
-      );
+        delayMs: Math.max(0, this.#lastClaimStartedAt + QUIET_REFILL_MS - Date.now())
+      });
     }
   }
   #freeSlots() {
@@ -1312,23 +1748,24 @@ var Dispatcher = class {
   }
   /** 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 wakeGeneration = this.#wakeGeneration;
       this.#lastClaimStartedAt = Date.now();
-      clearTimeout(this.#quietRefillTimer);
+      this.#quietRefillTimer?.();
       this.#quietRefillTimer = void 0;
       requested += request.limit;
-      const claimed = await store.claim({
+      const claim = {
         handlers: request.handlers,
         limit: request.limit,
         leaseOwner: settings.owner,
         leaseExpiresAt: new Date(now.getTime() + settings.leaseDurationMs),
         now
-      });
+      };
+      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);
@@ -1336,7 +1773,7 @@ var Dispatcher = class {
           this.#exhaustedHandlers.delete(handler);
         }
       }
-      for (const delivery of claimed) {
+      for (const delivery of this.#abandoned ? [] : claimed) {
         started.push(this.#start(delivery));
       }
     }
@@ -1351,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;
       }
     }
@@ -1402,7 +1842,7 @@ var Dispatcher = class {
     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`
         )
       );
@@ -1410,8 +1850,9 @@ var Dispatcher = class {
     }
     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", { delivery, durationMs });
@@ -1424,24 +1865,31 @@ var Dispatcher = class {
       }
       return true;
     } catch (error) {
-      if (error instanceof LeaseLostError) {
+      if (this.#abandoned) {
+        return false;
+      }
+      if (error instanceof chunk3OHMEMZA_cjs.LeaseLostError) {
         notifier.notify("onLeaseLost", { delivery });
         if (!error.storeConfirmed) {
-          await this.#giveBack(registration, delivery, error);
+          await this.#giveBack(registration, { delivery, error });
         }
-      } else if (error instanceof DispatcherStoppedError) {
+      } 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
@@ -1449,16 +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);
   }
   /**
@@ -1468,6 +1916,9 @@ var Dispatcher = class {
   async #confirmCompletion(delivery) {
     const { notifier } = this.#dependencies;
     for (let attempt = 0; ; attempt += 1) {
+      if (this.#abandoned) {
+        return "unconfirmed";
+      }
       let completed;
       try {
         completed = await this.#complete(delivery);
@@ -1481,7 +1932,7 @@ 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
         });
       }
@@ -1493,7 +1944,8 @@ var Dispatcher = class {
     const { store, clock } = this.#dependencies;
     return this.#completions === void 0 ? store.complete(delivery, clock.now()) : this.#completions.submit(delivery);
   }
-  async #invoke(registration, event, delivery, controller, transaction) {
+  async #invoke(input) {
+    const { registration, event, delivery, controller, transaction } = input;
     const context = {
       deliveryId: delivery.deliveryId,
       handler: delivery.handler,
@@ -1506,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?.();
     }
   }
   /**
@@ -1537,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
@@ -1546,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;
@@ -1559,81 +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`));
+    return chunk3OHMEMZA_cjs.schedule(clock, {
+      run: () => {
+        controller.abort(new chunk3OHMEMZA_cjs.LeaseLostError(`Lease on delivery ${delivery.deliveryId} expired`));
       },
-      Math.max(0, expiry - clock.now().getTime())
-    );
-    timer.unref();
-    return () => clearTimeout(timer);
+      delayMs: Math.max(0, expiry - clock.now().getTime()),
+      unref: true
+    });
   }
-  /**
-   * 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 = (storeConfirmed = false) => {
-      controller.abort(
-        new LeaseLostError(`Lease on delivery ${delivery.deliveryId} was lost`, { storeConfirmed })
-      );
-    };
-    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(true);
-          }
-        }).catch((error) => notifier.failure("extend-lease", error)).finally(() => {
-          renewing = false;
-        });
-      },
-      Math.max(1, Math.floor(settings.leaseDurationMs / 3))
-    );
-    timer.unref();
-    return () => clearInterval(timer);
-  }
-  async #fail(registration, delivery, error) {
+  async #fail(registration, { delivery, error }) {
     const policy = registration.retry;
     if (delivery.attempt >= policy.attempts || !isRetryableError(policy, error)) {
       await this.#bury(delivery, error);
       return;
     }
-    await this.#reschedule(registration, delivery, error);
+    await this.#reschedule(registration, { delivery, error });
   }
   /** Schedules the next attempt with the retry policy's backoff. */
-  async #reschedule(registration, delivery, error) {
+  async #reschedule(registration, { delivery, error }) {
     const { store, clock, random, notifier } = this.#dependencies;
     const policy = registration.retry;
-    const errorInfo = toErrorInfo(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     const now = clock.now();
     const availableAt = new Date(
       now.getTime() + computeRetryDelay(policy, delivery.attempt, random)
@@ -1658,7 +2080,7 @@ 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());
@@ -1685,11 +2107,11 @@ var Dispatcher = class {
    * 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) {
+  async #giveBack(registration, { delivery, error }) {
     if (delivery.attempt >= registration.retry.attempts) {
       await this.#bury(delivery, error);
     } else {
-      await this.#reschedule(registration, delivery, error);
+      await this.#reschedule(registration, { delivery, error });
     }
   }
   async #release(delivery) {
@@ -1713,54 +2135,64 @@ var Dispatcher = class {
     }
   }
 };
-function pendingKey(delivery) {
-  return `${delivery.deliveryId}\0${delivery.leaseToken}`;
-}
-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) ?? [];
@@ -1769,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;
   }
@@ -1783,9 +2215,18 @@ function resolveTimeout(timeout, fallback, handlerId) {
 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) {
@@ -1800,7 +2241,7 @@ var Notifier = class {
     }
   }
   failure(stage, error) {
-    const errorInfo = toErrorInfo(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     this.#logger.error(
       `[Notifier](failure) relaybus ${stage} failed | ${errorInfo.name}: ${errorInfo.message}`
     );
@@ -1814,7 +2255,7 @@ var Notifier = class {
   }
   #reportObserverFailure(failedObserver, error) {
     this.#logObserverFailure(error);
-    const errorInfo = toErrorInfo(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     for (const observer of this.#observers) {
       if (observer === failedObserver) {
         continue;
@@ -1827,14 +2268,60 @@ var Notifier = class {
     }
   }
   #logObserverFailure(error) {
-    const errorInfo = toErrorInfo(error);
+    const errorInfo = chunk3OHMEMZA_cjs.toErrorInfo(error);
     this.#logger.warn(
-      `[Notifier](notify) relaybus observer threw | ${errorInfo.name}: ${errorInfo.message}`
+      `[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/relay-bus.ts
+// 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",
@@ -1844,14 +2331,195 @@ var DEFAULTS = {
   completionBatchSize: 200,
   completedRetention: "7d",
   retentionInterval: "1h",
-  routeTimeoutMs: 3e4
+  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 });
+    }
+  }
+  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`
+    );
+  }
+  if (group.eventTypes.includes(type)) {
+    throw new chunk3OHMEMZA_cjs.ConfigurationError(`Event type ${type} is routed to ${target} twice`);
+  }
+  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 DEFAULT_DRAIN_BATCHES = 1e3;
 var WAKE_DELAY_MS = 25;
 var RelayBus = class {
   #store;
   #source;
   #transactionMode;
+  #transactionTimeoutMs;
   #transactionResolver;
   #unroutedEvents;
   #registry = new HandlerRegistry();
@@ -1868,61 +2536,79 @@ var RelayBus = class {
   #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`);
       }
     }
     for (const catalog of options.catalogs ?? []) {
       this.registerCatalog(catalog);
     }
-    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)
-    });
   }
   get store() {
     return this.#store;
@@ -1942,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,
@@ -1955,8 +2642,9 @@ 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)) {
+    for (const binding of resolveCatalogHandlers(catalog, { handlers, options })) {
       this.subscribe(binding.eventClass, binding.handle, binding.options);
     }
   }
@@ -1979,7 +2667,9 @@ var RelayBus = class {
   }
   /** 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
@@ -1987,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.
@@ -2009,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) {
@@ -2038,7 +2745,7 @@ 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}`
       );
     }
@@ -2052,25 +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 === "idle") {
-      await this.#dispatcher.stop();
-      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}`
+      );
     }
-    if (this.#state !== "running") {
-      return;
+    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.
@@ -2083,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();
@@ -2092,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);
@@ -2134,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 [];
     }
@@ -2176,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) {
@@ -2192,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"
       );
     }
@@ -2230,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,
@@ -2263,17 +3098,26 @@ var RelayBus = class {
     const routes = registrations.filter((registration) => registration.forwardsToTransport).length;
     return { handlers: registrations.length - routes, routes };
   }
-  #registerRoute(route) {
-    const transport = this.#requireTransport(route.transport);
-    const { type } = describeEvent(route.event);
-    const destination = route.destination ?? type;
+  #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 }
         },
@@ -2285,7 +3129,7 @@ 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;
   }
@@ -2293,24 +3137,30 @@ var RelayBus = class {
     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,
@@ -2320,136 +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"
-    ),
-    completionBatchWindowMs: toMilliseconds(
-      options?.completionBatchWindow ?? DEFAULTS.completionBatchWindow,
-      "dispatcher.completionBatchWindow"
-    ),
-    completionBatchSize: positiveInteger(
-      options?.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"
-    )
-  };
-}
 
+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.ConfigurationError = ConfigurationError;
 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.defineCatalog = defineCatalog;
-exports.defineEvent = defineEvent;
 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