@relaybus/core 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,114 +1,5 @@
-/** Source of the current time. Replace it in tests to control retries and leases. */
-interface Clock {
-    now(): Date;
-}
-declare const systemClock: Clock;
-
-/**
- * A duration in milliseconds, or a string such as `'250ms'`, `'30s'`, `'5m'`,
- * `'1h'` or `'7d'`.
- */
-type Duration = number | `${number}${DurationUnit}`;
-type DurationUnit = 'ms' | 's' | 'm' | 'h' | 'd';
-declare function toMilliseconds(value: Duration, name: string): number;
-/** Largest delay Node.js timers support. Longer values fire after 1ms instead. */
-declare const MAX_TIMER_DELAY_MS = 2147483647;
-
-/**
- * The Standard Schema interface (https://standardschema.dev), copied as the
- * specification recommends so relaybus needs no runtime dependency. Zod,
- * Valibot, ArkType and other libraries implement it.
- */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-    interface Props<Input = unknown, Output = Input> {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    type Result<Output> = SuccessResult<Output> | FailureResult;
-    interface SuccessResult<Output> {
-        readonly value: Output;
-        readonly issues?: undefined;
-    }
-    interface FailureResult {
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    interface Issue {
-        readonly message: string;
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    interface PathSegment {
-        readonly key: PropertyKey;
-    }
-    interface Types<Input = unknown, Output = Input> {
-        readonly input: Input;
-        readonly output: Output;
-    }
-    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
-    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
-}
-
-/** String metadata carried with an event, such as `traceparent`. */
-type EventHeaders = Readonly<Record<string, string>>;
-/**
- * An event as stored and delivered. Field names follow CloudEvents where they
- * overlap (`id`, `type`, `source`, `time` as `occurredAt`, `subject` as `key`).
- */
-interface EventEnvelope<TPayload = unknown> {
-    /** Globally unique id. Handlers and transports deduplicate on it. */
-    readonly id: string;
-    /** Event type, for example `order.created.v1`. */
-    readonly type: string;
-    /** Logical name of the publishing service. */
-    readonly source: string;
-    /** Ordering and partition key. Events sharing a key are handled in publish order. */
-    readonly key: string | null;
-    readonly payload: TPayload;
-    readonly headers: EventHeaders;
-    /** Id shared by every event of one business flow. */
-    readonly correlationId: string | null;
-    /** Id of the event whose handler published this one. */
-    readonly causationId: string | null;
-    readonly occurredAt: Date;
-}
-/** An instance of a class created with {@link defineEvent}. */
-interface DomainEvent<TPayload = unknown> {
-    readonly type: string;
-    readonly payload: TPayload;
-}
-/** A class created with {@link defineEvent}. */
-interface EventClass<TPayload = unknown> {
-    new (payload: TPayload): DomainEvent<TPayload>;
-    readonly type: string;
-    readonly schema: StandardSchemaV1<unknown, TPayload> | undefined;
-}
-/** Payload type of an event class: `PayloadOf<typeof OrderPlaced>`. */
-type PayloadOf<TEvent> = TEvent extends EventClass<infer TPayload> ? TPayload : never;
-/** Anything that names an event type: an event class or the type string itself. */
-type EventReference = {
-    readonly type: string;
-} | string;
-interface DefineEventOptions<TSchema extends StandardSchemaV1> {
-    /** Validates the payload on publish and before every handler call. */
-    readonly schema: TSchema;
-}
-declare function assertEventType(type: string): void;
-/**
- * Defines an event type. Extend the returned class to name it:
- *
- * ```ts
- * export class OrderPlaced extends defineEvent<{ orderId: string }>('order.placed.v1') {}
- * export class OrderShipped extends defineEvent('order.shipped.v1', { schema: orderShippedSchema }) {}
- * ```
- */
-declare function defineEvent<TSchema extends StandardSchemaV1>(type: string, options: DefineEventOptions<TSchema>): EventClass<StandardSchemaV1.InferOutput<TSchema>>;
-declare function defineEvent<TPayload>(type: string): EventClass<TPayload>;
-/** Runs a Standard Schema and returns its output, or throws {@link EventValidationError}. */
-declare function validatePayload<TPayload>(type: string, schema: StandardSchemaV1<unknown, TPayload> | undefined, payload: unknown): Promise<TPayload>;
+import { D as Duration, E as EventEnvelope, a as DomainEvent, S as StandardSchemaV1, P as PayloadOf, C as ClaimedDelivery, b as EventHeaders, c as EventStoreStatistics, d as ErrorInfo, e as PurgeResult, f as EventStore, T as Transport, g as EventReference, h as Clock, A as AppendEntry, i as AppendResult, j as ClaimRequest, L as LeaseReference, k as DeliveryQuery, l as DeliveryRecord, m as PurgeRequest, n as EventClass } from './transport-BlfzIBZD.js';
+export { o as AttemptsExhaustedError, p as CloseOptions, q as ConfigurationError, r as DELIVERY_STATUSES, s as DefineEventKeyOptions, t as DefineEventOptions, u as DeliveryStatus, v as DispatcherStoppedError, w as DrainIncompleteError, x as EventKeyFunction, y as EventStoreTransactionOptions, z as EventValidationError, H as HandlerTimeoutError, I as InvalidEnvelopeError, B as InvalidTransportMessage, F as LeaseLostError, G as LifecycleError, M as MAX_TIMER_DELAY_MS, N as NewDelivery, J as NonRetryableError, R as RelayBusError, K as TransactionRequiredError, O as TransactionTimeoutError, Q as TransportMessage, U as TransportMessageHandler, V as TransportSubscriptionHooks, W as ValidationIssue, X as assertEventType, Y as defineEvent, Z as systemClock, _ as toErrorInfo, $ as toMilliseconds, a0 as validatePayload } from './transport-BlfzIBZD.js';
 
 /**
  * How the delay between attempts is randomized.
@@ -430,7 +321,7 @@ interface CatalogDeclaration<TCatalog extends Catalog = Catalog, TName extends k
  * Declares that this service consumes events of a catalog, typically one
  * shared between services through a contracts package. `start()` fails unless
  * every declared event has a local handler (`subscribeCatalog`, `subscribe`,
- * `@EventConsumer`, `@Subscribe`); a route to a transport does not count.
+ * `@RelayBusCatalogConsumer`, `@RelayBusConsumer`); a route to a transport does not count.
  * Without `events`, every event of the catalog is declared. Unknown names do
  * not compile and are rejected at runtime with a {@link ConfigurationError}.
  *
@@ -458,269 +349,175 @@ declare function consume<TCatalog extends Catalog, const TName extends keyof TCa
 declare function produce<TCatalog extends Catalog, const TName extends keyof TCatalog = keyof TCatalog>(catalog: TCatalog, options?: CatalogEventSelection<TName>): CatalogDeclaration<TCatalog, TName>;
 
 /**
- * Base class of every error thrown by relaybus.
- */
-declare class RelayBusError extends Error {
-    name: string;
-}
-/** Invalid options passed to a relaybus component. */
-declare class ConfigurationError extends RelayBusError {
-    name: string;
-}
-/**
- * Thrown by `publish` when no transaction can be found and the bus runs with
- * `transactionMode: 'required'` (the default). Publishing outside a transaction
- * would reintroduce the dual-write problem the outbox exists to prevent.
- */
-declare class TransactionRequiredError extends RelayBusError {
-    name: string;
-}
-/**
- * Throw from a handler to dead-letter the delivery immediately, skipping the
- * remaining retry attempts.
- */
-declare class NonRetryableError extends RelayBusError {
-    name: string;
-}
-/** A payload failed its event schema. Never retried: the payload will not change. */
-declare class EventValidationError extends NonRetryableError {
-    readonly issues: readonly ValidationIssue[];
-    name: string;
-    constructor(message: string, issues: readonly ValidationIssue[]);
-}
-/**
- * A message received from a broker is not a valid event. Never retried:
- * transports should dead-letter it instead of redelivering it forever.
- */
-declare class InvalidEnvelopeError extends NonRetryableError {
-    name: string;
-}
-/** The worker no longer owns the delivery it was processing. */
-declare class LeaseLostError extends RelayBusError {
-    name: string;
-    /**
-     * 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.
-     */
-    readonly storeConfirmed: boolean;
-    constructor(message: string, options?: {
-        readonly storeConfirmed?: boolean;
-    });
-}
-/** A handler did not settle within its configured timeout. Retried like any failure. */
-declare class HandlerTimeoutError extends RelayBusError {
-    name: string;
-}
-/**
- * Reason of a handler's abort signal when the bus stops before the handler
- * finished. The delivery is released and runs again without losing an attempt.
+ * RFC 9562 UUID version 7: 48-bit Unix millisecond timestamp followed by random
+ * bits. Time-ordered, so it keeps B-tree indexes compact, and globally unique,
+ * so it is safe as an idempotency key across services.
  */
-declare class DispatcherStoppedError extends RelayBusError {
-    name: string;
-}
-interface ValidationIssue {
-    readonly message: string;
-    readonly path?: readonly PropertyKey[] | undefined;
-}
-/** Serializable snapshot of an error, stored with failed deliveries. */
-interface ErrorInfo {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string | undefined;
-}
-declare function toErrorInfo(error: unknown): ErrorInfo;
+declare function createUuidV7(timestamp?: number): string;
+/** Produces unique identifiers for events, deliveries and lease tokens. */
+type IdentifierGenerator = () => string;
 
-/**
- * Lifecycle of one handler's delivery of one event.
- * `pending` (waiting or scheduled for retry) -> `processing` (leased by a worker)
- * -> `completed` | `pending` (retry) | `dead` (exhausted or non-retryable).
- * `dead` -> `pending` only through an explicit requeue.
- *
- * A completed delivery is deleted. `completed` records exist only in stores
- * configured to keep a completion history (`retainCompleted` /
- * `completionHistory`), where they are listed, counted and purged like before.
- */
-type DeliveryStatus = 'pending' | 'processing' | 'completed' | 'dead';
-declare const DELIVERY_STATUSES: readonly DeliveryStatus[];
-interface NewDelivery {
-    readonly id: string;
-    /** Stable handler id. Together with the event id it is unique. */
-    readonly handler: string;
-    readonly availableAt: Date;
-}
-interface AppendEntry {
-    readonly event: EventEnvelope;
-    readonly deliveries: readonly NewDelivery[];
-}
-interface AppendResult {
-    /** Events written by this call. */
-    readonly appendedEventIds: readonly string[];
-    /** Events that already existed. Their missing deliveries were still added. */
-    readonly duplicateEventIds: readonly string[];
-    /** Deliveries written by this call. Existing (event, handler) pairs are skipped. */
-    readonly appendedDeliveryCount: number;
-}
-/**
- * Lease expiry is compared with the `now` the caller passes, taken from the
- * bus clock. Keep worker clocks synchronized (NTP): a skew larger than a third
- * of the lease duration lets another worker reclaim a delivery that is still running.
+/** Event header that carries the W3C trace context (`version-traceid-parentid-flags`). */
+declare const TRACEPARENT_HEADER = "traceparent";
+/** Event header that carries the vendor part of the W3C trace context. */
+declare const TRACESTATE_HEADER = "tracestate";
+/** A W3C Trace Context as it travels in event headers. */
+interface TraceContext {
+    readonly traceparent: string;
+    readonly tracestate?: string;
+}
+/**
+ * The W3C trace context an event carries in its headers, or undefined when it has none or a
+ * malformed one. A handler or a consumer span continues the publisher's trace from it.
  *
- * Stores may grant the lease on a group of deliveries (a lane) instead of on
- * each delivery. The group is exclusive to `leaseOwner` while the lease is
- * live, so other owners do not see its pending deliveries until it expires or
- * is relinquished; every delivery of the group carries the group's fencing token.
- */
-interface ClaimRequest {
-    /** Only deliveries of these handlers are claimed. */
-    readonly handlers: readonly string[];
-    readonly limit: number;
-    readonly leaseOwner: string;
-    readonly leaseExpiresAt: Date;
-    readonly now: Date;
-}
-/**
- * Proof of ownership. Every state change after a claim must present it
- * (fencing). A lease stays valid until another claim replaces it, even after
- * its expiry time; expiry only makes the delivery claimable again.
+ * ```ts
+ * bus.subscribe(OrderPlaced, (event) => startSpan({ parent: traceContextOf(event.headers) }), ...)
+ * ```
  */
-interface LeaseReference {
-    readonly deliveryId: string;
-    readonly leaseToken: string;
-}
-interface ClaimedDelivery extends LeaseReference {
-    readonly handler: string;
-    /** Attempt number of this claim, starting at 1. */
-    readonly attempt: number;
-    readonly leaseExpiresAt: Date;
-    readonly event: EventEnvelope;
-}
-interface DeliveryRecord {
-    readonly id: string;
-    readonly handler: string;
-    readonly status: DeliveryStatus;
-    readonly attempts: number;
-    readonly availableAt: Date;
-    readonly leaseOwner: string | null;
-    readonly leaseExpiresAt: Date | null;
-    readonly lastError: ErrorInfo | null;
-    readonly createdAt: Date;
-    readonly updatedAt: Date;
-    readonly completedAt: Date | null;
-    readonly event: EventEnvelope;
-}
-interface DeliveryQuery {
-    readonly status?: DeliveryStatus;
-    readonly handler?: string;
-    readonly eventType?: string;
-    readonly eventId?: string;
-    /** Default 100. */
-    readonly limit?: number;
-}
-interface PurgeRequest {
-    /** Delete completed deliveries completed before this instant. */
-    readonly completedBefore?: Date;
-    /** Delete dead deliveries last updated before this instant. */
-    readonly deadBefore?: Date;
+declare function traceContextOf(headers: EventHeaders): TraceContext | undefined;
+/** A `publish` or `publishAll` call. */
+interface PublishTraceInput {
+    /** The type of every event of the call, in order. */
+    readonly eventTypes: readonly string[];
 }
-interface PurgeResult {
-    readonly deletedDeliveries: number;
-    /** Events deleted because no delivery referenced them any more. */
-    readonly deletedEvents: number;
+/** A route sending one event to its transport. */
+interface SendTraceInput {
+    readonly envelope: EventEnvelope;
+    readonly transport: string;
+    /** The messaging system of the transport (`kafka`, `rabbitmq`), else its name. */
+    readonly system: string;
+    readonly destination: string;
 }
-interface EventStoreStatistics {
-    readonly pending: number;
-    readonly processing: number;
-    readonly completed: number;
-    readonly dead: number;
-    /** `availableAt` of the oldest delivery that is due but not yet processed. */
-    readonly oldestDueAt: Date | null;
+/** A local handler running for one claimed delivery. */
+interface ProcessTraceInput {
+    readonly delivery: ClaimedDelivery;
 }
 /**
- * Storage port. Implementations persist events and deliveries in the same
- * database as the application's business data so that both commit atomically.
- *
- * Every implementation must pass the contract suite in `@relaybus/testing`.
+ * Tracing hooks, for example from `@relaybus/otel`. Each one wraps an operation: it starts a span,
+ * calls `run` inside it and ends the span when the returned promise settles, passing its result or
+ * error through unchanged. relaybus itself depends on no tracing library.
  */
-interface EventStore<TTransaction = unknown> {
-    /** Creates tables, collections and indexes when they do not exist. */
-    setup?(): Promise<void>;
-    /** Runs `work` inside a new database transaction and commits when it resolves. */
-    transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
-    /**
-     * Writes events and their deliveries inside `transaction`. Idempotent on
-     * event id and on (event id, handler). Assigns a per-key sequence to keyed
-     * events in commit order.
-     */
-    append(transaction: TTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
-    /**
-     * Leases up to `limit` deliveries that are due: pending with `availableAt <= now`,
-     * or processing with an expired lease. A keyed delivery is only claimable when
-     * no earlier delivery of the same handler and key is pending or processing.
-     * Counts the attempt (`attempt` of the result; a store may persist the count
-     * only when the attempt fails or its lease is lost). Safe to call from many
-     * processes at once.
-     */
-    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    /** Extends a lease the caller still holds. Returns false when the lease was lost. */
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
-    /**
-     * Marks a leased delivery completed by deleting it (or moving it to the
-     * completion history, when the store keeps one). With `transaction` the change
-     * commits together with the handler's own writes. Returns false when the lease
-     * was lost.
-     */
-    complete(lease: LeaseReference, now: Date, transaction?: TTransaction): Promise<boolean>;
-    /** Returns a leased delivery to pending, due at `availableAt`. */
-    reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
-    /**
-     * Gives a leased delivery back without counting the attempt: pending, due
-     * now, attempts decremented. Used when a handler is aborted at shutdown.
-     */
-    release(lease: LeaseReference, now: Date): Promise<boolean>;
+interface RelayBusTracer {
     /**
-     * Marks many leased deliveries completed with one round trip. Returns, for
-     * every lease in the same order, whether it was completed (false: lease lost
-     * or already finished). Each lease is fenced individually, exactly as in
-     * {@link EventStore.complete}. Optional: the dispatcher falls back to
-     * `complete` when a store does not implement it.
+     * Wraps one publish call. `run` takes the trace headers (`traceparent`, `tracestate`) to write
+     * into every event of the call, so its consumers continue the trace; headers passed to
+     * `publish` explicitly win.
      */
-    completeMany?(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
-    /** Moves a leased delivery to dead. */
-    bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
-    listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
-    /** Moves dead deliveries back to pending with a fresh attempt budget. Returns how many moved. */
-    requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
-    purge(request: PurgeRequest): Promise<PurgeResult>;
-    statistics(now: Date): Promise<EventStoreStatistics>;
+    publish?<T>(input: PublishTraceInput, run: (headers: EventHeaders) => Promise<T>): Promise<T>;
     /**
-     * Hands back every lease group that `leaseOwner` holds without running work,
-     * so other workers can take them at once instead of after lease expiry.
-     * Called at graceful shutdown after the owner's deliveries settled. Groups
-     * with running deliveries stay leased. Optional.
+     * Wraps one send of a route. `run` takes the trace headers to send the event with, in place of
+     * the ones it was stored with, so the consumer's trace continues from this send.
      */
-    relinquish?(leaseOwner: string, now: Date): Promise<void>;
+    send?<T>(input: SendTraceInput, run: (headers: EventHeaders) => Promise<T>): Promise<T>;
     /**
-     * Calls `listener` soon after a transaction that added deliveries due at once has committed, in this
-     * process or in any other one, so an idle dispatcher claims them without waiting for its next poll.
-     * A hint, never a guarantee: a report may be late, merged with others, or lost (while a connection
-     * is re-established, for instance), and polling still finds every delivery. Resolves with a function
-     * that stops listening, or with `undefined` when this store cannot listen. Optional.
+     * Wraps one run of a local handler; the handler runs inside `run`, so what it publishes or calls
+     * joins the span. The event's own trace context is in `traceContextOf(delivery.event.headers)`.
      */
-    watchNewDeliveries?(listener: () => void): Promise<(() => Promise<void>) | undefined>;
-    /** Releases connections the store opened itself. */
-    close?(): Promise<void>;
+    process?<T>(input: ProcessTraceInput, run: () => Promise<T>): Promise<T>;
 }
 
-/**
- * RFC 9562 UUID version 7: 48-bit Unix millisecond timestamp followed by random
- * bits. Time-ordered, so it keeps B-tree indexes compact, and globally unique,
- * so it is safe as an idempotency key across services.
- */
-declare function createUuidV7(timestamp?: number): string;
-/** Produces unique identifiers for events, deliveries and lease tokens. */
-type IdentifierGenerator = () => string;
-
-type FailureStage = 'claim' | 'dispatch' | 'complete' | 'reschedule' | 'bury' | 'release' | 'relinquish' | 'extend-lease' | 'purge' | 'watch' | 'observer';
+type FailureStage = 'claim' | 'dispatch' | 'complete' | 'reschedule' | 'bury' | 'release' | 'relinquish' | 'extend-lease' | 'purge' | 'watch' | 'backlog' | 'observer';
+/** How a timed operation ended. On `error` the event carries the error. */
+type OperationOutcome = 'success' | 'error';
+/** Whether a delivery runs a local handler or forwards its event to a transport (a route). */
+type DeliveryKind = 'handler' | 'route';
+/** A `publish` or `publishAll` call returned or threw. */
+interface PublishFinishedEvent {
+    /** The type of every event of the call, in order. */
+    readonly eventTypes: readonly string[];
+    readonly durationMs: number;
+    readonly outcome: OperationOutcome;
+    readonly error?: ErrorInfo;
+}
+/** One claim query of the dispatcher answered or failed. */
+interface ClaimFinishedEvent {
+    /** Handler ids the claim asked for. */
+    readonly handlers: readonly string[];
+    /** Most deliveries the claim asked for (the batch size of this query). */
+    readonly requested: number;
+    readonly claimed: number;
+    /** Distinct leases among the claimed deliveries: a store that leases lanes counts each lane once. */
+    readonly lanes: number;
+    readonly durationMs: number;
+    readonly outcome: OperationOutcome;
+    readonly error?: ErrorInfo;
+}
+/** A handler (or a route's send) is about to run for a claimed delivery. */
+interface HandlerStartedEvent {
+    readonly delivery: ClaimedDelivery;
+    readonly kind: DeliveryKind;
+    /** From the event's `occurredAt` to this start, across services for a received event. */
+    readonly endToEndLatencyMs: number;
+}
+/**
+ * A handler run ended: it resolved (`success`) or threw, timed out, lost its lease or was
+ * stopped (`error`). What happens to the delivery next is reported by the delivery hooks.
+ */
+interface HandlerFinishedEvent {
+    readonly delivery: ClaimedDelivery;
+    readonly kind: DeliveryKind;
+    readonly durationMs: number;
+    readonly outcome: OperationOutcome;
+    readonly error?: ErrorInfo;
+}
+/** A route handed an event to its transport, which acknowledged it or failed. */
+interface TransportSentEvent {
+    readonly envelope: EventEnvelope;
+    /** Name of the transport. */
+    readonly transport: string;
+    /** The messaging system of the transport (`kafka`, `rabbitmq`), else its name. */
+    readonly system: string;
+    readonly destination: string;
+    readonly durationMs: number;
+    readonly outcome: OperationOutcome;
+    readonly error?: ErrorInfo;
+}
+/**
+ * What `receive` did with an event from a broker: stored it (`accepted`), found it stored already
+ * (`duplicate`), had no handler for it (`ignored`), rejected it as malformed (`invalid`) or failed
+ * (`error`, the broker redelivers it).
+ */
+type ReceiveOutcome = 'accepted' | 'duplicate' | 'ignored' | 'invalid' | 'error';
+/** One event from a broker went through `receive`. */
+interface ReceiveFinishedEvent {
+    /** Name of the transport that delivered it; undefined when `bus.receive` was called directly. */
+    readonly transport: string | undefined;
+    /** Messaging system of that transport (`kafka`, `rabbitmq`), else its name. */
+    readonly system: string | undefined;
+    /** Topic, routing key or queue it arrived on, when the transport tells. */
+    readonly destination: string | undefined;
+    /** The event's type and source as received; undefined when missing or not text. */
+    readonly eventType: string | undefined;
+    readonly source: string | undefined;
+    /** W3C trace context the event carries, to continue the trace of its publisher. */
+    readonly traceContext: TraceContext | undefined;
+    readonly outcome: ReceiveOutcome;
+    readonly durationMs: number;
+    readonly error?: ErrorInfo;
+}
+/**
+ * A transport could not decode an inbound message (codec failure, malformed record) and
+ * dead-lettered or skipped it. It never reached the bus, so `onReceiveFinished` does not see it.
+ */
+interface InvalidMessageEvent {
+    /** Name of the transport. */
+    readonly transport: string;
+    /** The messaging system of the transport (`kafka`, `rabbitmq`), else its name. */
+    readonly system: string;
+    /** Topic, routing key or queue the message arrived on. */
+    readonly destination: string;
+    /** Why the message was rejected. */
+    readonly reason: string;
+    readonly error: ErrorInfo;
+}
+/** A periodic reading of the store's backlog (`RelayBusOptions.backlogInterval`). */
+interface BacklogEvent {
+    /** Deliveries waiting to run, due or not. */
+    readonly pending: number;
+    /** How long the oldest due delivery has waited; 0 when none is due. */
+    readonly oldestPendingAgeMs: number;
+    readonly statistics: EventStoreStatistics;
+}
 /**
  * Hooks for logging, metrics and tracing. Every method is optional, runs
  * synchronously on the hot path and must not throw; errors it throws are
@@ -769,6 +566,17 @@ interface RelayBusObserver {
         readonly stage: FailureStage;
         readonly error: ErrorInfo;
     }): void;
+    /** A publish call ended; called before the publishing transaction commits. */
+    onPublishFinished?(event: PublishFinishedEvent): void;
+    onClaimFinished?(event: ClaimFinishedEvent): void;
+    onHandlerStarted?(event: HandlerStartedEvent): void;
+    onHandlerFinished?(event: HandlerFinishedEvent): void;
+    onTransportSent?(event: TransportSentEvent): void;
+    onReceiveFinished?(event: ReceiveFinishedEvent): void;
+    /** A transport rejected an inbound message it could not decode. */
+    onInvalidMessage?(event: InvalidMessageEvent): void;
+    /** Called every `backlogInterval` while the bus runs, when that option is set. */
+    onBacklog?(event: BacklogEvent): void;
 }
 /** Minimal logger. Nest's `Logger` and `console` both satisfy it. */
 interface RelayBusLogger {
@@ -777,34 +585,6 @@ interface RelayBusLogger {
     error(message: string): void;
 }
 
-/** Receives an event from a broker. Resolve only after it is durably stored. */
-type TransportMessageHandler = (envelope: EventEnvelope) => Promise<void>;
-/**
- * Broker port used to exchange events between services.
- *
- * Outbound: the bus calls `publish` from a delivery, so a broker outage only
- * delays events; the outbox keeps them. `publish` must resolve only after the
- * broker acknowledged the message.
- *
- * Inbound: `subscribe` must acknowledge a message only after `onMessage`
- * resolved, and redeliver it when `onMessage` rejects (at-least-once).
- */
-interface Transport {
-    /** Unique name referenced by routes and subscriptions. */
-    readonly name: string;
-    connect?(): Promise<void>;
-    publish(envelope: EventEnvelope, destination: string): Promise<void>;
-    subscribe?(destinations: readonly string[], onMessage: TransportMessageHandler): Promise<void>;
-    /**
-     * Whether the transport can currently publish and, when subscribed, is
-     * consuming. Health checks use it to report a dead consumer or a lost
-     * connection. Transports without it count as ready.
-     */
-    isReady?(): boolean;
-    /** Releases connections. A closed transport is not reopened. */
-    close(): Promise<void>;
-}
-
 /**
  * - `required`: `publish` throws {@link TransactionRequiredError} when it finds no transaction.
  * - `optional`: `publish` opens its own transaction instead. The event is still durable,
@@ -830,7 +610,11 @@ interface DispatcherOptions {
     readonly pollInterval?: Duration;
     /** Lease length; renewed every third of it while the handler runs. Default `'30s'`. */
     readonly leaseDuration?: Duration;
-    /** How long `stop` waits for running handlers before aborting them. Default `'30s'`. */
+    /**
+     * Longest `stop` takes in all, and its default `timeout`: waiting for running handlers, handing
+     * back leases, closing transports and the store. Past it, `stop` aborts the handlers still
+     * running, force-closes what relaybus opened itself and resolves. Default `'30s'`.
+     */
     readonly shutdownTimeout?: Duration;
     /**
      * Longest a finished delivery waits so that deliveries finishing around the
@@ -855,6 +639,11 @@ interface RetentionOptions {
     /** How often the cleanup runs. Default `'1h'`. */
     readonly interval?: Duration;
 }
+/**
+ * Every route to one destination of one transport is one handler,
+ * `relaybus.transport:<transport>:<destination>`: its events of one key are sent in commit
+ * order whatever their types. Such routes must resolve to the same `retry` and `timeout`.
+ */
 interface RouteOptions {
     /** Event class or type forwarded to the transport. */
     readonly event: EventReference;
@@ -877,6 +666,15 @@ interface RelayBusOptions<TTransaction = unknown> {
     readonly source?: string;
     /** Default `'required'`. */
     readonly transactionMode?: TransactionMode;
+    /**
+     * Time budget of every `bus.transaction` (and `@RelayBusTransaction()` method). The store makes
+     * the database enforce it where it can (PostgreSQL: `statement_timeout`, plus
+     * `idle_in_transaction_session_timeout` and on PostgreSQL 17+ `transaction_timeout`; MongoDB:
+     * `maxCommitTimeMS`), and a transaction that still runs past
+     * it is rolled back with a {@link TransactionTimeoutError}. Keep calls to other services out of
+     * transactions instead of raising it. Default `'5s'`.
+     */
+    readonly transactionTimeout?: Duration;
     /**
      * Finds the caller's active transaction when none is passed to `publish`
      * and none was opened with `bus.transaction`, for example from
@@ -898,7 +696,23 @@ interface RelayBusOptions<TTransaction = unknown> {
     readonly subscriptions?: readonly InboundSubscriptionOptions[];
     /** Create tables and indexes on start. Default true. */
     readonly setupStore?: boolean;
+    /**
+     * Hooks for logging and metrics. The hooks an observer implements are read when the bus is
+     * created; the newer ones (`onPublishFinished` and the other timed hooks) are skipped entirely,
+     * clock reads included, when no observer implements them.
+     */
     readonly observers?: readonly RelayBusObserver[];
+    /**
+     * Spans around publish, send and handler runs, and the W3C trace context written into published
+     * events (`traceparent`, `tracestate` headers). `@relaybus/otel` provides one. Default: none.
+     */
+    readonly tracer?: RelayBusTracer;
+    /**
+     * Reads `statistics()` this often while the bus runs and reports the backlog (pending deliveries,
+     * age of the oldest due one) to the observers' `onBacklog`. Each reading is a store query, so it
+     * is off unless set; `'15s'` to `'1m'` suits metrics scraped every minute. Default: off.
+     */
+    readonly backlogInterval?: Duration;
     /** Default: `console`. */
     readonly logger?: RelayBusLogger;
     readonly clock?: Clock;
@@ -921,7 +735,9 @@ interface PublishOptions<TTransaction = unknown> {
     /**
      * Ordering and partition key. Events with the same key are handled one at a
      * time per handler, in commit order. A delayed or retrying event holds back
-     * later events of its key.
+     * later events of its key. Default: the `key` of the event's definition
+     * (`defineEvent(type, { key })`), else none. An explicit key wins over the definition's, and in
+     * `publishAll` applies to every event of the call.
      */
     readonly key?: string;
     /** Deliver no earlier than this delay from now. */
@@ -942,6 +758,106 @@ interface PublishOneOptions<TTransaction = unknown> extends PublishOptions<TTran
     readonly id?: string;
 }
 type ReceiveStatus = 'accepted' | 'duplicate' | 'ignored';
+
+/** The publishing half of a bus, which a {@link CatalogPublisher} delegates to. */
+interface PublishTarget<TTransaction> {
+    publish<TPayload>(event: DomainEvent<TPayload>, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TPayload>>;
+    publishAll(events: readonly DomainEvent[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
+}
+/**
+ * A view of a bus that publishes only the events of one catalog, or only the
+ * events a service produces from it. Obtain it with `bus.forCatalog(catalog)`
+ * or `bus.forCatalog(catalog, { events: ['OrderPlaced'] })`. Publishing an
+ * event outside the view fails to compile; a mistyped event that gets past the
+ * compiler (a cast, plain JavaScript, or a class with a structurally identical
+ * payload) is rejected with a {@link ConfigurationError} before anything is stored.
+ *
+ * ```ts
+ * const orders = bus.forCatalog(OrderEvents);
+ * await orders.publish(new OrderPlaced({ orderId }));
+ * await orders.publish(new UserRegistered({ userId })); // compile error
+ * ```
+ */
+declare class CatalogPublisher<TCatalog extends Catalog, TTransaction = unknown, TName extends keyof TCatalog = keyof TCatalog> {
+    #private;
+    /**
+     * Throws {@link ConfigurationError} when `catalog` was not created with
+     * `defineCatalog` or `options.events` names no event, an unknown event or
+     * the same event twice.
+     */
+    constructor(catalog: TCatalog, target: PublishTarget<TTransaction>, options?: CatalogEventSelection<TName>);
+    /** Same as `bus.publish`, limited to the events of the view. */
+    publish<TEvent extends CatalogEvents<TCatalog, TName>>(event: TEvent, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TEvent['payload']>>;
+    /** Same as `bus.publishAll`, limited to the events of the view. Nothing is stored unless every event belongs to it. */
+    publishAll(events: readonly CatalogEvents<TCatalog, TName>[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
+}
+
+/** Transaction handle of {@link InMemoryEventStore}. Writes apply on commit only. */
+declare class InMemoryTransaction {
+    #private;
+    get state(): 'open' | 'committed' | 'rolled-back';
+    enqueue(operation: () => void): void;
+    /** Runs `finisher` once the transaction commits or rolls back, like a lock release. */
+    onFinish(finisher: () => void): void;
+    commit(): void;
+    rollback(): void;
+}
+
+interface InMemoryEventStoreOptions {
+    /** Allow use when `NODE_ENV` is `production`. Data is lost on restart. Default false. */
+    readonly allowInProduction?: boolean;
+    readonly generateIdentifier?: IdentifierGenerator;
+    /**
+     * Keep a record of completed deliveries (status `completed`, listed, counted
+     * and purged by `retention.completed`). Default false: a completed delivery
+     * is deleted, like in the database stores.
+     */
+    readonly retainCompleted?: boolean;
+}
+/**
+ * Event store kept in process memory, with the same semantics as the database
+ * stores: transactional appends, leases, fencing and per-key ordering. Payloads
+ * are round-tripped through JSON exactly like a database would store them.
+ * Meant for tests and local development.
+ */
+declare class InMemoryEventStore implements EventStore<InMemoryTransaction> {
+    #private;
+    constructor(options?: InMemoryEventStoreOptions);
+    transaction<T>(work: (transaction: InMemoryTransaction) => Promise<T>): Promise<T>;
+    append(transaction: InMemoryTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
+    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    complete(lease: LeaseReference, now: Date, transaction?: InMemoryTransaction): Promise<boolean>;
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
+    reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
+    release(lease: LeaseReference, now: Date): Promise<boolean>;
+    bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
+    listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
+    requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
+    purge(request: PurgeRequest): Promise<PurgeResult>;
+    statistics(now: Date): Promise<EventStoreStatistics>;
+}
+
+interface StopOptions {
+    /**
+     * Longest the whole `stop` may take. Default: `dispatcher.shutdownTimeout`. Keep it below the time
+     * the platform waits before killing the process (Kubernetes `terminationGracePeriodSeconds`).
+     */
+    readonly timeout?: Duration;
+}
+/** How a `stop` went. */
+interface StopResult {
+    /** False when the deadline passed and `stop` aborted handlers or force-closed connections. */
+    readonly graceful: boolean;
+    /**
+     * Deliveries whose handlers still ran at the deadline. Their leases expire after
+     * `dispatcher.leaseDuration` and another process runs them again (at-least-once).
+     */
+    readonly abandonedDeliveries: number;
+    /** Time `stop` took, on the bus clock. */
+    readonly durationMs: number;
+}
+
 /**
  * Reliable event bus: events are stored with business data in one transaction,
  * then dispatched to every subscribed handler and route with independent
@@ -1005,9 +921,16 @@ declare class RelayBus<TTransaction = unknown> {
     publishAll(events: readonly DomainEvent[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
     /**
      * 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.
      */
     transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
+    /**
+     * 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(): TTransaction | undefined;
     /**
      * Stores an event received from a broker and schedules it for local handlers.
      * Idempotent on the event id. Transports call it and acknowledge the message
@@ -1022,10 +945,15 @@ declare class RelayBus<TTransaction = unknown> {
      */
     start(): Promise<void>;
     /**
-     * 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.
      */
-    stop(): Promise<void>;
+    stop(options?: StopOptions): Promise<StopResult>;
     /**
      * Claims and runs one batch of due deliveries, resolving when they settle.
      * Returns how many ran. Intended for tests and scripts.
@@ -1044,82 +972,4 @@ declare class RelayBus<TTransaction = unknown> {
     purgeExpired(): Promise<PurgeResult>;
 }
 
-/** The publishing half of a bus, which a {@link CatalogPublisher} delegates to. */
-interface PublishTarget<TTransaction> {
-    publish<TPayload>(event: DomainEvent<TPayload>, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TPayload>>;
-    publishAll(events: readonly DomainEvent[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
-}
-/**
- * A view of a bus that publishes only the events of one catalog, or only the
- * events a service produces from it. Obtain it with `bus.forCatalog(catalog)`
- * or `bus.forCatalog(catalog, { events: ['OrderPlaced'] })`. Publishing an
- * event outside the view fails to compile; a mistyped event that gets past the
- * compiler (a cast, plain JavaScript, or a class with a structurally identical
- * payload) is rejected with a {@link ConfigurationError} before anything is stored.
- *
- * ```ts
- * const orders = bus.forCatalog(OrderEvents);
- * await orders.publish(new OrderPlaced({ orderId }));
- * await orders.publish(new UserRegistered({ userId })); // compile error
- * ```
- */
-declare class CatalogPublisher<TCatalog extends Catalog, TTransaction = unknown, TName extends keyof TCatalog = keyof TCatalog> {
-    #private;
-    /**
-     * Throws {@link ConfigurationError} when `catalog` was not created with
-     * `defineCatalog` or `options.events` names no event, an unknown event or
-     * the same event twice.
-     */
-    constructor(catalog: TCatalog, target: PublishTarget<TTransaction>, options?: CatalogEventSelection<TName>);
-    /** Same as `bus.publish`, limited to the events of the view. */
-    publish<TEvent extends CatalogEvents<TCatalog, TName>>(event: TEvent, options?: PublishOneOptions<TTransaction>): Promise<EventEnvelope<TEvent['payload']>>;
-    /** Same as `bus.publishAll`, limited to the events of the view. Nothing is stored unless every event belongs to it. */
-    publishAll(events: readonly CatalogEvents<TCatalog, TName>[], options?: PublishOptions<TTransaction>): Promise<EventEnvelope[]>;
-}
-
-interface InMemoryEventStoreOptions {
-    /** Allow use when `NODE_ENV` is `production`. Data is lost on restart. Default false. */
-    readonly allowInProduction?: boolean;
-    readonly generateIdentifier?: IdentifierGenerator;
-    /**
-     * Keep a record of completed deliveries (status `completed`, listed, counted
-     * and purged by `retention.completed`). Default false: a completed delivery
-     * is deleted, like in the database stores.
-     */
-    readonly retainCompleted?: boolean;
-}
-/** Transaction handle of {@link InMemoryEventStore}. Writes apply on commit only. */
-declare class InMemoryTransaction {
-    #private;
-    get state(): 'open' | 'committed' | 'rolled-back';
-    enqueue(operation: () => void): void;
-    /** Runs `finisher` once the transaction commits or rolls back, like a lock release. */
-    onFinish(finisher: () => void): void;
-    commit(): void;
-    rollback(): void;
-}
-/**
- * Event store kept in process memory, with the same semantics as the database
- * stores: transactional appends, leases, fencing and per-key ordering. Payloads
- * are round-tripped through JSON exactly like a database would store them.
- * Meant for tests and local development.
- */
-declare class InMemoryEventStore implements EventStore<InMemoryTransaction> {
-    #private;
-    constructor(options?: InMemoryEventStoreOptions);
-    transaction<T>(work: (transaction: InMemoryTransaction) => Promise<T>): Promise<T>;
-    append(transaction: InMemoryTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
-    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
-    complete(lease: LeaseReference, now: Date, transaction?: InMemoryTransaction): Promise<boolean>;
-    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
-    reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
-    release(lease: LeaseReference, now: Date): Promise<boolean>;
-    bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
-    listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
-    requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
-    purge(request: PurgeRequest): Promise<PurgeResult>;
-    statistics(now: Date): Promise<EventStoreStatistics>;
-}
-
-export { type AppendEntry, type AppendResult, type Catalog, type CatalogDeclaration, type CatalogDescription, type CatalogEntry, type CatalogEventClass, type CatalogEventName, type CatalogEventSelection, type CatalogEvents, CatalogPublisher, type CatalogRole, type ClaimRequest, type ClaimedDelivery, type Clock, ConfigurationError, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, DELIVERY_STATUSES, type DefineCatalogOptions, type DefineEventOptions, type DeliveryQuery, type DeliveryRecord, type DeliveryStatus, type DispatcherOptions, DispatcherStoppedError, type DomainEvent, type Duration, type ErrorInfo, type EventClass, type EventEnvelope, type EventHandler, type EventHeaders, type EventOf, type EventReference, type EventStore, type EventStoreStatistics, EventValidationError, type FailureStage, type HandlerContext, type HandlerDescriptor, type HandlerShapeOf, HandlerTimeoutError, type HandlersOf, type IdentifierGenerator, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryTransaction, type InboundSubscriptionOptions, InvalidEnvelopeError, type JitterStrategy, LeaseLostError, type LeaseReference, MAX_TIMER_DELAY_MS, type MatchingHandlers, type NewDelivery, type NoExtraHandlers, NonRetryableError, type PartialHandlersOf, type PayloadOf, type PublishOneOptions, type PublishOptions, type PublishTarget, type PurgeRequest, type PurgeResult, type ReceiveStatus, RelayBus, RelayBusError, type RelayBusLogger, type RelayBusObserver, type RelayBusOptions, type RetentionOptions, type RetryPolicy, type RetryPolicyOptions, type RouteOptions, StandardSchemaV1, type SubscribeCatalogOptions, type SubscribeOptions, type TransactionMode, TransactionRequiredError, type Transport, type TransportMessageHandler, type UnroutedEventPolicy, type ValidationIssue, assertEventType, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineEvent, defineHandlers, describeCatalog, isRetryableError, produce, systemClock, toErrorInfo, toMilliseconds, validatePayload };
+export { AppendEntry, AppendResult, type BacklogEvent, type Catalog, type CatalogDeclaration, type CatalogDescription, type CatalogEntry, type CatalogEventClass, type CatalogEventName, type CatalogEventSelection, type CatalogEvents, CatalogPublisher, type CatalogRole, type ClaimFinishedEvent, ClaimRequest, ClaimedDelivery, Clock, DEFAULT_RETRY_POLICY, DEFAULT_ROUTE_RETRY_POLICY, type DefineCatalogOptions, type DeliveryKind, DeliveryQuery, DeliveryRecord, type DispatcherOptions, DomainEvent, Duration, ErrorInfo, EventClass, EventEnvelope, type EventHandler, EventHeaders, type EventOf, EventReference, EventStore, EventStoreStatistics, type FailureStage, type HandlerContext, type HandlerDescriptor, type HandlerFinishedEvent, type HandlerShapeOf, type HandlerStartedEvent, type HandlersOf, type IdentifierGenerator, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryTransaction, type InboundSubscriptionOptions, type InvalidMessageEvent, type JitterStrategy, LeaseReference, type MatchingHandlers, type NoExtraHandlers, type OperationOutcome, type PartialHandlersOf, PayloadOf, type ProcessTraceInput, type PublishFinishedEvent, type PublishOneOptions, type PublishOptions, type PublishTarget, type PublishTraceInput, PurgeRequest, PurgeResult, type ReceiveFinishedEvent, type ReceiveOutcome, type ReceiveStatus, RelayBus, type RelayBusLogger, type RelayBusObserver, type RelayBusOptions, type RelayBusTracer, type RetentionOptions, type RetryPolicy, type RetryPolicyOptions, type RouteOptions, type SendTraceInput, StandardSchemaV1, type StopOptions, type StopResult, type SubscribeCatalogOptions, type SubscribeOptions, TRACEPARENT_HEADER, TRACESTATE_HEADER, type TraceContext, type TransactionMode, Transport, type TransportSentEvent, type UnroutedEventPolicy, computeRetryDelay, consume, createRetryPolicy, createUuidV7, defineCatalog, defineHandlers, describeCatalog, isRetryableError, produce, traceContextOf };