@relaybus/mongodb 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { EventStore, IdentifierGenerator, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+import { EventStore, RelayBusLogger, IdentifierGenerator, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
 import { ClientSession, MongoClient, TransactionOptions } from 'mongodb';
 
 interface MongoEventStoreOptions {
@@ -6,7 +6,7 @@ interface MongoEventStoreOptions {
     readonly client: MongoClient;
     /** Database holding the relaybus collections. Default: the client's default database. */
     readonly database?: string;
-    /** Prefix of the three collection names. Default `relaybus_`. */
+    /** Prefix of the collection names. Default `relaybus_`. */
     readonly collectionPrefix?: string;
     /**
      * Options of the transactions the store opens. Default: snapshot read
@@ -15,7 +15,20 @@ interface MongoEventStoreOptions {
     readonly transactionOptions?: TransactionOptions;
     /** Rows deleted per purge step. Default 500. */
     readonly purgeBatchSize?: number;
-    /** Produces lease tokens. Default UUID v7. */
+    /**
+     * Keep an append-only record of every completed delivery in
+     * `<prefix>completed_deliveries`, listed as `completed`, counted by
+     * `statistics` and removed by `purge({ completedBefore })`. Default false: a
+     * completed delivery is deleted and leaves nothing behind. Use the same value
+     * in every process.
+     */
+    readonly completionHistory?: boolean;
+    /** Receives warnings about best-effort steps that failed (parking). Default `console`. */
+    readonly logger?: RelayBusLogger;
+    /**
+     * @deprecated Ignored. Lease tokens name the lane and its epoch
+     * (`<laneId>:<epoch>:<claims>`) and are no longer generated.
+     */
     readonly generateIdentifier?: IdentifierGenerator;
 }
 /**
@@ -24,29 +37,75 @@ interface MongoEventStoreOptions {
  * session can carry your own writes (native driver or Mongoose).
  *
  * Guarantees:
- * - `append` is atomic with the caller's writes and idempotent on event id and on
- *   (event id, handler). Duplicates are detected by reading, never by catching a
+ * - **Atomic, idempotent append.** `append` is atomic with the caller's writes
+ *   and idempotent on event id and on (event id, handler). An event remembers
+ *   every handler it ever had a delivery for, so a redelivered or republished
+ *   event never runs a completed handler again although completed deliveries are
+ *   deleted. Duplicates are detected by reading, never by catching a
  *   duplicate-key error, which would abort the surrounding transaction.
- * - Per-key sequences are allocated from a counter document inside the append
- *   transaction. Two transactions appending the same key cannot both hold the
- *   counter, so the loser conflicts, restarts after the winner committed, and
- *   its sequence is higher: sequence order is commit order.
- * - `claim` selects candidates, then takes each with a conditional update that
- *   re-checks the exact state it selected, so exactly one claimer wins. A keyed
- *   delivery waits while an earlier delivery of its handler and key is
- *   unfinished, or while any other delivery of them runs under a live lease;
- *   the second rule is re-checked after the update, so a dead letter requeued
- *   during a claim cannot run alongside its successor.
- * - Every lease operation is fenced by delivery id, status and lease token.
+ * - **Per-key order.** Per-key sequences come from a counter document inside the
+ *   append transaction. Two transactions appending the same key cannot both hold
+ *   the counter, so the loser conflicts, restarts after the winner committed, and
+ *   its sequence is higher: sequence order is commit order. A keyed delivery is
+ *   claimed only when no earlier delivery of its handler and key is pending and
+ *   no other delivery of them runs.
+ * - **Lane leases.** Every delivery belongs to one of 256 lanes (a hash of its
+ *   ordering key, or of its event id), so all deliveries of a key share a lane.
+ *   Workers lease lanes with one conditional write on a lane document, and a
+ *   claim records its whole batch in the lane documents: it writes no delivery
+ *   document. While a lane lease is live, other workers do not see the pending
+ *   deliveries of that lane, even idle ones. A lane changes hands only when its
+ *   lease expired or its owner handed it back.
+ * - **Fencing.** A lease token is `<laneId>:<epoch>:<claims>`. The epoch grows
+ *   whenever the lane is taken; `claims`, the delivery's claim generation, grows
+ *   whenever a claim of it ends (retry, release, burial, lost lease), so the
+ *   lease of an earlier claim never matches a later claim of the same delivery
+ *   in the same lane epoch. Completion, retry, burial, release and renewal apply
+ *   only while the lane has that epoch, lists the delivery as in flight, and the
+ *   delivery has that claim generation.
+ * - **Effectively-once for transactional handlers.** A worker that takes a lane
+ *   over first writes every delivery the previous owner had in flight (it
+ *   charges the lost attempt) and only then reads what to claim. A completion
+ *   inside a transaction (a transactional handler's, or any completion when a
+ *   completion history is kept) deletes the delivery after checking the lane:
+ *   both write the same delivery document, so the later of the two either
+ *   conflicts and retries (and then sees the new epoch or the missing
+ *   delivery), or waits for the earlier to commit. Other completions run
+ *   without a transaction: they read the deliveries' claim generations, then
+ *   the lanes, and delete only deliveries whose generation did not change,
+ *   which a takeover, a retry or a release always changes. Either way a completion and a takeover
+ *   cannot both succeed. Completions never write the lane document, so
+ *   concurrent completions of one lane never conflict with each other.
+ * - **Attempts survive crashes.** `attempts` counts attempts that ended. The
+ *   claim result reports `attempts + 1`; a failure records it; a lane taken over
+ *   charges one attempt to every delivery the previous owner still had in flight,
+ *   so a poison message still reaches the retry limit after crashes.
+ *
+ * - **Deduplication record.** A completion records its time on the event
+ *   (`completedAt`). An event nothing references any more stays until
+ *   `purge({ completedBefore })` passes that time, however old the event is, and
+ *   `deadBefore` alone never removes it. Once purged, the event takes its list
+ *   of handlers with it: a broker redelivery or publish retry of that event id
+ *   afterwards is appended as a new event and runs its handlers again, as in
+ *   the PostgreSQL store, so keep completed retention longer than any
+ *   redelivery window.
  *
  * `transaction` may run `work` more than once (see {@link MongoEventStore.transaction}).
+ * Claims of one `leaseOwner` on one store instance run one after the other
+ * (a claim that overlaps another of the same owner waits for it); different
+ * owners claim concurrently, from any number of processes. Lanes are held per store
+ * instance, so a process restarted with the same `leaseOwner` takes its
+ * predecessor's lanes over only once their leases expired.
  */
 declare class MongoEventStore implements EventStore<ClientSession> {
     #private;
     constructor(options: MongoEventStoreOptions);
     /**
-     * Verifies the deployment supports transactions and creates the indexes.
-     * Safe to run repeatedly and from several processes.
+     * Verifies the deployment supports transactions, creates the collections and
+     * indexes and seeds the lane documents. Upgrades a 0.1.0 database in place
+     * first (see `MongoSchema.#upgradeFromVersion010`); the seeded lanes
+     * mark the upgrade as done, so later runs skip it. Safe to run repeatedly and
+     * from several processes. Stop 0.1.0 workers before the first run.
      *
      * @throws ConfigurationError when the server is a standalone mongod.
      */
@@ -61,19 +120,99 @@ declare class MongoEventStore implements EventStore<ClientSession> {
      * not safe for side effects outside the session (HTTP calls, other databases),
      * so keep those out of `work`; relaybus handlers are already at-least-once.
      *
+     * With `options.timeoutMs` (from `bus.transaction`) the server bounds the commit with
+     * `maxCommitTimeMS`; the bus aborts a transaction that ran past the budget before its commit.
+     *
      * @throws ConfigurationError when the deployment does not support transactions.
      */
-    transaction<T>(work: (transaction: ClientSession) => Promise<T>): Promise<T>;
+    transaction<T>(work: (transaction: ClientSession) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
+    /**
+     * Writes the entries in `session`. An existing event gets a delivery only for
+     * handlers it does not list yet; the added handlers are appended to its list
+     * together with a `revision` increment, a real write that makes a concurrent
+     * purge of the event conflict with this transaction.
+     */
     append(session: ClientSession, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
+    /**
+     * Claims up to `limit` due deliveries. It claims from the lanes this owner
+     * (and this store instance) holds under a live lease first, then takes free
+     * lanes with due work, a few at a time (4, 8, 16, ...) and the lane with the
+     * oldest due delivery first, so a worker holds only as many lanes as it
+     * needs. It then records the batch with one write per lane and hands back the
+     * lanes that yielded nothing and run nothing. No delivery document is
+     * written, except for the attempt charged to deliveries of a lane taken over
+     * and for parking (see `MongoOrdering.#parkDeliveries`).
+     *
+     * Taking a lane is one conditional `findOneAndUpdate` that also moves the
+     * previous owner's in-flight list to the lane's `lost` list; a lane another
+     * claimer took first is skipped, never waited for. Lost deliveries are charged
+     * one attempt before anything is read from the lane, and `lost` is cleared
+     * only after that. Whoever holds the lane next charges a `lost` list it finds
+     * first, so a claim that fails anywhere after the take loses no charge; the
+     * charge of a lost claim is recorded on the delivery, so charging the list
+     * again after a failure before the clear charges nothing twice.
+     * Nothing a failed claim did leaves a delivery listed as running.
+     */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    /**
+     * Extends the lease of the lane a running delivery belongs to. The lane lease
+     * never shrinks, so a repeated renewal with the same value still holds. An
+     * expired lease nobody took over is still renewed, so `_now` is not needed.
+     */
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date, _now?: Date): Promise<boolean>;
+    /**
+     * Deletes the delivery (and records it in the completion history, when kept).
+     * With `session` the deletion commits with the caller's transaction; without,
+     * it runs in a transaction of its own. Returns false when the lease was lost.
+     */
     complete(lease: LeaseReference, now: Date, session?: ClientSession): Promise<boolean>;
+    /**
+     * Completes many leases with a fixed number of round trips, whatever lanes
+     * they belong to: three commands without a completion history, one
+     * transaction with it (see `MongoCompletion.#deleteFenced`).
+     * Returns one flag per lease in input order; a lease listed twice completes
+     * once, and a token this store cannot have issued is refused.
+     */
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
+    /** Returns a running delivery to pending, due at `availableAt`, and counts the attempt that ended. */
     reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
+    /** Gives a running delivery back without counting the attempt: pending, due `now`. */
     release(lease: LeaseReference, now: Date): Promise<boolean>;
+    /** Moves a running delivery to dead and counts the attempt that ended. */
     bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
+    /**
+     * Frees every lane `leaseOwner` holds that runs no delivery, so other workers
+     * need not wait for the lease to expire. Lanes with running deliveries stay leased.
+     */
+    relinquish(leaseOwner: string): Promise<void>;
+    /**
+     * Lists deliveries in creation order. A delivery is `processing` while its
+     * document exists as `pending` and its lane lists it; its attempt count then
+     * includes the running attempt, and owner and expiry are those of the lane
+     * lease. Completion history records (when kept) are listed as `completed`.
+     */
     listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
+    /** Moves dead deliveries back to pending with a fresh attempt budget. */
     requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
+    /**
+     * Deletes, in batches of `purgeBatchSize`, dead deliveries last updated before
+     * `deadBefore`, and completion history records (and `completed` documents left
+     * by 0.1.0) completed before `completedBefore`, each batch in one transaction
+     * together with the events it left without any reference. Finally, events
+     * nothing references are deleted: one with a completed delivery once its last
+     * completion is before `completedBefore` (never by `deadBefore` alone), one
+     * that never had a completion (no subscribers, or only dead letters) once it
+     * was created before the earliest given cutoff. The batch step applies the
+     * same rule to events whose last completion is recorded.
+     */
     purge(request: PurgeRequest): Promise<PurgeResult>;
+    /**
+     * Counts by derived status. `pending` excludes running deliveries; `completed`
+     * counts history records and 0.1.0 `completed` documents. `oldestDueAt` is the
+     * oldest instant at which a delivery became claimable: the due time of a
+     * pending delivery nobody runs, or the lease expiry of a lane that still runs
+     * deliveries.
+     */
     statistics(now: Date): Promise<EventStoreStatistics>;
 }
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EventStore, IdentifierGenerator, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+import { EventStore, RelayBusLogger, IdentifierGenerator, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
 import { ClientSession, MongoClient, TransactionOptions } from 'mongodb';
 
 interface MongoEventStoreOptions {
@@ -6,7 +6,7 @@ interface MongoEventStoreOptions {
     readonly client: MongoClient;
     /** Database holding the relaybus collections. Default: the client's default database. */
     readonly database?: string;
-    /** Prefix of the three collection names. Default `relaybus_`. */
+    /** Prefix of the collection names. Default `relaybus_`. */
     readonly collectionPrefix?: string;
     /**
      * Options of the transactions the store opens. Default: snapshot read
@@ -15,7 +15,20 @@ interface MongoEventStoreOptions {
     readonly transactionOptions?: TransactionOptions;
     /** Rows deleted per purge step. Default 500. */
     readonly purgeBatchSize?: number;
-    /** Produces lease tokens. Default UUID v7. */
+    /**
+     * Keep an append-only record of every completed delivery in
+     * `<prefix>completed_deliveries`, listed as `completed`, counted by
+     * `statistics` and removed by `purge({ completedBefore })`. Default false: a
+     * completed delivery is deleted and leaves nothing behind. Use the same value
+     * in every process.
+     */
+    readonly completionHistory?: boolean;
+    /** Receives warnings about best-effort steps that failed (parking). Default `console`. */
+    readonly logger?: RelayBusLogger;
+    /**
+     * @deprecated Ignored. Lease tokens name the lane and its epoch
+     * (`<laneId>:<epoch>:<claims>`) and are no longer generated.
+     */
     readonly generateIdentifier?: IdentifierGenerator;
 }
 /**
@@ -24,29 +37,75 @@ interface MongoEventStoreOptions {
  * session can carry your own writes (native driver or Mongoose).
  *
  * Guarantees:
- * - `append` is atomic with the caller's writes and idempotent on event id and on
- *   (event id, handler). Duplicates are detected by reading, never by catching a
+ * - **Atomic, idempotent append.** `append` is atomic with the caller's writes
+ *   and idempotent on event id and on (event id, handler). An event remembers
+ *   every handler it ever had a delivery for, so a redelivered or republished
+ *   event never runs a completed handler again although completed deliveries are
+ *   deleted. Duplicates are detected by reading, never by catching a
  *   duplicate-key error, which would abort the surrounding transaction.
- * - Per-key sequences are allocated from a counter document inside the append
- *   transaction. Two transactions appending the same key cannot both hold the
- *   counter, so the loser conflicts, restarts after the winner committed, and
- *   its sequence is higher: sequence order is commit order.
- * - `claim` selects candidates, then takes each with a conditional update that
- *   re-checks the exact state it selected, so exactly one claimer wins. A keyed
- *   delivery waits while an earlier delivery of its handler and key is
- *   unfinished, or while any other delivery of them runs under a live lease;
- *   the second rule is re-checked after the update, so a dead letter requeued
- *   during a claim cannot run alongside its successor.
- * - Every lease operation is fenced by delivery id, status and lease token.
+ * - **Per-key order.** Per-key sequences come from a counter document inside the
+ *   append transaction. Two transactions appending the same key cannot both hold
+ *   the counter, so the loser conflicts, restarts after the winner committed, and
+ *   its sequence is higher: sequence order is commit order. A keyed delivery is
+ *   claimed only when no earlier delivery of its handler and key is pending and
+ *   no other delivery of them runs.
+ * - **Lane leases.** Every delivery belongs to one of 256 lanes (a hash of its
+ *   ordering key, or of its event id), so all deliveries of a key share a lane.
+ *   Workers lease lanes with one conditional write on a lane document, and a
+ *   claim records its whole batch in the lane documents: it writes no delivery
+ *   document. While a lane lease is live, other workers do not see the pending
+ *   deliveries of that lane, even idle ones. A lane changes hands only when its
+ *   lease expired or its owner handed it back.
+ * - **Fencing.** A lease token is `<laneId>:<epoch>:<claims>`. The epoch grows
+ *   whenever the lane is taken; `claims`, the delivery's claim generation, grows
+ *   whenever a claim of it ends (retry, release, burial, lost lease), so the
+ *   lease of an earlier claim never matches a later claim of the same delivery
+ *   in the same lane epoch. Completion, retry, burial, release and renewal apply
+ *   only while the lane has that epoch, lists the delivery as in flight, and the
+ *   delivery has that claim generation.
+ * - **Effectively-once for transactional handlers.** A worker that takes a lane
+ *   over first writes every delivery the previous owner had in flight (it
+ *   charges the lost attempt) and only then reads what to claim. A completion
+ *   inside a transaction (a transactional handler's, or any completion when a
+ *   completion history is kept) deletes the delivery after checking the lane:
+ *   both write the same delivery document, so the later of the two either
+ *   conflicts and retries (and then sees the new epoch or the missing
+ *   delivery), or waits for the earlier to commit. Other completions run
+ *   without a transaction: they read the deliveries' claim generations, then
+ *   the lanes, and delete only deliveries whose generation did not change,
+ *   which a takeover, a retry or a release always changes. Either way a completion and a takeover
+ *   cannot both succeed. Completions never write the lane document, so
+ *   concurrent completions of one lane never conflict with each other.
+ * - **Attempts survive crashes.** `attempts` counts attempts that ended. The
+ *   claim result reports `attempts + 1`; a failure records it; a lane taken over
+ *   charges one attempt to every delivery the previous owner still had in flight,
+ *   so a poison message still reaches the retry limit after crashes.
+ *
+ * - **Deduplication record.** A completion records its time on the event
+ *   (`completedAt`). An event nothing references any more stays until
+ *   `purge({ completedBefore })` passes that time, however old the event is, and
+ *   `deadBefore` alone never removes it. Once purged, the event takes its list
+ *   of handlers with it: a broker redelivery or publish retry of that event id
+ *   afterwards is appended as a new event and runs its handlers again, as in
+ *   the PostgreSQL store, so keep completed retention longer than any
+ *   redelivery window.
  *
  * `transaction` may run `work` more than once (see {@link MongoEventStore.transaction}).
+ * Claims of one `leaseOwner` on one store instance run one after the other
+ * (a claim that overlaps another of the same owner waits for it); different
+ * owners claim concurrently, from any number of processes. Lanes are held per store
+ * instance, so a process restarted with the same `leaseOwner` takes its
+ * predecessor's lanes over only once their leases expired.
  */
 declare class MongoEventStore implements EventStore<ClientSession> {
     #private;
     constructor(options: MongoEventStoreOptions);
     /**
-     * Verifies the deployment supports transactions and creates the indexes.
-     * Safe to run repeatedly and from several processes.
+     * Verifies the deployment supports transactions, creates the collections and
+     * indexes and seeds the lane documents. Upgrades a 0.1.0 database in place
+     * first (see `MongoSchema.#upgradeFromVersion010`); the seeded lanes
+     * mark the upgrade as done, so later runs skip it. Safe to run repeatedly and
+     * from several processes. Stop 0.1.0 workers before the first run.
      *
      * @throws ConfigurationError when the server is a standalone mongod.
      */
@@ -61,19 +120,99 @@ declare class MongoEventStore implements EventStore<ClientSession> {
      * not safe for side effects outside the session (HTTP calls, other databases),
      * so keep those out of `work`; relaybus handlers are already at-least-once.
      *
+     * With `options.timeoutMs` (from `bus.transaction`) the server bounds the commit with
+     * `maxCommitTimeMS`; the bus aborts a transaction that ran past the budget before its commit.
+     *
      * @throws ConfigurationError when the deployment does not support transactions.
      */
-    transaction<T>(work: (transaction: ClientSession) => Promise<T>): Promise<T>;
+    transaction<T>(work: (transaction: ClientSession) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
+    /**
+     * Writes the entries in `session`. An existing event gets a delivery only for
+     * handlers it does not list yet; the added handlers are appended to its list
+     * together with a `revision` increment, a real write that makes a concurrent
+     * purge of the event conflict with this transaction.
+     */
     append(session: ClientSession, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
+    /**
+     * Claims up to `limit` due deliveries. It claims from the lanes this owner
+     * (and this store instance) holds under a live lease first, then takes free
+     * lanes with due work, a few at a time (4, 8, 16, ...) and the lane with the
+     * oldest due delivery first, so a worker holds only as many lanes as it
+     * needs. It then records the batch with one write per lane and hands back the
+     * lanes that yielded nothing and run nothing. No delivery document is
+     * written, except for the attempt charged to deliveries of a lane taken over
+     * and for parking (see `MongoOrdering.#parkDeliveries`).
+     *
+     * Taking a lane is one conditional `findOneAndUpdate` that also moves the
+     * previous owner's in-flight list to the lane's `lost` list; a lane another
+     * claimer took first is skipped, never waited for. Lost deliveries are charged
+     * one attempt before anything is read from the lane, and `lost` is cleared
+     * only after that. Whoever holds the lane next charges a `lost` list it finds
+     * first, so a claim that fails anywhere after the take loses no charge; the
+     * charge of a lost claim is recorded on the delivery, so charging the list
+     * again after a failure before the clear charges nothing twice.
+     * Nothing a failed claim did leaves a delivery listed as running.
+     */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    /**
+     * Extends the lease of the lane a running delivery belongs to. The lane lease
+     * never shrinks, so a repeated renewal with the same value still holds. An
+     * expired lease nobody took over is still renewed, so `_now` is not needed.
+     */
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date, _now?: Date): Promise<boolean>;
+    /**
+     * Deletes the delivery (and records it in the completion history, when kept).
+     * With `session` the deletion commits with the caller's transaction; without,
+     * it runs in a transaction of its own. Returns false when the lease was lost.
+     */
     complete(lease: LeaseReference, now: Date, session?: ClientSession): Promise<boolean>;
+    /**
+     * Completes many leases with a fixed number of round trips, whatever lanes
+     * they belong to: three commands without a completion history, one
+     * transaction with it (see `MongoCompletion.#deleteFenced`).
+     * Returns one flag per lease in input order; a lease listed twice completes
+     * once, and a token this store cannot have issued is refused.
+     */
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
+    /** Returns a running delivery to pending, due at `availableAt`, and counts the attempt that ended. */
     reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
+    /** Gives a running delivery back without counting the attempt: pending, due `now`. */
     release(lease: LeaseReference, now: Date): Promise<boolean>;
+    /** Moves a running delivery to dead and counts the attempt that ended. */
     bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
+    /**
+     * Frees every lane `leaseOwner` holds that runs no delivery, so other workers
+     * need not wait for the lease to expire. Lanes with running deliveries stay leased.
+     */
+    relinquish(leaseOwner: string): Promise<void>;
+    /**
+     * Lists deliveries in creation order. A delivery is `processing` while its
+     * document exists as `pending` and its lane lists it; its attempt count then
+     * includes the running attempt, and owner and expiry are those of the lane
+     * lease. Completion history records (when kept) are listed as `completed`.
+     */
     listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
+    /** Moves dead deliveries back to pending with a fresh attempt budget. */
     requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
+    /**
+     * Deletes, in batches of `purgeBatchSize`, dead deliveries last updated before
+     * `deadBefore`, and completion history records (and `completed` documents left
+     * by 0.1.0) completed before `completedBefore`, each batch in one transaction
+     * together with the events it left without any reference. Finally, events
+     * nothing references are deleted: one with a completed delivery once its last
+     * completion is before `completedBefore` (never by `deadBefore` alone), one
+     * that never had a completion (no subscribers, or only dead letters) once it
+     * was created before the earliest given cutoff. The batch step applies the
+     * same rule to events whose last completion is recorded.
+     */
     purge(request: PurgeRequest): Promise<PurgeResult>;
+    /**
+     * Counts by derived status. `pending` excludes running deliveries; `completed`
+     * counts history records and 0.1.0 `completed` documents. `oldestDueAt` is the
+     * oldest instant at which a delivery became claimable: the due time of a
+     * pending delivery nobody runs, or the lease expiry of a lane that still runs
+     * deliveries.
+     */
     statistics(now: Date): Promise<EventStoreStatistics>;
 }