@relaybus/postgres 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,17 +1,31 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresRow } from './executor-CSM7ZOhz.cjs';
-import { PoolClient, Pool, PoolConfig } from 'pg';
+import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-VZGmsMX4.cjs';
 import { RelayBusLogger, EventStore, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+import { PoolClient, Pool, PoolConfig } from 'pg';
 
+interface PgExecutorOptions {
+    /** Receives the warning sent when prepared statements are switched off. Default `console`. */
+    readonly logger?: RelayBusLogger;
+}
 /**
  * Executor for a `pg` {@link Pool}. A transaction is a dedicated pool client
  * between `BEGIN` and `COMMIT`; it is handed to callers as the transaction
  * handle, so they can run their own queries on it.
+ *
+ * A statement sent with `prepare: true` is a named prepared statement: each
+ * connection parses and plans its text once and from then on only binds the
+ * parameters. Its name is derived from the text, so stores with different
+ * tables never share one. When the server reports that a prepared statement
+ * does not exist on the connection, or already does (a pooler such as
+ * PgBouncer before 1.21 in transaction mode hands every transaction another
+ * server session), the executor stops preparing for good, logs a warning, and
+ * runs the statement again unprepared unless it belonged to a transaction,
+ * which has failed by then and is the caller's to retry.
  */
 declare class PgExecutor implements PostgresExecutor<PoolClient> {
     #private;
-    constructor(pool: Pool);
+    constructor(pool: Pool, options?: PgExecutorOptions);
     transaction<T>(work: (transaction: PoolClient) => Promise<T>): Promise<T>;
-    query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient): Promise<readonly PostgresRow[]>;
+    query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
 /** Where relaybus keeps its tables. */
@@ -24,6 +38,14 @@ interface PostgresSchemaOptions {
      * Lower-case letters, digits and underscores. Default `'relaybus_'`.
      */
     readonly tablePrefix?: string;
+    /**
+     * Keep an append-only record of completed deliveries in
+     * `<prefix>completed_deliveries`, so `listDeliveries({ status: 'completed' })`,
+     * `statistics().completed` and `retention.completed` keep working. Default
+     * `false`: a completed delivery is deleted, which avoids the dead tuples and
+     * index churn of updating it. Use the same value in every process.
+     */
+    readonly completionHistory?: boolean;
 }
 /** Validated, quoted names used to build SQL. */
 interface PostgresNames {
@@ -32,18 +54,32 @@ interface PostgresNames {
     readonly events: string;
     readonly deliveries: string;
     readonly keySequences: string;
+    /** Lane lease rows: one per lane, see {@link LANE_COUNT}. */
+    readonly lanes: string;
+    /** Unquoted, unqualified name of {@link lanes}, for catalog lookups. */
+    readonly lanesTableName: string;
+    /** One row per event that had a delivery complete: when the last one did. Retention of completed work is measured from it. */
+    readonly eventCompletions: string;
+    /** Completion history, present only with `completionHistory`. */
+    readonly completions: string;
+    readonly completionHistory: boolean;
+    /**
+     * Channel of the notifications that wake dispatchers when deliveries were published:
+     * `<schema>.<prefix>deliveries`, or a hash of it when that is longer than a channel name may be.
+     */
+    readonly notificationChannel: string;
     /** Index names, quoted but not schema-qualified (an index lives in its table's schema). */
     readonly indexes: {
         readonly deliveryEventHandler: string;
-        readonly deliveryDue: string;
-        readonly deliveryDueUnkeyed: string;
-        readonly deliveryHandlerCreated: string;
+        readonly deliveryLaneDue: string;
+        readonly deliveryKeyPending: string;
         readonly eventCreated: string;
-        readonly deliveryKeyUnfinished: string;
-        readonly deliveryKeyProcessing: string;
-        readonly deliveryStatusCreated: string;
         readonly deliveryCompleted: string;
         readonly deliveryDead: string;
+        readonly completionCompleted: string;
+        readonly eventCompletionsCompleted: string;
+        /** Indexes of the 0.1.0 schema that the current schema drops. */
+        readonly obsolete: readonly string[];
     };
 }
 /**
@@ -55,15 +91,23 @@ interface PostgresNames {
 declare function resolvePostgresNames(options?: PostgresSchemaOptions): PostgresNames;
 
 /**
- * Statements that create the schema, tables and indexes, in dependency order.
- * Every statement is idempotent (`IF NOT EXISTS`). Run them in one transaction
- * and serialize concurrent runs (see {@link PostgresEventStore.setup}), or
- * paste {@link createPostgresSchemaSql} into your own migration tool.
+ * Statements that create the schema, tables and indexes, in dependency order,
+ * and upgrade a 0.1.0 schema in place. Every statement is idempotent
+ * (`IF NOT EXISTS`, or guarded by a check for the 0.1.0 columns). Run them in
+ * one transaction and serialize concurrent runs (see
+ * {@link PostgresEventStore.setup}), or paste {@link createPostgresSchemaSql}
+ * into your own migration tool.
  *
  * `events.id` and `deliveries.id` are `text` so that any caller-supplied id
  * (UUID, ULID, deterministic business id) is accepted. `deliveries.id` uses the
  * `C` collation so that ordering by id matches a byte-wise comparison on every
  * database, whatever its locale.
+ *
+ * A delivery row is written once (insert) and removed once (delete) on the
+ * normal path. The lease lives in the lane row a delivery belongs to, so
+ * claiming, renewing and completing never update an indexed column of the
+ * delivery. The lane table is tiny, has no index besides its primary key and
+ * leaves free space in its pages, so its updates are heap-only (HOT).
  */
 declare function createPostgresSchemaStatements(options?: PostgresSchemaOptions): string[];
 /**
@@ -87,7 +131,29 @@ interface PostgresEventStoreSettings extends PostgresSchemaOptions {
      * it, otherwise `pg` raises an unhandled `error` event and the process exits.
      */
     readonly logger?: RelayBusLogger;
+    /**
+     * Send the statements the store repeats (publish, claim, complete, renew) as named prepared
+     * statements, so each connection parses and plans their text once instead of on every call. Default
+     * `true`. Set `false` behind a pooler in transaction mode that does not keep prepared statements per
+     * client (PgBouncer before 1.21, or 1.21+ with `max_prepared_statements = 0`). Left on there, the
+     * first statement that lands on another server session fails once, then the store stops preparing
+     * and logs a warning. Only executors that support it prepare (`PgExecutor`, the default); the
+     * other adapters send every statement unprepared.
+     */
+    readonly preparedStatements?: boolean;
+    /**
+     * How dispatchers in other processes learn about new deliveries.
+     * - `'notify'` (default): a publishing transaction sends `NOTIFY` (at most one per 10 ms per store,
+     *   the rest merged into one trailing notification after the commit) and each dispatcher listens
+     *   with `LISTEN` on a connection of its own, so a delivery is picked up within milliseconds.
+     * - `'poll'`: no `NOTIFY`, no listening connection. Other processes find new deliveries when they
+     *   poll (`dispatcher.pollInterval`, default 1 s); a dispatcher in the publishing process is still
+     *   woken at once. Use it behind a pooler in transaction mode, where `LISTEN` does not work.
+     */
+    readonly wakeUp?: PostgresWakeUp;
 }
+/** See {@link PostgresEventStoreSettings.wakeUp}. */
+type PostgresWakeUp = 'notify' | 'poll';
 /** Use an existing `pg` pool. The store never closes it. */
 interface PostgresPoolOptions extends PostgresEventStoreSettings {
     readonly pool: Pool;
@@ -126,13 +192,26 @@ type PostgresEventStoreOptions<TTransaction = PoolClient> = PostgresPoolOptions
  *   Publishing locks that row and holds the lock until commit, so two
  *   transactions publishing the same key are serialized and sequence order
  *   equals commit order. Claiming then hands out only the lowest unfinished
- *   sequence of a (handler, key).
- * - **Safe parallel claiming.** One `FOR UPDATE SKIP LOCKED` statement leases
- *   deliveries; any number of processes can claim at once.
+ *   sequence of a (handler, key), and all deliveries of a key live in one lane,
+ *   so one worker at a time sees them.
+ * - **Lane leases.** Workers lease lanes (256 hash buckets of the ordering key
+ *   or event id), not single deliveries. A claim writes one lane row for a
+ *   whole batch and never writes a delivery row; a completion deletes the
+ *   delivery rows. Delivery rows are therefore inserted once and deleted once,
+ *   which leaves no dead index entries from updates on the normal path.
  * - **Fenced state changes.** Complete, reschedule, bury and extend only apply
- *   to the lease token that claimed the delivery.
+ *   with the epoch of the lane lease that claimed the delivery. A lane taken
+ *   over by another worker gets a new epoch, which fences everything the
+ *   previous holder still runs. Completion takes a key-share lock on the lane
+ *   row, so it cannot interleave with a takeover.
+ * - **Attempts survive crashes.** A claim records which deliveries it put in
+ *   flight in the lane row. If the holder dies, the next holder charges one
+ *   attempt to each of them, so a poison message still reaches the retry limit.
  * - **App clock.** Every timestamp comes from the `now` the caller passes in,
  *   never from the database clock.
+ *
+ * Completed deliveries are deleted. Pass `completionHistory: true` to keep an
+ * append-only record for `listDeliveries({ status: 'completed' })`.
  */
 declare class PostgresEventStore<TTransaction = PoolClient> implements EventStore<TTransaction> {
     #private;
@@ -141,36 +220,58 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * Creates the schema, tables and indexes if they do not exist. Safe to call
      * from many processes at once: a transaction-scoped advisory lock serializes
      * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
+     * When the lane table already carries the marker of the current statements
+     * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+     * that start next to running dispatchers cannot deadlock with their claims.
      * Skip it (`setupStore: false`) when a migration tool applies
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
     transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
     /**
-     * Writes the entries in `transaction`. Keyed events reserve their sequence
-     * numbers first (locking the key rows in sorted order, so publishers cannot
-     * deadlock inside one call), then events, then deliveries, each in a single
-     * multi-row statement ordered by primary key. Two transactions that append
-     * keys in opposite order across several calls can still deadlock (40P01);
-     * the database rolls one back and the caller retries.
+     * Writes the entries in `transaction`, normally with one statement
+     * ({@link PostgresStatements.insertFreshEvents}): keyed events reserve their sequence numbers (locking
+     * the key rows in sorted order, so publishers cannot deadlock inside one call), then the new events and
+     * their deliveries are inserted, ordered by primary key, and one notification wakes the dispatchers
+     * when a delivery is due now. Events that already existed get their missing handlers' deliveries in
+     * two more statements. Two transactions that append keys in opposite order across several calls can
+     * still deadlock (40P01); the database rolls one back and the caller retries.
      * A duplicate event id still consumes a sequence number; gaps are harmless
      * because only the order of sequences matters.
      */
     append(transaction: TTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
     /**
-     * Leases up to `limit` due deliveries with `FOR UPDATE SKIP LOCKED`. The fast
-     * statement examines the first due deliveries; only when they are mostly
-     * blocked followers of busy keys does a second statement look at the heads of
-     * all keys. See {@link PostgresStatements.claim} for why that keeps a
-     * (handler, key) strictly one-at-a-time and in order.
+     * Claims up to `limit` due deliveries, normally with one statement
+     * ({@link PostgresStatements.claimLanes}): from the lanes this owner already holds, then from free lanes
+     * it takes in the same statement, recording the batch in the lane rows. A claim that would have to take
+     * over a lane whose previous holder still runs deliveries under an expired lease continues in a
+     * transaction that charges their lost attempts first, taking free lanes a few at a time (4, 8, 16, ...);
+     * so does a claim whose statement kept seeing a lane it holds change under it, and one that came up
+     * short with more free lanes left than it looked at. The step that fails after
+     * the first one has recorded deliveries returns those instead of failing: a recorded delivery nobody
+     * received would be held for a whole lease. See {@link PostgresStatements.claim} for the rules a delivery
+     * must satisfy.
      */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date): Promise<boolean>;
     complete(lease: LeaseReference, now: Date, transaction?: TTransaction): Promise<boolean>;
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
     reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
     bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
     /** Returns a leased delivery to pending, due now, without counting the attempt. */
     release(lease: LeaseReference, now: Date): Promise<boolean>;
+    /**
+     * Calls `listener` soon after a transaction that published deliveries due at once commits, in any
+     * process: `append` sends one `pg_notify` per call (merged per transaction, none for delayed
+     * deliveries), and this listens with `LISTEN` on a connection of its own, opened with the settings of
+     * the store's pool (one connection more than the pool's `max`). A lost connection is replaced after a
+     * second. Resolves with `undefined` for a store built on an `executor`, which has no connection of its
+     * own to listen on, and with `wakeUp: 'poll'`: polling then finds new deliveries (and the bus still
+     * wakes its own dispatcher).
+     */
+    watchNewDeliveries(listener: () => void): Promise<(() => Promise<void>) | undefined>;
+    /** Frees the lanes `leaseOwner` holds that run no delivery, so other workers need not wait for the lease to expire. */
+    relinquish(leaseOwner: string): Promise<void>;
     listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
     requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
     /**
@@ -188,4 +289,4 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
     close(): Promise<void>;
 }
 
-export { PgExecutor, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresRow, type PostgresSchemaOptions, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };

package/dist/index.d.ts

@@ -1,17 +1,31 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresRow } from './executor-CSM7ZOhz.js';
-import { PoolClient, Pool, PoolConfig } from 'pg';
+import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-VZGmsMX4.js';
 import { RelayBusLogger, EventStore, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics } from '@relaybus/core';
+import { PoolClient, Pool, PoolConfig } from 'pg';
 
+interface PgExecutorOptions {
+    /** Receives the warning sent when prepared statements are switched off. Default `console`. */
+    readonly logger?: RelayBusLogger;
+}
 /**
  * Executor for a `pg` {@link Pool}. A transaction is a dedicated pool client
  * between `BEGIN` and `COMMIT`; it is handed to callers as the transaction
  * handle, so they can run their own queries on it.
+ *
+ * A statement sent with `prepare: true` is a named prepared statement: each
+ * connection parses and plans its text once and from then on only binds the
+ * parameters. Its name is derived from the text, so stores with different
+ * tables never share one. When the server reports that a prepared statement
+ * does not exist on the connection, or already does (a pooler such as
+ * PgBouncer before 1.21 in transaction mode hands every transaction another
+ * server session), the executor stops preparing for good, logs a warning, and
+ * runs the statement again unprepared unless it belonged to a transaction,
+ * which has failed by then and is the caller's to retry.
  */
 declare class PgExecutor implements PostgresExecutor<PoolClient> {
     #private;
-    constructor(pool: Pool);
+    constructor(pool: Pool, options?: PgExecutorOptions);
     transaction<T>(work: (transaction: PoolClient) => Promise<T>): Promise<T>;
-    query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient): Promise<readonly PostgresRow[]>;
+    query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
 /** Where relaybus keeps its tables. */
@@ -24,6 +38,14 @@ interface PostgresSchemaOptions {
      * Lower-case letters, digits and underscores. Default `'relaybus_'`.
      */
     readonly tablePrefix?: string;
+    /**
+     * Keep an append-only record of completed deliveries in
+     * `<prefix>completed_deliveries`, so `listDeliveries({ status: 'completed' })`,
+     * `statistics().completed` and `retention.completed` keep working. Default
+     * `false`: a completed delivery is deleted, which avoids the dead tuples and
+     * index churn of updating it. Use the same value in every process.
+     */
+    readonly completionHistory?: boolean;
 }
 /** Validated, quoted names used to build SQL. */
 interface PostgresNames {
@@ -32,18 +54,32 @@ interface PostgresNames {
     readonly events: string;
     readonly deliveries: string;
     readonly keySequences: string;
+    /** Lane lease rows: one per lane, see {@link LANE_COUNT}. */
+    readonly lanes: string;
+    /** Unquoted, unqualified name of {@link lanes}, for catalog lookups. */
+    readonly lanesTableName: string;
+    /** One row per event that had a delivery complete: when the last one did. Retention of completed work is measured from it. */
+    readonly eventCompletions: string;
+    /** Completion history, present only with `completionHistory`. */
+    readonly completions: string;
+    readonly completionHistory: boolean;
+    /**
+     * Channel of the notifications that wake dispatchers when deliveries were published:
+     * `<schema>.<prefix>deliveries`, or a hash of it when that is longer than a channel name may be.
+     */
+    readonly notificationChannel: string;
     /** Index names, quoted but not schema-qualified (an index lives in its table's schema). */
     readonly indexes: {
         readonly deliveryEventHandler: string;
-        readonly deliveryDue: string;
-        readonly deliveryDueUnkeyed: string;
-        readonly deliveryHandlerCreated: string;
+        readonly deliveryLaneDue: string;
+        readonly deliveryKeyPending: string;
         readonly eventCreated: string;
-        readonly deliveryKeyUnfinished: string;
-        readonly deliveryKeyProcessing: string;
-        readonly deliveryStatusCreated: string;
         readonly deliveryCompleted: string;
         readonly deliveryDead: string;
+        readonly completionCompleted: string;
+        readonly eventCompletionsCompleted: string;
+        /** Indexes of the 0.1.0 schema that the current schema drops. */
+        readonly obsolete: readonly string[];
     };
 }
 /**
@@ -55,15 +91,23 @@ interface PostgresNames {
 declare function resolvePostgresNames(options?: PostgresSchemaOptions): PostgresNames;
 
 /**
- * Statements that create the schema, tables and indexes, in dependency order.
- * Every statement is idempotent (`IF NOT EXISTS`). Run them in one transaction
- * and serialize concurrent runs (see {@link PostgresEventStore.setup}), or
- * paste {@link createPostgresSchemaSql} into your own migration tool.
+ * Statements that create the schema, tables and indexes, in dependency order,
+ * and upgrade a 0.1.0 schema in place. Every statement is idempotent
+ * (`IF NOT EXISTS`, or guarded by a check for the 0.1.0 columns). Run them in
+ * one transaction and serialize concurrent runs (see
+ * {@link PostgresEventStore.setup}), or paste {@link createPostgresSchemaSql}
+ * into your own migration tool.
  *
  * `events.id` and `deliveries.id` are `text` so that any caller-supplied id
  * (UUID, ULID, deterministic business id) is accepted. `deliveries.id` uses the
  * `C` collation so that ordering by id matches a byte-wise comparison on every
  * database, whatever its locale.
+ *
+ * A delivery row is written once (insert) and removed once (delete) on the
+ * normal path. The lease lives in the lane row a delivery belongs to, so
+ * claiming, renewing and completing never update an indexed column of the
+ * delivery. The lane table is tiny, has no index besides its primary key and
+ * leaves free space in its pages, so its updates are heap-only (HOT).
  */
 declare function createPostgresSchemaStatements(options?: PostgresSchemaOptions): string[];
 /**
@@ -87,7 +131,29 @@ interface PostgresEventStoreSettings extends PostgresSchemaOptions {
      * it, otherwise `pg` raises an unhandled `error` event and the process exits.
      */
     readonly logger?: RelayBusLogger;
+    /**
+     * Send the statements the store repeats (publish, claim, complete, renew) as named prepared
+     * statements, so each connection parses and plans their text once instead of on every call. Default
+     * `true`. Set `false` behind a pooler in transaction mode that does not keep prepared statements per
+     * client (PgBouncer before 1.21, or 1.21+ with `max_prepared_statements = 0`). Left on there, the
+     * first statement that lands on another server session fails once, then the store stops preparing
+     * and logs a warning. Only executors that support it prepare (`PgExecutor`, the default); the
+     * other adapters send every statement unprepared.
+     */
+    readonly preparedStatements?: boolean;
+    /**
+     * How dispatchers in other processes learn about new deliveries.
+     * - `'notify'` (default): a publishing transaction sends `NOTIFY` (at most one per 10 ms per store,
+     *   the rest merged into one trailing notification after the commit) and each dispatcher listens
+     *   with `LISTEN` on a connection of its own, so a delivery is picked up within milliseconds.
+     * - `'poll'`: no `NOTIFY`, no listening connection. Other processes find new deliveries when they
+     *   poll (`dispatcher.pollInterval`, default 1 s); a dispatcher in the publishing process is still
+     *   woken at once. Use it behind a pooler in transaction mode, where `LISTEN` does not work.
+     */
+    readonly wakeUp?: PostgresWakeUp;
 }
+/** See {@link PostgresEventStoreSettings.wakeUp}. */
+type PostgresWakeUp = 'notify' | 'poll';
 /** Use an existing `pg` pool. The store never closes it. */
 interface PostgresPoolOptions extends PostgresEventStoreSettings {
     readonly pool: Pool;
@@ -126,13 +192,26 @@ type PostgresEventStoreOptions<TTransaction = PoolClient> = PostgresPoolOptions
  *   Publishing locks that row and holds the lock until commit, so two
  *   transactions publishing the same key are serialized and sequence order
  *   equals commit order. Claiming then hands out only the lowest unfinished
- *   sequence of a (handler, key).
- * - **Safe parallel claiming.** One `FOR UPDATE SKIP LOCKED` statement leases
- *   deliveries; any number of processes can claim at once.
+ *   sequence of a (handler, key), and all deliveries of a key live in one lane,
+ *   so one worker at a time sees them.
+ * - **Lane leases.** Workers lease lanes (256 hash buckets of the ordering key
+ *   or event id), not single deliveries. A claim writes one lane row for a
+ *   whole batch and never writes a delivery row; a completion deletes the
+ *   delivery rows. Delivery rows are therefore inserted once and deleted once,
+ *   which leaves no dead index entries from updates on the normal path.
  * - **Fenced state changes.** Complete, reschedule, bury and extend only apply
- *   to the lease token that claimed the delivery.
+ *   with the epoch of the lane lease that claimed the delivery. A lane taken
+ *   over by another worker gets a new epoch, which fences everything the
+ *   previous holder still runs. Completion takes a key-share lock on the lane
+ *   row, so it cannot interleave with a takeover.
+ * - **Attempts survive crashes.** A claim records which deliveries it put in
+ *   flight in the lane row. If the holder dies, the next holder charges one
+ *   attempt to each of them, so a poison message still reaches the retry limit.
  * - **App clock.** Every timestamp comes from the `now` the caller passes in,
  *   never from the database clock.
+ *
+ * Completed deliveries are deleted. Pass `completionHistory: true` to keep an
+ * append-only record for `listDeliveries({ status: 'completed' })`.
  */
 declare class PostgresEventStore<TTransaction = PoolClient> implements EventStore<TTransaction> {
     #private;
@@ -141,36 +220,58 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * Creates the schema, tables and indexes if they do not exist. Safe to call
      * from many processes at once: a transaction-scoped advisory lock serializes
      * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
+     * When the lane table already carries the marker of the current statements
+     * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+     * that start next to running dispatchers cannot deadlock with their claims.
      * Skip it (`setupStore: false`) when a migration tool applies
      * `createPostgresSchemaSql()` instead.
      */
     setup(): Promise<void>;
     transaction<T>(work: (transaction: TTransaction) => Promise<T>): Promise<T>;
     /**
-     * Writes the entries in `transaction`. Keyed events reserve their sequence
-     * numbers first (locking the key rows in sorted order, so publishers cannot
-     * deadlock inside one call), then events, then deliveries, each in a single
-     * multi-row statement ordered by primary key. Two transactions that append
-     * keys in opposite order across several calls can still deadlock (40P01);
-     * the database rolls one back and the caller retries.
+     * Writes the entries in `transaction`, normally with one statement
+     * ({@link PostgresStatements.insertFreshEvents}): keyed events reserve their sequence numbers (locking
+     * the key rows in sorted order, so publishers cannot deadlock inside one call), then the new events and
+     * their deliveries are inserted, ordered by primary key, and one notification wakes the dispatchers
+     * when a delivery is due now. Events that already existed get their missing handlers' deliveries in
+     * two more statements. Two transactions that append keys in opposite order across several calls can
+     * still deadlock (40P01); the database rolls one back and the caller retries.
      * A duplicate event id still consumes a sequence number; gaps are harmless
      * because only the order of sequences matters.
      */
     append(transaction: TTransaction, entries: readonly AppendEntry[], now: Date): Promise<AppendResult>;
     /**
-     * Leases up to `limit` due deliveries with `FOR UPDATE SKIP LOCKED`. The fast
-     * statement examines the first due deliveries; only when they are mostly
-     * blocked followers of busy keys does a second statement look at the heads of
-     * all keys. See {@link PostgresStatements.claim} for why that keeps a
-     * (handler, key) strictly one-at-a-time and in order.
+     * Claims up to `limit` due deliveries, normally with one statement
+     * ({@link PostgresStatements.claimLanes}): from the lanes this owner already holds, then from free lanes
+     * it takes in the same statement, recording the batch in the lane rows. A claim that would have to take
+     * over a lane whose previous holder still runs deliveries under an expired lease continues in a
+     * transaction that charges their lost attempts first, taking free lanes a few at a time (4, 8, 16, ...);
+     * so does a claim whose statement kept seeing a lane it holds change under it, and one that came up
+     * short with more free lanes left than it looked at. The step that fails after
+     * the first one has recorded deliveries returns those instead of failing: a recorded delivery nobody
+     * received would be held for a whole lease. See {@link PostgresStatements.claim} for the rules a delivery
+     * must satisfy.
      */
     claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
-    extendLease(lease: LeaseReference, leaseExpiresAt: Date, now: Date): Promise<boolean>;
+    extendLease(lease: LeaseReference, leaseExpiresAt: Date): Promise<boolean>;
     complete(lease: LeaseReference, now: Date, transaction?: TTransaction): Promise<boolean>;
+    completeMany(leases: readonly LeaseReference[], now: Date): Promise<boolean[]>;
     reschedule(lease: LeaseReference, availableAt: Date, error: ErrorInfo, now: Date): Promise<boolean>;
     bury(lease: LeaseReference, error: ErrorInfo, now: Date): Promise<boolean>;
     /** Returns a leased delivery to pending, due now, without counting the attempt. */
     release(lease: LeaseReference, now: Date): Promise<boolean>;
+    /**
+     * Calls `listener` soon after a transaction that published deliveries due at once commits, in any
+     * process: `append` sends one `pg_notify` per call (merged per transaction, none for delayed
+     * deliveries), and this listens with `LISTEN` on a connection of its own, opened with the settings of
+     * the store's pool (one connection more than the pool's `max`). A lost connection is replaced after a
+     * second. Resolves with `undefined` for a store built on an `executor`, which has no connection of its
+     * own to listen on, and with `wakeUp: 'poll'`: polling then finds new deliveries (and the bus still
+     * wakes its own dispatcher).
+     */
+    watchNewDeliveries(listener: () => void): Promise<(() => Promise<void>) | undefined>;
+    /** Frees the lanes `leaseOwner` holds that run no delivery, so other workers need not wait for the lease to expire. */
+    relinquish(leaseOwner: string): Promise<void>;
     listDeliveries(query: DeliveryQuery): Promise<DeliveryRecord[]>;
     requeue(deliveryIds: readonly string[], now: Date): Promise<number>;
     /**
@@ -188,4 +289,4 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
     close(): Promise<void>;
 }
 
-export { PgExecutor, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresRow, type PostgresSchemaOptions, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };