queen-mq 1.3.0 → 2.0.0

package/client-v2/utils/consumerGroup.js

@@ -0,0 +1,54 @@
+/**
+ * The consumer group a popped message belongs to.
+ *
+ * Every pop answers each message with the group it was claimed under
+ * (`consumerGroup`), and the lease an ack has to match belongs to that group.
+ * An ack that names no group is judged in queue mode, so a message popped by a
+ * group and acked without one is refused: `rejected_ack` from a transaction,
+ * `invalid or expired lease` from /ack. Reading the group off the message is
+ * what lets `ack(message)` work without the caller repeating `.group(...)`.
+ */
+
+/** The broker's name for "no consumer group" (queue mode). */
+export const QUEUE_MODE_GROUP = '__QUEUE_MODE__'
+
+/**
+ * The group to send with an ack of `message`, or null for queue mode.
+ *
+ * Null for queue mode on purpose: an ack with no group IS a queue-mode ack, so
+ * leaving the key out keeps those requests byte-identical to what this client
+ * always sent. Also null for anything that is not a popped message (a bare
+ * transactionId string, a hand-built `{transactionId, partitionId}`).
+ */
+export function consumerGroupOf(message) {
+  if (message === null || typeof message !== 'object') return null
+  const group = message.consumerGroup
+  if (typeof group !== 'string' || group.length === 0 || group === QUEUE_MODE_GROUP) return null
+  return group
+}
+
+/**
+ * The one group to send with a batch ack of `messages`, or null for queue mode.
+ *
+ * /api/v1/ack/batch carries ONE consumer group for the whole request, so a
+ * batch whose messages were popped under different groups cannot be expressed
+ * as one call: it throws rather than ack some of them under the wrong group.
+ * Messages that state no group (hand-built ones) take whatever the others say.
+ */
+export function sharedConsumerGroupOf(messages) {
+  const named = new Set()
+  for (const message of messages) {
+    if (message !== null && typeof message === 'object' &&
+        typeof message.consumerGroup === 'string' && message.consumerGroup.length > 0) {
+      named.add(message.consumerGroup)
+    }
+  }
+  if (named.size > 1) {
+    throw new Error(
+      `Cannot ack messages from different consumer groups in one call (${[...named].join(', ')}): ` +
+      'a batch ack carries one consumer group. Ack each group separately, or pass { group }.'
+    )
+  }
+  const [group] = named
+  return group && group !== QUEUE_MODE_GROUP ? group : null
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "type": "module",
-  "description": "Partitioned message queue on PostgreSQL — broker client + fluent streaming SDK (windows, joins, gates) in one package",
+  "description": "Partitioned message queue on a replicated broker log — broker client + fluent streaming SDK (windows, joins, gates) in one package",
   "main": "client-v2/index.js",
   "scripts": {
-    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/autopilot-unit/autopilotWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js && node test-v2/run.js human",
-    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/autopilot-unit/autopilotWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js",
+    "test": "npm run test:unit && node test-v2/run.js human",
+    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/streams-unit/gate.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/http-unit/pushStatus.test.js test-v2/http-unit/renew.test.js test-v2/consumer-unit/handlerError.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/autopilot-unit/autopilotWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js test-v2/runner-unit/fatalExit.test.js",
     "test:unit:e2e": "node --test test-v2/streams-unit/e2e.test.js",
     "test:integration": "node test-v2/run.js human",
     "test:streams": "node test-v2/run.js stream",
@@ -19,12 +19,11 @@
   ],
   "dependencies": {
     "axios": "^1.12.2",
-    "pg": "^8.16.3",
     "undici": "^6.21.0",
     "uuid": "^13.0.0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "author": "Smartness",
   "license": "Apache-2.0",
@@ -39,8 +38,6 @@
   "keywords": [
     "message-queue",
     "queue",
-    "postgres",
-    "postgresql",
     "broker",
     "message-queue-system",
     "fifo",

package/test-v2/_kvtimers.js

@@ -19,8 +19,9 @@
  * says nothing, and that was only tolerable while the 404 was legitimate.
  *
  * What still exists is the operator's RUNTIME kill switch (`kv_enabled`,
- * `timers_schedule_enabled`, `timers_fire_enabled` in `queen.system_state`) --
- * the maintenance-mode lever, pulled live during an incident. It answers 503
+ * `timers_schedule_enabled`, `timers_fire_enabled`, set through
+ * `POST /api/v1/system/kv-timers`) --
+ * a lever pulled live during an incident. It answers 503
  * with `Retry-After` on the kv/timer routes and 403 on a `kv`/`timers` rider
  * inside a transaction, never 404. If a run here ever goes red against that,
  * the switch is down on the rig and somebody pulled it; it is not something
@@ -35,20 +36,18 @@ export const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms))
 /**
  * Poll a queue until `match` accepts a message, or the deadline passes.
  *
- * WHY THIS IS A POLL AND NOT A LONG POLL, MEASURED ON A REAL RIG. A timer's
- * delivery is committed by the sweeper INSIDE PostgreSQL
- * (`log_timers_fire_v1` = DELETE + push in one transaction), so it does not
- * pass through the broker's push handler and the destination partition is not
- * marked ready in that broker's hot list. A consumer therefore sees the
- * message only at the next hot-list reseed: on a default broker
- * (QUEEN_HOTLIST_RESEED_MS = 30000) a timer scheduled for +300 ms was measured
- * arriving at +30.7 s, and a 20 s long poll timed out with the message already
- * committed in the log.
+ * WHY THIS IS A POLL AND NOT A LONG POLL. A timer's delivery is not a client
+ * push: the broker's own fire step appends it (the leader plans due timers in
+ * a step of its own loop, each fire's message append and timer removal in one
+ * entry), so it never passes through the push handler, and when it becomes
+ * visible is bounded by that step, not by the delay under test. A short poll
+ * with a deadline asserts the arrival without depending on whether, or when,
+ * a parked long poll is woken by a fire.
  *
  * That is a broker property, not a client one, and it is why these tests
  * assert ARRIVAL and never latency: `deliverAt` is "not before", never
- * "exactly at". The deadline here is generous on purpose -- it is sized
- * against the reseed period, not against the delay under test.
+ * "exactly at". The deadline here is generous on purpose -- it is sized for a
+ * slow rig, not against the delay under test.
  */
 export async function popUntil(client, queueName, match, timeoutMs = 60000) {
   const deadline = Date.now() + timeoutMs

package/test-v2/ackwindow.js

@@ -1,33 +1,21 @@
 /**
- * Ack-window honesty tests (2026-07-30).
+ * Ack-window honesty test (2026-07-30).
  *
- * queen.log_ack_by_hash_v1 resolves txn hashes through the queen.log_txns
- * sidecar, which is purged on its own clock (GREATEST(dedup_window,
- * completed_retention, 900s)). A hash that cannot be resolved — purged row,
- * or a transactionId that never existed — is correctly NOT acked (the cursor
- * stops, frames redeliver: redelivery over loss). The BUG these tests pin:
- * the broker reported those items as success=true (they appear in neither
- * noopHashes nor staleHashes), so the client believed the ack landed while
- * the cursor never moved — a silent redelivery livelock, and a nack/dlq in
- * that state could never dead-letter its poison message.
+ * An ack whose transactionId the broker cannot resolve to a message of that
+ * partition (here: one that was never pushed) is correctly NOT applied: the
+ * cursor stays put and the real messages redeliver (redelivery over loss). The
+ * BUG this test pins: the broker reported such items as success=true, so the
+ * client believed the ack landed while the cursor never moved -- a silent
+ * redelivery livelock, and a nack/dlq in that state could never dead-letter
+ * its poison message.
  *
  * Expected contract (post-fix): unresolvable items come back success=false
- * with an explicit "unresolvable" error, and the cursor is untouched.
- *
- * Companion test: emptyPartitionCursorSealsAfterRetention pins the empty-
- * partition cursor seal in log_pop_v1 (the Rust port of the C++
- * pop_unified_batch_v4 starvation fix): a partition whose segments were all
- * removed by retention must stop being "phantom pending" after one pop.
+ * with an explicit "unresolvable" error, and the lease survives for the real
+ * batch.
  *
  * Run: node run.js ackUnknownTxnMustFail
- *      node run.js ackAfterHashPurgeMustFailExplicitly
- *      node run.js emptyPartitionCursorSealsAfterRetention
  */
 
-import { dbPool } from './run.js'
-
-const TENANT = '00000000-0000-0000-0000-000000000001'
-
 function sleep(ms) { return new Promise(r => setTimeout(r, ms)) }
 
 async function popRetry(client, queue, { batch = 3, group = null, partition = null, tries = 30, mode = null } = {}) {
@@ -43,35 +31,9 @@ async function popRetry(client, queue, { batch = 3, group = null, partition = nu
     return []
 }
 
-async function partitionRow(queue, partition = 'Default') {
-    const r = await dbPool.query(
-        `SELECT p.id::text AS id, p.last_offset::bigint AS last_offset, p.log_start::bigint AS log_start
-         FROM queen.log_partitions p
-         JOIN queen.queues lq ON lq.id = p.queue_id
-         WHERE lq.name = $1 AND p.name = $2 AND lq.tenant_id = $3::uuid`,
-        [queue, partition, TENANT])
-    return r.rows[0] || null
-}
-
-async function committedOf(partitionId, group) {
-    const r = await dbPool.query(
-        `SELECT c.committed::bigint AS committed FROM queen.log_consumers c
-         WHERE c.partition_id = $1::uuid AND c.consumer_group = $2`,
-        [partitionId, group])
-    return r.rows.length ? Number(r.rows[0].committed) : null
-}
-
-async function segmentCount(partitionId) {
-    const r = await dbPool.query(
-        `SELECT count(*)::int AS n FROM queen.log_segments WHERE partition_id = $1::uuid`,
-        [partitionId])
-    return r.rows[0].n
-}
-
 /**
- * Test A (wire-only): acking a transactionId that never existed must fail
- * explicitly, for both a completed ack and a failed nack. Today the broker
- * answers success=true for both.
+ * Wire-only: acking a transactionId that never existed must fail explicitly,
+ * for both a completed ack and a failed nack.
  */
 export async function ackUnknownTxnMustFail(client) {
     const queue = 'test-queue-v2-ackwindow-unknown'
@@ -121,145 +83,3 @@ export async function ackUnknownTxnMustFail(client) {
 
     return { success: true, message: 'unknown-txn ack and nack both rejected explicitly; real batch still ackable' }
 }
-
-/**
- * Test B (with SQL): the real-world shape — messages still delivered (segments
- * intact) but their log_txns hash rows purged. Per-message acks must fail
- * explicitly and the cursor must not move. Pre-fix: every ack reported
- * success=true while committed stayed put (silent livelock).
- */
-export async function ackAfterHashPurgeMustFailExplicitly(client) {
-    const queue = 'test-queue-v2-ackwindow-purged'
-    await client.queue(queue).create()
-    const txns = [1, 2, 3, 4, 5].map(n => `${queue}-tx-${n}`)
-    await client.queue(queue).partition('Default').push(
-        txns.map((t, i) => ({ data: { n: i }, transactionId: t })))
-
-    // Wait until the segments are visible, then purge the hash sidecar —
-    // exactly what log_txns_purge_step_v1 does after the window expires
-    // (the 900s floor makes the real purge untestable in-suite).
-    const part = await partitionRow(queue)
-    if (!part) return { success: false, message: 'partition row not found' }
-    for (let i = 0; i < 30 && (await segmentCount(part.id)) === 0; i++) await sleep(100)
-
-    const del = await dbPool.query(
-        `DELETE FROM queen.log_txns WHERE partition_id = $1::uuid`, [part.id])
-    if (del.rowCount === 0) return { success: false, message: 'no log_txns rows to purge — test setup broken' }
-
-    // Segments untouched: the messages still DELIVER.
-    const msgs = await popRetry(client, queue, { batch: 5 })
-    if (msgs.length !== 5) return { success: false, message: `expected 5 delivered messages after purge, got ${msgs.length}` }
-
-    // Per-message completed ack (the JS per-message consumer shape): the hash
-    // cannot resolve, so the honest answer is an explicit failure.
-    const r1 = await client.ack([msgs[0]], true)
-    const item1 = (r1.results || [])[0] || {}
-    if (item1.success !== false || !/unresolv/i.test(item1.error || '')) {
-        return { success: false, message: `BUG: ack with purged hash answered success=${item1.success}, error='${item1.error}'` }
-    }
-
-    // Nack of a purged-hash message: same — and pre-fix this also meant the
-    // poison could never reach the DLQ.
-    const r2 = await client.ack([msgs[1]], false)
-    const item2 = (r2.results || [])[0] || {}
-    if (item2.success !== false || !/unresolv/i.test(item2.error || '')) {
-        return { success: false, message: `BUG: nack with purged hash answered success=${item2.success}, error='${item2.error}'` }
-    }
-
-    // The cursor must not have moved (redelivery over loss — that part of the
-    // contract was always right; only the reporting lied).
-    const committed = await committedOf(part.id, '__QUEUE_MODE__')
-    if (committed !== -1) {
-        return { success: false, message: `cursor moved on unresolvable acks: committed=${committed}, expected -1` }
-    }
-
-    return { success: true, message: 'purged-hash ack and nack rejected explicitly, cursor untouched, messages still deliverable' }
-}
-
-/**
- * Test C (bug 2, with SQL): empty-partition cursor seal. A group consumes
- * part of a partition, retention then deletes ALL segments (time rule deletes
- * unconsumed data too): last_offset > committed with zero segments = a
- * phantom-pending row that used to stay a wildcard candidate forever and
- * pinned the empty-scan watermark at epoch. After the fix, one empty pop
- * seals committed to the partition's last_offset. A delayed-processing queue
- * pins the guard: segments EXIST but are deferred → no seal.
- */
-export async function emptyPartitionCursorSealsAfterRetention(client) {
-    const queue = 'test-queue-v2-ackwindow-seal'
-    const group = 'g-seal'
-    await client.queue(queue).config({ retentionEnabled: true, retentionSeconds: 1, leaseTime: 30 }).create()
-    await client.queue(queue).partition('Default').push(
-        [0, 1, 2, 3, 4, 5].map(n => ({ data: { n }, transactionId: `${queue}-tx-${n}` })))
-
-    // Consume + ack only the first two: committed lands at 1, the rest stays.
-    // First contact for g-seal, and the 6 messages are already pushed: the
-    // group has to ask for the backlog it is about to half-consume.
-    const first = await popRetry(client, queue, { batch: 2, group, mode: 'all' })
-    if (first.length !== 2) return { success: false, message: `expected 2 messages, got ${first.length}` }
-    const ackr = await client.ack(first, true, { group })
-    if (ackr.success !== true) return { success: false, message: `ack failed: ${ackr.error}` }
-
-    const part = await partitionRow(queue)
-    if (!part) return { success: false, message: 'partition row not found' }
-
-    // Retention (interval 2s in the harness, cutoff 1s) must delete ALL
-    // segments — the time rule ignores cursors.
-    let segs = -1
-    for (let i = 0; i < 60; i++) {
-        segs = await segmentCount(part.id)
-        if (segs === 0) break
-        await sleep(500)
-    }
-    if (segs !== 0) return { success: false, message: `retention never emptied the partition (segments=${segs})` }
-
-    const before = await committedOf(part.id, group)
-    const rowNow = await partitionRow(queue)
-    if (before === null) return { success: false, message: 'consumer row missing before the empty pop' }
-    if (before >= Number(rowNow.last_offset)) {
-        return { success: false, message: `setup broken: no phantom span (committed=${before}, last_offset=${rowNow.last_offset})` }
-    }
-
-    // ONE empty pop on the emptied partition must seal the cursor.
-    const empty = await client.queue(queue).partition('Default').group(group).batch(1).wait(false).pop()
-    if (empty && empty.length > 0) return { success: false, message: `expected an empty pop, got ${empty.length} messages` }
-
-    const after = await committedOf(part.id, group)
-    if (after !== Number(rowNow.last_offset)) {
-        return { success: false, message: `BUG: empty pop did not seal the cursor (committed=${after}, want last_offset=${rowNow.last_offset}) — partition stays phantom-pending forever` }
-    }
-
-    // Guard: delayed messages are NOT sealed over. Segments exist but are
-    // deferred; the cursor must stay put so they deliver when eligible.
-    const dqueue = 'test-queue-v2-ackwindow-seal-delayed'
-    await client.queue(dqueue).config({ delayedProcessing: 30, leaseTime: 30 }).create()
-    await client.queue(dqueue).partition('Default').push([
-        { data: { n: 0 }, transactionId: `${dqueue}-tx-0` },
-        { data: { n: 1 }, transactionId: `${dqueue}-tx-1` },
-    ])
-    // Give the fusion flush a moment so the segments exist before the pop.
-    const dpart0 = await (async () => {
-        for (let i = 0; i < 30; i++) {
-            const p = await partitionRow(dqueue)
-            if (p && (await segmentCount(p.id)) > 0) return p
-            await sleep(100)
-        }
-        return null
-    })()
-    if (!dpart0) return { success: false, message: 'delayed queue segments never appeared' }
-
-    // First contact for g-seal on THIS queue too (metadata is queue-scoped), and
-    // the 2 delayed messages are already pushed: under the default 'new' the
-    // cursor would seed at last_offset and the guard below could not tell a seed
-    // from a seal. 'all' seeds at -1, so a non -1 cursor can only be the seal.
-    const dempty = await client.queue(dqueue).partition('Default').group(group).subscriptionMode('all').batch(1).wait(false).pop()
-    if (dempty && dempty.length > 0) return { success: false, message: 'delayed message delivered early?' }
-    const dcommitted = await committedOf(dpart0.id, group)
-    const dsegs = await segmentCount(dpart0.id)
-    if (dsegs === 0) return { success: false, message: 'delayed queue segments vanished' }
-    if (dcommitted !== -1 && dcommitted !== null) {
-        return { success: false, message: `BUG: seal fired over deferred-but-present segments (committed=${dcommitted}) — delayed messages would be skipped` }
-    }
-
-    return { success: true, message: 'empty partition sealed after one pop; deferred segments not sealed over' }
-}

package/test-v2/bootstrap.js

@@ -217,8 +217,8 @@ export async function testCgBootstrapTimestamp(client) {
 
     // 3. Record cutoff timestamp (after historical, before new messages)
     //    Wait before capturing the cutoff to handle clock skew between the
-    //    client (Date.now) and PostgreSQL (NOW()). Without this, the last
-    //    push batch may have a PG created_at AFTER the client-side cutoff.
+    //    client (Date.now) and the broker's clock. Without this, the last
+    //    push batch may have a broker created_at AFTER the client-side cutoff.
     await new Promise(resolve => setTimeout(resolve, 2000))
     const cutoffTimestamp = new Date().toISOString()
     console.log(`  Cutoff timestamp: ${cutoffTimestamp}`)

package/test-v2/conflation-unit/conflationWire.test.js

@@ -310,18 +310,6 @@ describe('conflation — declaration conflict', () => {
       assert.equal(warnings.filter(w => w.includes('Conflation.conflict')).length, 1)
     })
   })
-
-  it('pop maintenance is not a version skew', async () => {
-    // `{"messages":[],"paused":true}` means an operator turned pops off. The
-    // request never reached the claim path, so there is no echo to expect —
-    // raising here would stop every conflating consumer in the fleet on a
-    // routine operator action.
-    const paused = ok({ messages: [], paused: true })
-    await withQueen([paused], paused, async (queen) => {
-      const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
-      assert.equal(messages.length, 0)
-    })
-  })
 })
 
 // ---------------------------------------------------------------------------

package/test-v2/consume.js

@@ -708,4 +708,44 @@ export async function testConsumerMultiPartitionGlobalCap(client) {
     }
 
     return { success: true, message: 'Global batch cap respected across multi-partition consume' }
-}
+}
+// A handler that throws under autoAck(false) (2026-10-02, 2.0.0-beta.6): the
+// consumer stopped at the first throw, consume() rejected, and the message
+// stayed leased until its lease ran out. It now nacks what the handler was
+// given and keeps consuming: the broker redelivers, the handler acks it.
+export async function manualAckHandlerErrorKeepsConsuming(client) {
+    const queueName = 'test-queue-v2-manual-ack-throw'
+    const group = 'test-manual-ack-throw'
+    const queue = await client.queue(queueName).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    await client.queue(queueName).push([{ data: { id: 1 } }, { data: { id: 2 } }])
+
+    const seen = []
+    try {
+        await client
+        .queue(queueName)
+        .group(group)
+        .subscriptionMode('all')
+        .autoAck(false)
+        .each()
+        .batch(1)
+        .wait(false)
+        .limit(3)
+        .consume(async (msg) => {
+            seen.push(`${msg.data.id}#${msg.deliveryAttempt}`)
+            if (seen.length === 1) throw new Error('first delivery fails')
+            // No { group }: the ack takes it from the message.
+            const res = await client.ack(msg, true)
+            if (!res.success) throw new Error(`ack refused: ${res.error}`)
+        })
+    } catch (error) {
+        return { success: false, message: `consume() rejected: ${error.message} (deliveries ${seen.join(', ')})` }
+    }
+
+    const leftover = await client.queue(queueName).group(group).batch(10).wait(false).pop()
+    const ids = seen.map(s => s.split('#')[0]).join(',')
+    const success = ids === '1,1,2' && leftover.length === 0
+    return { success, message: `deliveries ${seen.join(', ')} (expected 1,1,2), ${leftover.length} left unacked` }
+}

package/test-v2/consumer-unit/handlerError.test.js

@@ -0,0 +1,161 @@
+/**
+ * consume(): what a handler that throws does to the consumer.
+ *
+ * The rule, the same with and without autoAck: the messages the handler was
+ * given are NACKED (the broker redelivers them, and files them in the DLQ
+ * once the queue's retryLimit is spent) and the worker KEEPS CONSUMING.
+ * autoAck(false) hands the success path to the handler, not the failure path:
+ * a handler that threw did not get to settle its messages.
+ *
+ * Before: under autoAck(false) the error left the worker loop, the consume()
+ * promise rejected after one message, and the messages stayed leased until
+ * the lease expired (found 2026-10-02 against 2.0.0-beta.6). With
+ * concurrency > 1 the other workers kept running behind a promise that had
+ * already rejected.
+ *
+ * `.onError(fn)` is the way to decide for yourself: the error never reaches
+ * the consumer, so nothing is nacked on your behalf.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+
+import { Queen } from '../../client-v2/index.js'
+
+const GROUP = 'workers'
+
+const message = (n) => ({
+  id: `msg-${n}`,
+  transactionId: `tx-${n}`,
+  partitionId: '7',
+  partition: 'p1',
+  leaseId: `lease-${n}`,
+  consumerGroup: GROUP,
+  data: { n },
+  createdAt: '2026-10-02T10:00:00.000Z'
+})
+
+/**
+ * A fake broker routed by path: each pop answers the next batch of `pops`
+ * (an empty 204 once they run out), each ack or batch ack is accepted. Every
+ * request is recorded.
+ */
+async function withBroker(pops, run) {
+  const queue = [...pops]
+  const requests = []
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', chunk => { raw += chunk })
+    req.on('end', () => {
+      const body = raw ? JSON.parse(raw) : null
+      const path = req.url.split('?')[0]
+      requests.push({ method: req.method, path, body })
+      if (req.method === 'GET' && path.startsWith('/api/v1/pop')) {
+        const batch = queue.shift()
+        if (!batch) { res.writeHead(204); res.end(); return }
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ success: true, consumerGroup: GROUP, messages: batch }))
+        return
+      }
+      if (req.method === 'POST' && (path === '/api/v1/ack' || path === '/api/v1/ack/batch')) {
+        const acks = body.acknowledgments || [body]
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(acks.map((a, i) => ({ index: i, transactionId: a.transactionId, success: true, error: null }))))
+        return
+      }
+      res.writeHead(404, { 'Content-Type': 'application/json' })
+      res.end('{"error":"not found"}')
+    })
+  })
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+  const queen = new Queen({ url: `http://127.0.0.1:${server.address().port}`, handleSignals: false })
+  try {
+    await run(queen, requests)
+  } finally {
+    await queen.close()
+    await new Promise(resolve => server.close(resolve))
+  }
+}
+
+const acksIn = (requests) => requests.filter(r => r.method === 'POST' && r.path.startsWith('/api/v1/ack'))
+const statusesOf = (ackRequest) => (ackRequest.body.acknowledgments || [ackRequest.body]).map(a => a.status)
+
+describe('consume() — a handler that throws is nacked, and the consumer keeps going', () => {
+  it('autoAck(false), one message at a time: nack, redelivery, done', async () => {
+    // Delivery 1 of tx-1 fails, delivery 2 succeeds and the handler acks it.
+    await withBroker([[message(1)], [message(1)]], async (queen, requests) => {
+      const seen = []
+      await queen.queue('orders').group(GROUP).wait(false).autoAck(false).each().limit(2)
+        .consume(async (msg) => {
+          seen.push(msg.transactionId)
+          if (seen.length === 1) throw new Error('boom')
+          await queen.ack(msg, true)
+        })
+
+      assert.deepEqual(seen, ['tx-1', 'tx-1'], 'the consumer survived the throw and got the redelivery')
+      const acks = acksIn(requests)
+      assert.equal(acks.length, 2)
+      assert.deepEqual(statusesOf(acks[0]), ['failed'], 'the throw nacked the message')
+      assert.equal(acks[0].body.consumerGroup, GROUP)
+      assert.equal(acks[0].body.leaseId, 'lease-1', 'the nack names the lease it releases')
+      assert.equal(acks[0].body.error, 'boom', 'the handler error travels with the nack')
+      assert.deepEqual(statusesOf(acks[1]), ['completed'], 'the handler\'s own ack of the redelivery')
+    })
+  })
+
+  it('autoAck(false), batch handler: the whole batch is nacked in one call', async () => {
+    await withBroker([[message(1), message(2)], [message(1), message(2)]], async (queen, requests) => {
+      let calls = 0
+      await queen.queue('orders').group(GROUP).wait(false).autoAck(false).limit(3)
+        .consume(async (msgs) => {
+          calls++
+          if (calls === 1) throw new Error('batch boom')
+          await queen.ack(msgs, true)
+        })
+
+      assert.equal(calls, 2)
+      const acks = acksIn(requests)
+      assert.equal(acks[0].path, '/api/v1/ack/batch')
+      assert.deepEqual(statusesOf(acks[0]), ['failed', 'failed'])
+      assert.equal(acks[0].body.consumerGroup, GROUP)
+      assert.deepEqual(statusesOf(acks[1]), ['completed', 'completed'])
+    })
+  })
+
+  it('autoAck(false), .each(): the rest of the popped batch is abandoned after a nack', async () => {
+    // The nack released the lease and clamps the cursor at tx-1, so tx-2 comes
+    // back with it: handling it now would only produce a duplicate.
+    await withBroker([[message(1), message(2)], [message(1), message(2)]], async (queen) => {
+      const seen = []
+      await queen.queue('orders').group(GROUP).wait(false).autoAck(false).each().limit(3)
+        .consume(async (msg) => {
+          seen.push(msg.transactionId)
+          if (seen.length === 1) throw new Error('boom')
+        })
+      assert.deepEqual(seen, ['tx-1', 'tx-1', 'tx-2'])
+    })
+  })
+
+  it('autoAck(true) behaves the same way: nack and keep going', async () => {
+    await withBroker([[message(1)], [message(1)]], async (queen, requests) => {
+      let calls = 0
+      await queen.queue('orders').group(GROUP).wait(false).each().limit(2)
+        .consume(async () => { if (++calls === 1) throw new Error('boom') })
+      assert.equal(calls, 2)
+      assert.deepEqual(acksIn(requests).map(statusesOf), [['failed'], ['completed']])
+    })
+  })
+
+  it('with .onError() the handler decides: nothing is nacked on its behalf', async () => {
+    await withBroker([[message(1)], [message(2)]], async (queen, requests) => {
+      const failures = []
+      await queen.queue('orders').group(GROUP).wait(false).autoAck(false).each().limit(2)
+        .consume(async (msg) => { if (msg.transactionId === 'tx-1') throw new Error('boom') })
+        .onError(async (msg, err) => { failures.push([msg.transactionId, err.message]) })
+
+      assert.deepEqual(failures, [['tx-1', 'boom']])
+      assert.equal(acksIn(requests).length, 0, 'autoAck(false) + onError: the consumer sent no ack and no nack')
+    })
+  })
+})

package/test-v2/docs.js

@@ -10,8 +10,8 @@
  *
  * After editing a marked region, regenerate the partials with
  * `pnpm --dir webdoc gen` or the docs CI check fails on drift. The queues used
- * here (orders, payments, invoices) are wiped by cleanupTestData in run.js
- * before every suite run, exactly like the test-% queues.
+ * here (orders, payments, invoices) start empty because every suite run gets a
+ * fresh broker (test/run.sh), exactly like the test-% queues.
  */
 
 export async function docsProduceAndConsume(client) {
@@ -65,8 +65,9 @@ export async function docsProduceAndConsume(client) {
 }
 
 export async function docsDeduplication(client) {
-    // The fixed transactionId below survives reruns because cleanupTestData
-    // purges log_txns for these queues before the suite starts.
+    // The fixed transactionId below survives reruns because every run gets a
+    // fresh broker (test/run.sh creates its data volume empty and destroys it
+    // with `down -v`), so no earlier run's dedup entry is ever there.
     // docs:start(js-push-dedup)
     const first = await client
       .queue('payments')