queen-mq 1.3.0 → 2.0.2

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/admin-unit/removedRoutes.test.js

@@ -0,0 +1,63 @@
+/**
+ * Admin methods whose route the 2.x broker does not have.
+ *
+ * clearQueue() sent DELETE /api/v1/queues/:name/clear and moveMessageToDLQ()
+ * sent POST /api/v1/messages/:partitionId/:transactionId/dlq. Neither route is
+ * registered (server/src/rsm/facade/real/phase2/reads.rs: the messages family
+ * is GET, DELETE and POST .../retry; there is no /api/v1/queues/... family), so
+ * a 2.x broker answers both with 404 no_such_route, and the caller saw
+ * "not found". Both now throw before any request, naming the way that works.
+ *
+ * Same style as conflation-unit/conflationWire.test.js: a real node:http
+ * server records every request, so "before any request" is asserted on the
+ * socket, not on a mock.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer } from '../kv-unit/_planServer.js'
+
+const notFound = { status: 404, body: { code: 'no_such_route', error: 'not found' } }
+
+async function withQueen(run) {
+  await withPlanServer([], notFound, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('Admin — routes the 2.x broker does not have', () => {
+  it('moveMessageToDLQ() throws before any request and names the dlq ack', async () => {
+    await withQueen(async (queen, hits) => {
+      await assert.rejects(
+        queen.admin.moveMessageToDLQ('7', 'tx-1'),
+        (err) => {
+          assert.match(err.message, /no route/)
+          assert.match(err.message, /queen\.ack\(message, 'dlq', \{ group \}\)/)
+          return true
+        }
+      )
+      assert.equal(hits.length, 0, 'no request was sent')
+    })
+  })
+
+  it('clearQueue() throws before any request and names the seek to the end', async () => {
+    await withQueen(async (queen, hits) => {
+      await assert.rejects(
+        queen.admin.clearQueue('orders', 'p1'),
+        (err) => {
+          assert.match(err.message, /no route/)
+          assert.match(err.message, /seekConsumerGroup\(group, 'orders', \{ toEnd: true \}\)/)
+          return true
+        }
+      )
+      assert.equal(hits.length, 0, 'no request was sent')
+    })
+  })
+})

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/consumer-unit/nackScope.test.js

@@ -0,0 +1,88 @@
+/**
+ * each(): a nack releases ONE partition. A multi-partition pop claims several
+ * partitions under one lease; when the handler fails a message, the nack
+ * releases that message's partition and clamps its cursor, so the later
+ * messages of THAT partition come back on the next pop. The other partitions
+ * are still leased to this worker: their messages must be handled now.
+ *
+ * Before: the loop abandoned the whole popped batch after a nack. The other
+ * partitions' messages stayed leased and came back only when the lease
+ * expired (found live 2026-10-06 against 2.0.1: B1 and B2 waited the whole
+ * 6 s lease after A1 failed).
+ */
+
+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 = (partition, n) => ({
+  id: `msg-${partition}${n}`,
+  transactionId: `tx-${partition}${n}`,
+  partitionId: `pid-${partition}`,
+  partition,
+  leaseId: 'lease-1',
+  consumerGroup: GROUP,
+  data: { tag: `${partition}${n}` },
+  createdAt: '2026-10-06T10:00:00.000Z'
+})
+
+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))
+  }
+}
+
+describe('each(): a nack skips only its own partition', () => {
+  it('handles the other partitions of the pop after a failure', async () => {
+    const pop = [message('A', 1), message('A', 2), message('B', 1), message('B', 2)]
+    await withBroker([pop], async (queen, requests) => {
+      const handled = []
+      await queen.queue('orders').group(GROUP).each().batch(4).limit(3).idleMillis(500)
+        .consume(async (m) => {
+          handled.push(m.data.tag)
+          if (m.data.tag === 'A1') throw new Error('A1 fails')
+        })
+
+      assert.deepEqual(handled, ['A1', 'B1', 'B2'], 'A2 is skipped (it comes back after the nack), B is handled now')
+      const settled = requests.filter(r => r.path.startsWith('/api/v1/ack'))
+        .flatMap(r => r.body.acknowledgments || [r.body])
+        .map(a => `${a.transactionId}:${a.status}`)
+      assert.deepEqual(settled, ['tx-A1:failed', 'tx-B1:completed', 'tx-B2:completed'])
+    })
+  })
+})

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')