queen-mq 1.3.0 → 2.0.2

package/test-v2/ephemeral-unit/ephemeralWire.test.js

@@ -201,7 +201,7 @@ describe('ephemeral wire — pop', () => {
 
   it('pop puts every declared parameter on the query string, in order', async () => {
     await withEphemeral([popped(QUEUE, [])], async (eph, hits) => {
-      await eph.pop(QUEUE, { partition: 'room-7', batch: 10, wait: true, timeout: 2000, group: 'workers', autoAck: true })
+      await eph.pop(QUEUE, { partition: 'room-7', batch: 10, wait: true, timeout: 2000, group: 'workers', commitOnDelivery: true })
       assert.equal(
         hits[0].url,
         `/api/v1/ephemeral/pop?queue=${QUEUE}&partition=room-7&batch=10&wait=true&timeout=2000&group=workers&autoAck=true`
@@ -209,6 +209,29 @@ describe('ephemeral wire — pop', () => {
     })
   })
 
+  it('pop sends `commitOnDelivery` as autoAck=true, and nothing for false', async () => {
+    await withEphemeral([popped(QUEUE, []), popped(QUEUE, [])], async (eph, hits) => {
+      await eph.pop(QUEUE, { commitOnDelivery: true })
+      assert.equal(hits[0].url, `/api/v1/ephemeral/pop?queue=${QUEUE}&autoAck=true`)
+
+      await eph.pop(QUEUE, { commitOnDelivery: false })
+      assert.equal(hits[1].url, `/api/v1/ephemeral/pop?queue=${QUEUE}`)
+    })
+  })
+
+  it('pop still reads the deprecated `autoAck` as `commitOnDelivery`, and refuses both spellings', async () => {
+    await withEphemeral([popped(QUEUE, [])], async (eph, hits) => {
+      await eph.pop(QUEUE, { group: 'workers', autoAck: true })
+      assert.equal(hits[0].url, `/api/v1/ephemeral/pop?queue=${QUEUE}&group=workers&autoAck=true`)
+
+      await assert.rejects(
+        () => eph.pop(QUEUE, { commitOnDelivery: true, autoAck: true }),
+        /pass either `commitOnDelivery` or its deprecated alias `autoAck`, not both/
+      )
+      assert.equal(hits.length, 1)
+    })
+  })
+
   it('pop sends an explicit timeout whenever it waits, and none when it does not', async () => {
     // The HTTP deadline is set PAST the server's, so the broker's long poll
     // always ends the request first. Letting the two defaults drift apart is

package/test-v2/http-unit/pushStatus.test.js

@@ -0,0 +1,142 @@
+/**
+ * Push per-item statuses.
+ *
+ * POST /api/v1/push answers 201 with one result per item, in input order, and
+ * a refused item fails INSIDE a successful request, so the per-item status is
+ * the only signal that a message was not stored. The statuses brokers send:
+ *
+ *   queued     stored                                            (every broker)
+ *   duplicate  its transactionId is already stored               (every broker)
+ *   error      refused, no per-item message                      (2.x)
+ *   failed     refused, with `error`                             (1.x)
+ *   buffered   written to the broker's failover file, replayed   (1.x)
+ *
+ * The client used to look for `failed` only, so a 2.x refusal (`error`) was
+ * neither reported nor thrown: push() resolved as if the message were stored.
+ * Found 2026-10-02 against 2.0.0-beta.6, which answers `error` when a
+ * partition's planned append exceeds QUEEN_RAFT_ENTRY_MAX_BYTES.
+ */
+
+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 QUEUE = 'test-push-status'
+
+const item = (index, status, extra = {}) => ({
+  index,
+  message_id: `0199aaaa-0000-7000-8000-00000000000${index}`,
+  transaction_id: `tx-${index}`,
+  queueName: QUEUE,
+  status,
+  ...extra
+})
+
+// The exact shape 2.0.0-beta.6 answered for an item it refused (no offset,
+// no error text).
+const created = (results) => ({ status: 201, body: results })
+
+async function withQueen(response, run) {
+  await withPlanServer([response], response, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('push — a refused item is reported, whatever the broker calls it', () => {
+  it('a 2.x `error` item makes push() reject, carrying the per-item results', async () => {
+    await withQueen(created([item(0, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => {
+          assert.match(err.message, /rejected by the broker/)
+          assert.match(err.message, /"error"/, 'the status the broker answered is named')
+          assert.deepEqual(err.results.map(r => r.status), ['error'])
+          return true
+        }
+      )
+    })
+  })
+
+  it('a 2.x `error` item goes to onError, and the stored ones still go to onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 0 }), item(1, 'error')]), async (queen) => {
+      let failedItems = null
+      let failure = null
+      let succeeded = null
+      const res = await queen.queue(QUEUE)
+        .push([{ data: { n: 1 } }, { data: { n: 2 } }])
+        .onError(async (items, err) => { failedItems = items; failure = err })
+        .onSuccess(async (items) => { succeeded = items })
+
+      assert.ok(Array.isArray(res), 'with onError the call resolves with the broker results')
+      assert.equal(failedItems.length, 1)
+      assert.deepEqual(failedItems[0].payload, { n: 2 })
+      assert.equal(failedItems[0].result.status, 'error')
+      assert.match(failure.message, /rejected by the broker/)
+      assert.equal(succeeded.length, 1)
+      assert.deepEqual(succeeded[0].payload, { n: 1 })
+    })
+  })
+
+  it('a 1.x `failed` item is reported with the broker\'s own text', async () => {
+    await withQueen(created([item(0, 'failed', { error: 'File buffer write failed' })]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.equal(err.message, 'File buffer write failed'); return true }
+      )
+    })
+  })
+
+  it('a status this client does not know is a failure, not a silent success', async () => {
+    await withQueen(created([item(0, 'refused-by-something-new')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.match(err.message, /refused-by-something-new/); return true }
+      )
+    })
+  })
+
+  it('several refused items: one error for the call, counting them', async () => {
+    await withQueen(created([item(0, 'error'), item(1, 'queued', { offset: 0 }), item(2, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: 1 }, { data: 2 }, { data: 3 }]) },
+        (err) => { assert.match(err.message, /^2 of 3 pushed items rejected/); return true }
+      )
+    })
+  })
+})
+
+describe('push — accepted statuses stay accepted', () => {
+  it('`queued` resolves with the broker results and reaches onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 7 })]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'queued')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('a 1.x `buffered` item is accepted: the broker owns its delivery', async () => {
+    await withQueen(created([item(0, 'buffered')]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'buffered')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('`duplicate` goes to onDuplicate and is not a failure', async () => {
+    await withQueen(created([item(0, 'duplicate', { offset: 3 })]), async (queen) => {
+      let dups = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onDuplicate(async (items) => { dups = items })
+      assert.equal(res[0].status, 'duplicate')
+      assert.equal(dups.length, 1)
+    })
+  })
+})

package/test-v2/http-unit/renew.test.js

@@ -0,0 +1,96 @@
+/**
+ * Queen.renew() outcome.
+ *
+ * POST /api/v1/lease/:leaseId/extend answers HTTP 200 whether or not anything
+ * was renewed. `success` in the body is the only signal, and the client used
+ * to ignore it: renewing a lease that had expired, or that an ack had already
+ * released, reported `success: true` with `newExpiresAt: null` (found
+ * 2026-10-02 against 2.0.0-beta.6). The bodies below are what brokers send:
+ *
+ *   1.x and 2.x: {leaseId, success, renewed, newExpiresAt, expiresAt, lease_expires_at}
+ *   C++:         [{index, leaseId, success, error, expiresAt}]
+ */
+
+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 LEASE = '01a0fcf2-1a28-7001-8810-d74deda1fd42'
+const EXPIRES = '2026-10-02T14:09:40.273Z'
+
+// What 2.0.0-beta.6 answered for a live lease covering two partitions, and
+// for a lease that no longer exists.
+const renewed = (leaseId = LEASE) => ({
+  leaseId, success: true, renewed: 2, newExpiresAt: EXPIRES, expiresAt: EXPIRES, lease_expires_at: EXPIRES
+})
+const notRenewed = (leaseId = LEASE) => ({
+  leaseId, success: false, renewed: 0, newExpiresAt: null, expiresAt: null, lease_expires_at: null
+})
+
+async function withQueen(plan, run) {
+  await withPlanServer(plan, { status: 200, body: renewed() }, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('Queen.renew — the broker\'s verdict, not the HTTP status', () => {
+  it('a renewed lease reports success, its new expiry, and how many partitions it covers', async () => {
+    await withQueen([{ body: renewed() }], async (queen, hits) => {
+      const res = await queen.renew(LEASE)
+      assert.deepEqual(res, { leaseId: LEASE, success: true, newExpiresAt: EXPIRES, renewed: 2 })
+      assert.equal(hits[0].url, `/api/v1/lease/${LEASE}/extend`)
+    })
+  })
+
+  it('a lease that is gone reports failure, with a reason', async () => {
+    await withQueen([{ body: notRenewed() }], async (queen) => {
+      const res = await queen.renew({ leaseId: LEASE, transactionId: 'tx-1' })
+      assert.equal(res.success, false)
+      assert.equal(res.renewed, 0)
+      assert.equal(res.newExpiresAt, null)
+      assert.match(res.error, /not renewed/)
+    })
+  })
+
+  it('an array of messages answers one outcome per distinct lease', async () => {
+    const other = '01a0fcf2-0000-7000-8000-000000000000'
+    await withQueen([{ body: renewed() }, { body: notRenewed(other) }], async (queen, hits) => {
+      const res = await queen.renew([
+        { leaseId: LEASE, transactionId: 'tx-1' },
+        { leaseId: LEASE, transactionId: 'tx-2' },
+        { leaseId: other, transactionId: 'tx-3' }
+      ])
+      assert.equal(hits.length, 2, 'one call per lease, not per message')
+      assert.deepEqual(res.map(r => [r.leaseId, r.success]), [[LEASE, true], [other, false]])
+    })
+  })
+
+  it('reads the C++ broker\'s array, including its error text', async () => {
+    await withQueen([
+      { body: [{ index: 0, leaseId: LEASE, success: true, error: null, expiresAt: EXPIRES }] },
+      { body: [{ index: 0, leaseId: LEASE, success: false, error: 'Lease already expired', expiresAt: null }] }
+    ], async (queen) => {
+      const ok = await queen.renew(LEASE)
+      assert.equal(ok.success, true)
+      assert.equal(ok.newExpiresAt, EXPIRES)
+      const gone = await queen.renew(LEASE)
+      assert.equal(gone.success, false)
+      assert.equal(gone.error, 'Lease already expired')
+    })
+  })
+
+  it('an HTTP failure is still a failed renewal, not a throw', async () => {
+    await withQueen([{ status: 500, body: { error: 'boom' } }], async (queen) => {
+      const res = await queen.renew(LEASE)
+      assert.equal(res.success, false)
+      assert.ok(res.error)
+    })
+  })
+})

package/test-v2/kv-unit/timerWire.test.js

@@ -10,7 +10,7 @@
  *      a tenant that is over quota -- while the fire never stops by itself, so
  *      that tenant keeps producing messages it cannot stop.
  *   2. delayMs, never delaySeconds and never an absolute instant (§4.2,
- *      §20.6). One clock, Postgres's. `deliverAt` in an op is a 22023.
+ *      §20.6). One clock, the broker's. `deliverAt` in an op is a 22023.
  *   3. The payload is base64 (§6.2), and the SDK encodes it, so a caller never
  *      has to know.
  *   4. `txn` is mandatory on a schedule and is echoed on `absent`, which is

package/test-v2/kv-unit/txnWire.test.js

@@ -181,11 +181,19 @@ describe('Transaction wire — the verdict that must not throw', () => {
   })
 
   it('commit() still THROWS on every other failure', async () => {
-    const rejected = ok({ transactionId: 'txn-1', success: false, reason: 'ack_rejected', error: 'QTXN invalid or expired lease', results: [] })
+    // The body a 2.0 broker answers for an ack whose lease is gone (a 1.x
+    // broker spelled the reason ack_rejected).
+    const rejected = ok({
+      transactionId: 'txn-1',
+      success: false,
+      reason: 'rejected_ack',
+      error: 'QTXN 1 acked message(s) on partition 3 are not leased by this worker or were already acked; the transaction rolled back',
+      results: []
+    })
     await withQueen([rejected], async (queen) => {
       await assert.rejects(() => queen.transaction().ack(MSG).commit(), (e) => {
         assert.match(e.message, /QTXN/)
-        assert.equal(e.reason, 'ack_rejected', 'the closed-taxonomy reason travels on the error, so nobody matches the message')
+        assert.equal(e.reason, 'rejected_ack', 'the broker\'s reason travels on the error, so nobody matches the message')
         return true
       })
     })
@@ -220,3 +228,94 @@ describe('Transaction wire — the verdict that must not throw', () => {
     })
   })
 })
+
+// ---------------------------------------------------------------------------
+// The consumer group of an ack op. The lease an ack has to match belongs to
+// the group the message was popped under, and an op that names no group is
+// judged in queue mode: a message popped by a group and acked without one
+// rolled the whole bundle back with `rejected_ack` (found 2026-10-02 against
+// 2.0.0-beta.6). Every pop answers each message with its `consumerGroup`.
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — the ack op carries the group the message was popped under', () => {
+  const fromGroup = (group, n = 1) => ({
+    ...MSG,
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    consumerGroup: group
+  })
+
+  it('takes consumerGroup from the message when the caller names none', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers')).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'workers')
+    })
+  })
+
+  it('a queue-mode message adds no consumerGroup key, as before', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('__QUEUE_MODE__')).commit()
+      await queen.transaction().ack(MSG).commit()   // hand-built, no group at all
+      for (const hit of hits) {
+        assert.deepEqual(Object.keys(hit.body.operations[0]).sort(), ['leaseId', 'partitionId', 'status', 'transactionId', 'type'])
+      }
+    })
+  })
+
+  it('an explicit group wins, as { consumerGroup } or as { group }', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { consumerGroup: 'auditors' }).commit()
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { group: 'auditors' }).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'auditors')
+      assert.equal(hits[1].body.operations[0].consumerGroup, 'auditors')
+    })
+  })
+
+  it('messages from different groups each keep their own', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([fromGroup('a', 1), fromGroup('b', 2)]).commit()
+      assert.deepEqual(hits[0].body.operations.map(op => op.consumerGroup), ['a', 'b'])
+    })
+  })
+})
+
+// The lease of an ack op. A Queen 2 broker fences each ack with the leaseId
+// the operation carries, and lends it one from requiredLeases only when every
+// lease in the bundle is the same lease. An ack whose lease travelled in
+// requiredLeases alone was applied unfenced in a bundle of two leases, even
+// after that lease expired and another consumer took the message (found
+// 2026-10-03 against 2.0.0-beta.6).
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — each ack op carries its own lease', () => {
+  const leased = (n, leaseId) => ({
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    partitionId: `pppppppp-pppp-7ppp-8ppp-00000000000${n}`,
+    ...(leaseId === undefined ? {} : { leaseId })
+  })
+
+  it('a bundle spanning two leases names each lease on its own ack', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(leased(1, 'lease-1'))
+        .ack(leased(2, 'lease-2'))
+        .ack(leased(3))
+        .commit()
+
+      const [first, second, third] = hits[0].body.operations
+      assert.equal(first.leaseId, 'lease-1')
+      assert.equal(second.leaseId, 'lease-2')
+      assert.ok(!('leaseId' in third), 'a message without a lease adds no leaseId key')
+      assert.deepEqual(hits[0].body.requiredLeases, ['lease-1', 'lease-2'])
+    })
+  })
+
+  it('a null or empty lease adds no leaseId key either', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([leased(1, null), leased(2, '')]).commit()
+      for (const op of hits[0].body.operations) {
+        assert.ok(!('leaseId' in op))
+      }
+      assert.deepEqual(hits[0].body.requiredLeases, [])
+    })
+  })
+})

