queen-mq 1.2.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 
 [![npm](https://img.shields.io/npm/v/queen-mq.svg)](https://www.npmjs.com/package/queen-mq)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
-[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Node](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
 
 [Quick Start](#quick-start) • [Complete Guide](client-v2/README.md) • [Examples](#examples) • [API Reference](#api-reference)
 
@@ -16,7 +16,7 @@
 
 ## What is Queen MQ?
 
-Queen MQ is a PostgreSQL-backed message queue system with a powerful feature set:
+Queen MQ is a partitioned message queue broker that keeps its state in its own replicated log, with a powerful feature set:
 
 - **FIFO Partitions** - Unlimited ordered partitions within queues
 - **Consumer Groups** - Kafka-style consumer groups for scalability
@@ -40,7 +40,7 @@ This client provides a fluent, promise-based API for Node.js applications.
 npm install queen-mq
 ```
 
-**Requirements:** Node.js 22+
+**Requirements:** Node.js 24+
 
 ---
 
@@ -133,20 +133,21 @@ await queen.queue('emails')
 
 ### Subscription Modes
 
-Control whether consumer groups process historical messages:
+Control whether consumer groups process historical messages. A group's mode is fixed the first
+time the group pops a queue; unset, it is the broker's `DEFAULT_SUBSCRIPTION_MODE`, which is `new`.
 
 ```javascript
-// Default: Process ALL messages (including backlog)
-await queen.queue('events')
-  .group('batch-analytics')
-  .consume(async (message) => { /* all messages */ })
-
-// Skip history, only new messages
+// Default ('new'): start where the group first pops, skip what is already there
 await queen.queue('events')
   .group('realtime-monitor')
-  .subscriptionMode('new')
   .consume(async (message) => { /* new only */ })
 
+// Process ALL messages, including the backlog
+await queen.queue('events')
+  .group('batch-analytics')
+  .subscriptionMode('all')
+  .consume(async (message) => { /* all messages */ })
+
 // Start from specific timestamp
 await queen.queue('events')
   .group('replay')
@@ -278,6 +279,51 @@ await queen.queue('tasks')
   })
 ```
 
+**When the handler throws**, the consumer nacks what it was given (the message, or the whole batch)
+and keeps consuming. The broker redelivers it, and moves it to the dead letter queue once the queue's
+`retryLimit` is spent. With `.each()`, the rest of the popped batch is dropped after a nack: the
+broker redelivers it too.
+
+This is the same with `.autoAck(false)`. That setting hands the *success* path to your handler (it
+acks), not the failure path: a handler that threw never got to settle its messages. A message your
+handler acked before throwing is not affected: it is already settled, so the broker refuses
+its nack.
+
+To handle failures yourself, add `.onError(async (message, error) => { ... })`. The error then never
+reaches the consumer, nothing is nacked for you, and the message is yours to ack, nack, or leave
+until its lease expires. To stop consuming on an error, abort the `signal` you passed to
+`consume(handler, { signal })` from inside `onError`.
+
+```javascript
+// autoAck(false): the handler acks. A throw before the ack is nacked and retried.
+await queen.queue('tasks')
+  .group('workers')
+  .autoAck(false)
+  .each()                  // one message per call; without it the handler gets the popped array
+  .consume(async (message) => {
+    await processTask(message.data)
+    await queen.ack(message, true)
+  })
+
+// Your own failure policy: nack, then stop consuming.
+const stop = new AbortController()
+await queen.queue('tasks')
+  .group('workers')
+  .autoAck(false)
+  .each()
+  .consume(async (message) => {
+    await processTask(message.data)
+    await queen.ack(message, true)
+  }, { signal: stop.signal })
+  .onError(async (message, error) => {
+    await queen.ack(message, false, { error: error.message })
+    stop.abort()
+  })
+```
+
+Earlier versions stopped the consumer on a throw under `.autoAck(false)`: `consume()` rejected after
+the first failure, and the message stayed leased until its lease expired.
+
 ### Pop Messages (On-Demand Processing)
 
 ```javascript
@@ -494,9 +540,9 @@ Both surfaces are **always there**. There is nothing to enable: kv and timers ar
 broker the way push and pop are, on every cell that runs it. There is no capability to probe and
 no 404 that means "this cell does not have the feature" — a 404 from these routes is a bug.
 
-What an operator can still do is **pause** them, with the runtime kill switch in
-`queen.system_state` (`kv_enabled`, `timers_schedule_enabled`, `timers_fire_enabled`) — the same
-class of lever as maintenance mode, pulled live during an incident and expected to be pulled back.
+What an operator can still do is **pause** them, with the broker's runtime kill switches
+(`kv_enabled`, `timers_schedule_enabled`, `timers_fire_enabled`) — a lever pulled live during an
+incident and expected to be pulled back.
 A paused surface answers `503` with `Retry-After` and `error: 'kv_disabled'` / `'timers_disabled'`,
 which this client retries like any other 5xx. Inside a transaction it is a `403` on the `kv` or
 `timers` rider instead, so a bundle holding messages does not spin forever on a paused cell.
@@ -581,7 +627,7 @@ the retry budget.
 
 Durations that can be sub-second are in **milliseconds** (`delayMs`), the ones that cannot are in
 **seconds** (`ttlSeconds`). Only relative delays exist, because there is one clock and it is the
-database's. A delay in the past is legal and fires on the first cycle.
+broker's. A delay in the past is legal and fires on the first cycle.
 
 `deliverAt` is **"not before"**, never "exactly at".
 
@@ -768,6 +814,11 @@ await queen.ack(message, false, { error: 'reason' })
 await queen.ack([msg1, msg2], true)  // Batch ack
 ```
 
+An ack is judged against the lease of the consumer group the message was popped under. `queen.ack()`
+and `transaction().ack()` take that group from the message (`message.consumerGroup`, which every pop
+returns) unless you name one: `{ group }` on `queen.ack()`, `{ consumerGroup }` or `{ group }` on a
+transaction. A batch ack carries a single group, so `queen.ack()` throws on a batch that mixes groups.
+
 ### Transactions
 
 ```javascript
@@ -816,11 +867,14 @@ await queen.timer(q).list({ limit: 50, after })                  // {rows, trunc
 ### Lease Renewal
 
 ```javascript
-await queen.renew(message)
-await queen.renew([msg1, msg2, msg3])
+await queen.renew(message)              // {leaseId, success, newExpiresAt, renewed}
+await queen.renew([msg1, msg2, msg3])   // one result per distinct lease
 await queen.queue('q').renewLease(true, 60000).consume(async (msg) => { /* auto-renew */ })
 ```
 
+`success: false` (with an `error`) means nothing was renewed: the lease expired, an ack or nack
+already released it, or it never existed. The messages it covered may already be redelivered.
+
 ### Buffering
 
 ```javascript
@@ -970,4 +1024,3 @@ const messages: Message<OrderData>[] = await queen.queue('orders').pop()
 ## License
 
 Apache 2.0 - See [LICENSE.md](../LICENSE.md)
-

package/client-v2/Queen.js

@@ -15,6 +15,7 @@ import { StreamBuilder } from './stream/StreamBuilder.js'
 import { StreamConsumer } from './stream/StreamConsumer.js'
 import { Admin } from './admin/Admin.js'
 import { popAutopilotDisabledByEnv } from './utils/autopilot.js'
+import { consumerGroupOf, sharedConsumerGroupOf } from './utils/consumerGroup.js'
 import { CLIENT_DEFAULTS } from './utils/defaults.js'
 import { validateUrl, validateUrls } from './utils/validation.js'
 import * as logger from './utils/logger.js'
@@ -28,9 +29,9 @@ const CLOSE_FLUSH_DEADLINE_MILLIS = 30000
 // Both /api/v1/ack and /api/v1/ack/batch respond with a top-level JSON array,
 // one item per acknowledgment in request order:
 //   [{index, transactionId, success, error, queueName, partitionName, leaseReleased, dlq}]
-// (see queen.ack_messages_v2 / routes/ack.cpp). A rejected ack/nack (e.g.
-// "Invalid or expired lease") still arrives as HTTP 200 with success=false on
-// the item, so the per-item flag is the only signal that the broker accepted it.
+// A rejected ack/nack (e.g. "Invalid or expired lease") still arrives as HTTP
+// 200 with success=false on the item, so the per-item flag is the only signal
+// that the broker accepted it.
 
 function normalizeAckItem(item, index) {
   if (item === null || typeof item !== 'object') {
@@ -61,6 +62,30 @@ function parseAckResults(result, expected) {
   throw new Error('Unexpected ack response format: missing per-item result array')
 }
 
+// POST /api/v1/lease/:leaseId/extend answers HTTP 200 whether or not anything
+// was renewed, so `success` in the body is the only signal:
+//   1.x and 2.x brokers: {leaseId, success, renewed, newExpiresAt, expiresAt, lease_expires_at}
+//   the C++ broker:      [{index, leaseId, success, error, expiresAt}]
+// success:false means the lease is gone (expired, released by an ack or nack,
+// or never existed): nothing was extended, and the messages it covered can
+// already be on their way to another consumer.
+function parseRenewResult(result, leaseId) {
+  const item = Array.isArray(result) ? result[0] : result
+  if (item === null || typeof item !== 'object') {
+    return { leaseId, success: false, newExpiresAt: null, error: 'Unexpected lease renewal response' }
+  }
+  const newExpiresAt = item.newExpiresAt ?? item.expiresAt ?? item.lease_expires_at ?? null
+  const success = typeof item.success === 'boolean' ? item.success : newExpiresAt !== null
+  const outcome = { leaseId, success, newExpiresAt }
+  if (typeof item.renewed === 'number') outcome.renewed = item.renewed
+  if (!success) {
+    outcome.error = typeof item.error === 'string' && item.error.length > 0
+      ? item.error
+      : 'Lease not renewed: it expired, was released by an ack or nack, or does not exist'
+  }
+  return outcome
+}
+
 export class Queen {
   #httpClient
   #bufferManager
@@ -438,11 +463,15 @@ export class Queen {
         })
       }
 
+      // The group the messages were popped under unless the caller names one:
+      // the lease every ack has to match belongs to it (utils/consumerGroup.js).
+      const consumerGroup = context.group || sharedConsumerGroupOf(message)
+
       // Call batch ack endpoint
       try {
         const result = await this.#httpClient.post('/api/v1/ack/batch', {
           acknowledgments,
-          consumerGroup: context.group || null
+          consumerGroup
         })
 
         const results = parseAckResults(result, acknowledgments.length)
@@ -487,7 +516,9 @@ export class Queen {
       partitionId,
       status: statusStr,
       error: context.error || null,
-      consumerGroup: context.group || null
+      // The group the message was popped under unless the caller names one
+      // (utils/consumerGroup.js).
+      consumerGroup: context.group || consumerGroupOf(message)
     }
 
     if (leaseId) body.leaseId = leaseId
@@ -529,8 +560,8 @@ export class Queen {
     }
 
     // Dedupe: with v4 multi-partition pop, all messages in one batch share
-    // the same leaseId (one renew_lease_v2 call extends every claimed
-    // partition_consumers row). Without this, callers passing the full
+    // the same leaseId (one renew call extends the lease of every claimed
+    // partition). Without this, callers passing the full
     // messages array would issue N redundant identical HTTP calls.
     leaseIds = [...new Set(leaseIds)]
 
@@ -545,12 +576,13 @@ export class Queen {
     for (const leaseId of leaseIds) {
       try {
         const result = await this.#httpClient.post(`/api/v1/lease/${leaseId}/extend`, {})
-        results.push({
-          leaseId,
-          success: true,
-          newExpiresAt: result.leaseId ? result.newExpiresAt : result.lease_expires_at
-        })
-        logger.log('Queen.renew', { leaseId, success: true })
+        const outcome = parseRenewResult(result, leaseId)
+        results.push(outcome)
+        if (outcome.success) {
+          logger.log('Queen.renew', { leaseId, success: true, renewed: outcome.renewed })
+        } else {
+          logger.error('Queen.renew', { leaseId, error: outcome.error })
+        }
       } catch (error) {
         results.push({ leaseId, success: false, error: error.message })
         logger.error('Queen.renew', { leaseId, error: error.message })

package/client-v2/README.md

@@ -60,7 +60,7 @@ When connecting to multiple Queen servers, you can choose how requests are distr
 
 #### Affinity Mode (Recommended for Production)
 
-Uses consistent hashing with virtual nodes to route consumer groups to the same backend server. This optimizes database queries by consolidating poll intentions.
+Uses consistent hashing with virtual nodes to route consumer groups to the same backend server.
 
 ```javascript
 const queen = new Queen({
@@ -444,28 +444,31 @@ When a consumer group first subscribes to a queue, should it process **all histo
 - Join a stream at a specific point in time
 - Skip historical data for new analytics consumers
 
-### Default Behavior (All Messages)
+### Default Behavior (New Messages)
 
-By default, consumer groups start from the **beginning** and process all messages:
+By default, a consumer group starts where it first pops the queue and skips the messages that were
+already there. That default is the broker's `DEFAULT_SUBSCRIPTION_MODE`, which is `new`:
 
 ```javascript
-// This consumer group gets ALL messages, including historical ones
+// This consumer group gets only messages that arrive after it first pops
 await queen
   .queue('events')
   .group('new-analytics')
+  .each()
   .consume(async (message) => {
     console.log('Processing:', message.data)
   })
 ```
 
-**Server Default:** The server can be configured to change this default behavior:
+To process the backlog too, ask for it with `.subscriptionMode('all')`, or start the broker with
+`DEFAULT_SUBSCRIPTION_MODE=all` to make that the default for every new group:
 ```bash
-# Make all new consumer groups skip history by default
-export DEFAULT_SUBSCRIPTION_MODE="new"
-./bin/queen-server
+export DEFAULT_SUBSCRIPTION_MODE="all"
+./bin/queen
 ```
 
-When `DEFAULT_SUBSCRIPTION_MODE="new"` is set, new consumer groups automatically skip historical messages unless you explicitly override with `.subscriptionMode('all')`.
+The mode is stored with the group the first time it pops; changing the default later does not move
+an existing group.
 
 ### Subscription Mode: 'new'
 
@@ -1004,8 +1007,9 @@ const message = messages[0]
 
 // Start long processing
 const timer = setInterval(async () => {
-  await queen.renew(message)  // Extend lease
-  console.log('Lease renewed!')
+  const { success, newExpiresAt, error } = await queen.renew(message)  // Extend lease
+  if (success) console.log('Lease renewed until', newExpiresAt)
+  else console.warn('Lease lost:', error)   // expired or already released: it will be redelivered
 }, 30000)  // Every 30 seconds
 
 try {
@@ -1432,6 +1436,16 @@ await queen.queue('reports').consume(async (msg) => {
 
 Sometimes you need more control over what happens when messages succeed or fail.
 
+### What a Throw Does
+
+Without callbacks, a handler that throws gets what it was given nacked (the message with `.each()`,
+otherwise the whole popped batch), and the consumer keeps going. The broker redelivers it, and moves
+it to the DLQ once the queue's `retryLimit` is spent. That holds with `.autoAck(false)` too: there
+your handler acks on success, but a handler that threw never got to settle anything.
+
+With `.onError()` the failure is yours: nothing is nacked on your behalf. Ack, nack or DLQ the
+message in the callback, or it stays leased until its lease expires.
+
 ### Success Callback
 
 ```javascript
@@ -1457,6 +1471,7 @@ await queen
   .onError(async (message, error) => {
     console.error('Failed:', error.message)
     // Log to external service, send alert, etc.
+    await queen.ack(message, false)   // with onError, nothing is nacked for you
   })
 ```
 

package/client-v2/admin/Admin.js

@@ -359,44 +359,6 @@ export class Admin {
     return this.#httpClient.get('/metrics')
   }
 
-  /**
-   * Get push maintenance mode status
-   * @returns {Promise<object>}
-   */
-  async getMaintenanceMode() {
-    logger.log('Admin.getMaintenanceMode', {})
-    return this.#httpClient.get('/api/v1/system/maintenance')
-  }
-
-  /**
-   * Set push maintenance mode
-   * @param {boolean} enabled - Enable or disable maintenance mode
-   * @returns {Promise<object>}
-   */
-  async setMaintenanceMode(enabled) {
-    logger.log('Admin.setMaintenanceMode', { enabled })
-    return this.#httpClient.post('/api/v1/system/maintenance', { enabled })
-  }
-
-  /**
-   * Get pop maintenance mode status
-   * @returns {Promise<object>}
-   */
-  async getPopMaintenanceMode() {
-    logger.log('Admin.getPopMaintenanceMode', {})
-    return this.#httpClient.get('/api/v1/system/maintenance/pop')
-  }
-
-  /**
-   * Set pop maintenance mode
-   * @param {boolean} enabled - Enable or disable pop maintenance mode
-   * @returns {Promise<object>}
-   */
-  async setPopMaintenanceMode(enabled) {
-    logger.log('Admin.setPopMaintenanceMode', { enabled })
-    return this.#httpClient.post('/api/v1/system/maintenance/pop', { enabled })
-  }
-
   /**
    * Get system metrics (CPU, memory, connections, etc.)
    * @param {object} params - Query parameters (from, to, etc.)
@@ -419,15 +381,6 @@ export class Admin {
     return this.#httpClient.get(`/api/v1/analytics/worker-metrics${queryString}`)
   }
 
-  /**
-   * Get PostgreSQL statistics
-   * @returns {Promise<object>}
-   */
-  async getPostgresStats() {
-    logger.log('Admin.getPostgresStats', {})
-    return this.#httpClient.get('/api/v1/analytics/postgres-stats')
-  }
-
   // ===========================
   // Helper Methods
   // ===========================

package/client-v2/builders/QueueBuilder.js

@@ -16,6 +16,14 @@ import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/confla
 import { popSizing, parseAutopilotDecision } from '../utils/autopilot.js'
 import * as logger from '../utils/logger.js'
 
+// Per-item push statuses that mean the broker took the message: `queued`
+// (stored), and `buffered` (a 1.x broker wrote it to its failover file and
+// replays it into storage itself). Every other status is a rejection: `error`
+// from a 2.x broker, which carries no per-item message, and `failed` from a
+// 1.x broker, which does. Unknown statuses count as rejections too: a status
+// this client cannot read is not a message it can report as stored.
+const ACCEPTED_PUSH_STATUSES = new Set(['queued', 'buffered'])
+
 export class QueueBuilder {
   #queen
   #httpClient
@@ -849,24 +857,40 @@ class PushBuilder {
         for (let i = 0; i < results.length; i++) {
           const result = results[i]
           const originalItem = this.#formattedItems[i]
+          const status = result && typeof result === 'object' ? result.status : undefined
 
-          if (result.status === 'duplicate') {
+          if (status === 'duplicate') {
             duplicates.push({ ...originalItem, result })
-          } else if (result.status === 'failed') {
-            failed.push({ ...originalItem, result, error: result.error })
-          } else if (result.status === 'queued') {
+          } else if (ACCEPTED_PUSH_STATUSES.has(status)) {
             successful.push({ ...originalItem, result })
+          } else {
+            const error = result && typeof result.error === 'string' && result.error.length > 0
+              ? result.error
+              : `push rejected by the broker (item status: ${status === undefined ? 'missing' : JSON.stringify(status)})`
+            failed.push({ ...originalItem, result, error })
           }
         }
 
+        // One error for the whole call, built once so the callback and the
+        // throw describe the failure the same way. `results` is the broker's
+        // per-item answer in input order: the items that did go through are
+        // in it too, which is what a caller needs to retry only the rest.
+        let failure = null
+        if (failed.length > 0) {
+          failure = new Error(failed.length === 1
+            ? failed[0].error
+            : `${failed.length} of ${results.length} pushed items rejected: ${failed[0].error}`)
+          failure.results = results
+          logger.error('PushBuilder.execute', { status: 'failed', count: failed.length, total: results.length, error: failed[0].error })
+        }
+
         // Call appropriate callbacks
         if (duplicates.length > 0 && this.#onDuplicateCallback) {
           await this.#onDuplicateCallback(duplicates, new Error('Duplicate transaction IDs detected'))
         }
 
-        if (failed.length > 0 && this.#onErrorCallback) {
-          const error = new Error(failed[0].error || 'Push failed')
-          await this.#onErrorCallback(failed, error)
+        if (failure && this.#onErrorCallback) {
+          await this.#onErrorCallback(failed, failure)
         }
 
         if (successful.length > 0 && this.#onSuccessCallback) {
@@ -874,9 +898,8 @@ class PushBuilder {
         }
 
         // Only throw if no error callback is defined
-        if (failed.length > 0 && !this.#onErrorCallback) {
-          logger.error('PushBuilder.execute', { status: 'failed', count: failed.length })
-          throw new Error(failed[0].error || 'Push failed')
+        if (failure && !this.#onErrorCallback) {
+          throw failure
         }
 
         logger.log('PushBuilder.execute', { status: 'success', successful: successful.length, duplicates: duplicates.length, failed: failed.length })

package/client-v2/builders/TimerBuilder.js

@@ -24,8 +24,8 @@
  *    bundle's fate; see TransactionBuilder, which says so where it happens.)
  *
  * 2. ONLY RELATIVE DURATIONS, IN MILLISECONDS (§4.2, §20.6). `delayMs`, never
- *    `delaySeconds` and never an absolute instant: `deliver_at` is computed in
- *    Postgres, so there is ONE clock and no broker's skew can enter. The rule
+ *    `delaySeconds` and never an absolute instant: `deliver_at` is computed on
+ *    the broker's clock, so there is ONE clock and no client's skew can enter. The rule
  *    of the product is "durations that can be sub-second are in milliseconds,
  *    the ones that cannot are in seconds" -- a 250 ms retry backoff is a real
  *    and central use of timers, which is why this wire is the millisecond one.

package/client-v2/builders/TransactionBuilder.js

@@ -30,6 +30,7 @@ import { generateUUID } from './QueueBuilder.js'
 import { isValidUUID } from '../utils/validation.js'
 import { kvOp, materializeKvOp } from '../kv/Kv.js'
 import { TimerBuilder } from './TimerBuilder.js'
+import { consumerGroupOf } from '../utils/consumerGroup.js'
 
 export class TransactionBuilder {
   #httpClient
@@ -46,10 +47,21 @@ export class TransactionBuilder {
     this.#httpClient = httpClient
   }
 
+  /**
+   * Ack popped messages as part of this transaction.
+   *
+   * The consumer group defaults to the one each message was popped under
+   * (`message.consumerGroup`, which every pop answers with), because the lease
+   * an ack has to match belongs to that group: an ack that names no group is
+   * judged in queue mode, and a message popped by a group then fails with
+   * `rejected_ack`. Pass `{ consumerGroup }` (or `{ group }`, the key
+   * `queen.ack()` takes) to override it.
+   */
   ack(messages, status = 'completed', context = {}) {
     const msgs = Array.isArray(messages) ? messages : [messages]
-    
-    logger.log('TransactionBuilder.ack', { count: msgs.length, status, consumerGroup: context.consumerGroup })
+    const explicitGroup = context.consumerGroup || context.group || null
+
+    logger.log('TransactionBuilder.ack', { count: msgs.length, status, consumerGroup: explicitGroup })
 
     msgs.forEach(msg => {
       const transactionId = typeof msg === 'string' ? msg : (msg.transactionId || msg.id)
@@ -72,9 +84,18 @@ export class TransactionBuilder {
         status
       }
 
-      // Add consumerGroup if provided in context
-      if (context.consumerGroup) {
-        operation.consumerGroup = context.consumerGroup
+      const consumerGroup = explicitGroup || consumerGroupOf(msg)
+      if (consumerGroup) {
+        operation.consumerGroup = consumerGroup
+      }
+
+      // Each ack names its own lease. A Queen 2 broker fences an ack with the
+      // lease the operation carries, and lends it one from requiredLeases only
+      // when the bundle names a single lease: in a bundle spanning two leases,
+      // an ack without its own would be applied whoever holds its partition
+      // now. 1.x brokers read the operation's lease before requiredLeases too.
+      if (leaseId) {
+        operation.leaseId = leaseId
       }
 
       this.#operations.push(operation)
@@ -204,7 +225,7 @@ export class TransactionBuilder {
    *
    * `putIfAbsent` with `required:true`, so a marker that already exists ABORTS
    * the transaction: the push and the ack roll back together with it. That is
-   * what makes "the email is sent exactly once" a property of the database
+   * what makes "the email is sent exactly once" a property of the broker
    * rather than a hope about redelivery.
    *
    * The verdict is RETURNED by `commit()`, not thrown -- see there.
@@ -303,9 +324,14 @@ export class TransactionBuilder {
 
         logger.error('TransactionBuilder.commit', { error: result.error, reason: result.reason })
         const error = new Error(result.error || 'Transaction failed')
-        // The closed-taxonomy code travels ON the error, so no caller ever has
-        // to match the message: bad_request | duplicate | ack_rejected |
-        // timer_horizon_exceeded | payload_too_large | misaligned | db_error.
+        // The broker's reason code travels ON the error, so no caller ever has
+        // to match the message. The ones worth branching on from a 2.x broker:
+        // bad_request, duplicate (a pushed transactionId is already stored),
+        // rejected_ack (an acked message is no longer leased by this worker, or
+        // was popped under a different consumer group than the ack names), and
+        // too_large. A 1.x broker spells the ack one ack_rejected, and also
+        // sends timer_horizon_exceeded, payload_too_large, misaligned and
+        // db_error.
         if (result.reason) error.reason = result.reason
         error.result = result
         throw error