package/test-v2/kv.js

@@ -1,15 +1,16 @@
 /**
  * KV integration suite (PLAN_KV_TIMERS.md §5, §8.3).
  *
- * Every test here is repeatable ONLY because run.js purges `queen.kv` for the
- * `test-%` namespaces before the run (§10.4): without that purge a
+ * Every test here is repeatable ONLY because every run starts on a fresh broker
+ * (test/run.sh creates the lane's data volume empty and destroys it with
+ * `down -v`): against a broker that kept the previous run's keys, a
  * `putIfAbsent` test is green on its first execution and red forever after,
- * and an `incr` test accumulates between runs. If you add a test here, its
- * namespace must start with `test-` or it will be the one that rots.
+ * and an `incr` test accumulates between runs. Keep the namespaces under
+ * `test-`, like every other fixture of the suite.
  *
  * And `forever` is BANNED in this file. A test that goes wrong with a TTL
  * leaves state that expires by itself; a test that goes wrong with `forever`
- * leaves immortal state in a shared database.
+ * leaves immortal state in a shared broker.
  */
 
 import { KV_NS, sleep } from './_kvtimers.js'

package/test-v2/pop-unit/popDefaults.test.js

@@ -0,0 +1,236 @@
+/**
+ * pop() and consume() share one builder but not their defaults.
+ *
+ *            autoAck                     commitOnDelivery        wait
+ *   pop()    never sent                  off; on sends autoAck   true  (POP_DEFAULTS)
+ *   consume  true, client-side           refused                 true  (CONSUME_DEFAULTS)
+ *
+ * autoAck() is consume()'s ack after the handler and never reaches the wire.
+ * The broker's at-most-once commit at delivery is the pop's own option,
+ * commitOnDelivery(), which sends autoAck=true; consume() always leases, so it
+ * refuses that option before any request.
+ * POP_DEFAULTS.wait said false while every pop long-polled; the long poll is
+ * what callers rely on, so it stays, and POP_DEFAULTS and the guide say so.
+ *
+ * The broker contract (server/src/handlers/data.rs, PopParams): autoAck=true
+ * commits the messages at delivery, with an empty leaseId; an absent autoAck
+ * is false. An absent wait is false too, but this SDK always sends wait.
+ *
+ * Same style as conflation-unit/conflationWire.test.js: a real node:http
+ * server playing a canned plan, real fetch, and every assertion is about the
+ * bytes that crossed the socket.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer, ok } from '../kv-unit/_planServer.js'
+
+const QUEUE = 'q'
+const GROUP = 'g'
+
+const frame = (n = 1) => ({
+  transactionId: `txn-${n}`,
+  partitionId: `part-${n}`,
+  partition: 'Default',
+  payload: { n },
+  leaseId: 'lease-1',
+  consumerGroup: GROUP
+})
+
+const popBody = (frames = [frame()]) => ok({ messages: frames, partitionsClaimed: frames.length })
+
+// Acks answer with one result per acknowledgment; the plan only needs enough
+// of them for the consume() cases below.
+const ackBody = ok([{ index: 0, transactionId: 'txn-1', success: true, error: null }])
+
+function query(url) {
+  const i = url.indexOf('?')
+  return new URLSearchParams(i < 0 ? '' : url.slice(i + 1))
+}
+
+const pops = (hits) => hits.filter(h => h.method === 'GET' && h.url.startsWith('/api/v1/pop'))
+const acks = (hits) => hits.filter(h => h.method === 'POST' && h.url.startsWith('/api/v1/ack'))
+const statusesOf = (hit) => (hit.body.acknowledgments || [hit.body]).map(a => a.status)
+
+async function withQueen(plan, defaultResponse, run) {
+  await withPlanServer(plan, defaultResponse, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('pop() — autoAck', () => {
+  // autoAck() is consume()'s ack after the handler and never reaches the
+  // wire: a pop comes back leased whatever autoAck() said. The broker's
+  // at-most-once autoAck is commitOnDelivery(), below.
+  for (const [label, build] of [
+    ['autoAck() never called', (q) => q.group(GROUP)],
+    ['autoAck(true)', (q) => q.group(GROUP).autoAck(true)],
+    ['autoAck(false)', (q) => q.group(GROUP).autoAck(false)],
+  ]) {
+    it(`sends no autoAck after ${label}`, async () => {
+      await withQueen([popBody(), popBody()], popBody(), async (queen, hits) => {
+        await build(queen.queue(QUEUE)).pop()
+        await build(queen.queue(QUEUE)).popResult()
+
+        for (const hit of pops(hits)) {
+          assert.equal(query(hit.url).has('autoAck'), false)
+        }
+      })
+    })
+  }
+})
+
+describe('pop() — commitOnDelivery', () => {
+  // The broker's commit at delivery, on the wire name every 2.x broker reads:
+  // the pop carries autoAck=true and nothing else changes.
+  it('pop() and popResult() send autoAck=true and nothing else', async () => {
+    await withQueen([popBody(), popBody(), popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).pop()
+      await queen.queue(QUEUE).group(GROUP).commitOnDelivery().pop()
+      await queen.queue(QUEUE).group(GROUP).commitOnDelivery(true).popResult()
+
+      const [plain, ...committed] = pops(hits)
+      assert.equal(committed.length, 2)
+      for (const hit of committed) {
+        const q = query(hit.url)
+        assert.equal(q.get('autoAck'), 'true')
+        q.delete('autoAck')
+        assert.deepEqual(Object.fromEntries(q), Object.fromEntries(query(plain.url)))
+        assert.equal(hit.url.split('?')[0], plain.url.split('?')[0])
+      }
+    })
+  })
+
+  it('sends no autoAck after commitOnDelivery(false)', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).commitOnDelivery(true).commitOnDelivery(false).pop()
+
+      assert.equal(query(pops(hits)[0].url).has('autoAck'), false)
+    })
+  })
+
+  it('does not depend on autoAck(), which stays consume()\'s', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).autoAck(false).commitOnDelivery().pop()
+
+      assert.equal(query(pops(hits)[0].url).get('autoAck'), 'true')
+    })
+  })
+
+  it('with conflation(), sends both and raises the broker\'s 400 instead of returning []', async () => {
+    // The broker refuses conflation together with a commit at delivery
+    // (server/src/handlers/data.rs, conflation_refusal).
+    const refusal = {
+      status: 400,
+      body: { success: false, error: 'conflation cannot be combined with autoAck', messages: [] }
+    }
+    await withQueen([refusal], refusal, async (queen, hits) => {
+      await assert.rejects(
+        () => queen.queue(QUEUE).group(GROUP).conflation().commitOnDelivery().pop(),
+        (err) => err.status === 400
+      )
+
+      const q = query(pops(hits)[0].url)
+      assert.equal(q.get('autoAck'), 'true')
+      assert.equal(q.get('conflation'), 'true')
+    })
+  })
+})
+
+describe('consume() refuses commitOnDelivery()', () => {
+  it('throws before any request', async () => {
+    await withQueen([], popBody(), async (queen, hits) => {
+      assert.throws(
+        () => queen.queue(QUEUE).group(GROUP).commitOnDelivery().consume(async () => {}),
+        {
+          message: 'commitOnDelivery() is a pop() option; consume() always leases its messages'
+        }
+      )
+      assert.equal(hits.length, 0)
+    })
+  })
+
+  it('consumes as before after commitOnDelivery(false)', async () => {
+    await withQueen([popBody(), ackBody], ackBody, async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).commitOnDelivery(false).limit(1).consume(async () => {})
+
+      assert.equal(query(pops(hits)[0].url).has('autoAck'), false)
+      assert.equal(acks(hits).length, 1)
+    })
+  })
+})
+
+describe('pop() — wait', () => {
+  it('long-polls when wait() was never called', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).pop()
+
+      assert.equal(query(pops(hits)[0].url).get('wait'), 'true')
+    })
+  })
+
+  it('long-polls for timeoutMillis() when only that was called', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).timeoutMillis(2000).pop()
+
+      const q = query(pops(hits)[0].url)
+      assert.equal(q.get('wait'), 'true')
+      assert.equal(q.get('timeout'), '2000')
+    })
+  })
+
+  it('sends wait=false after wait(false)', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).wait(false).pop()
+
+      assert.equal(query(pops(hits)[0].url).get('wait'), 'false')
+    })
+  })
+})
+
+describe('consume() keeps its own defaults', () => {
+  it('long-polls and never sends autoAck, also after autoAck(true): it acks after the handler', async () => {
+    await withQueen([popBody(), ackBody], ackBody, async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).autoAck(true).limit(1)
+        .consume(async () => {})
+
+      const q = query(pops(hits)[0].url)
+      assert.equal(q.get('wait'), 'true')
+      assert.equal(q.has('autoAck'), false)
+      assert.equal(acks(hits).length, 1, 'the consumer acked after the handler returned')
+      assert.deepEqual(statusesOf(acks(hits)[0]), ['completed'])
+    })
+  })
+
+  it('acks after the handler when autoAck() was never called', async () => {
+    await withQueen([popBody(), ackBody], ackBody, async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).limit(1).consume(async () => {})
+
+      assert.equal(query(pops(hits)[0].url).get('wait'), 'true')
+      assert.equal(acks(hits).length, 1)
+    })
+  })
+
+  it('sends no ack after autoAck(false)', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).autoAck(false).limit(1).consume(async () => {})
+
+      assert.equal(acks(hits).length, 0)
+    })
+  })
+
+  it('sends wait=false after wait(false)', async () => {
+    await withQueen([popBody(), ackBody], ackBody, async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).wait(false).limit(1).consume(async () => {})
+
+      assert.equal(query(pops(hits)[0].url).get('wait'), 'false')
+    })
+  })
+})