queen-mq 2.0.0 → 2.0.2

package/README.md

@@ -22,7 +22,7 @@ Queen MQ is a partitioned message queue broker that keeps its state in its own r
 - **Consumer Groups** - Kafka-style consumer groups for scalability
 - **Flexible Semantics** - Exactly-once, at-least-once, and at-most-once delivery
 - **Transactions** - Atomic operations across push and ack
-- **High Performance** — 104K msg/s push, 165K msg/s fan-out with consumer groups on a single 32-core node ([benchmarks](https://github.com/queen-mq/queen/tree/master/benchmark-queen/2026-04-26))
+- **High Performance** — 1M msg/s in and out of one queue of 10M partitions on three nodes ([benchmarks](https://queenmq.com/benchmarks/))
 - **Subscription Modes** - Process from beginning, new messages only, or from timestamp
 - **Dead Letter Queue** - Automatic failure handling and monitoring
 - **Message Tracing** - Debug distributed workflows with trace timelines
@@ -192,8 +192,8 @@ Notes:
   the partition cap; either way it is clamped to 64, so a conflating pop returns
   at most 64 messages per round-trip whatever `batch` says.
 - Refused with 400 by the broker without a `.group(...)`, and together with
-  `.autoAck(true)` (auto-ack commits at delivery, which would turn the guarantee
-  above into at-most-once).
+  `.commitOnDelivery()` (a commit at delivery would turn the guarantee above
+  into at-most-once). `pop()` raises that 400 instead of returning `[]`.
 - Requires broker **>= 1.1.0**. An older broker ignores the flag and would
   quietly deliver the whole backlog, so the SDK raises
   `conflation was requested but this broker did not apply it` on the first
@@ -281,8 +281,9 @@ 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.
+`retryLimit` is spent. With `.each()`, the later messages of the failed message's partition are
+skipped after a nack (the broker redelivers them too); the other partitions of the same pop are
+still handled.
 
 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
@@ -794,8 +795,20 @@ const msgs = await queen.queue('q').batch(10).pop()
 const msgs = await queen.queue('q').batch(10).wait(true).pop()
 const msgs = await queen.queue('q').batch(200).partitions(50).pop()  // multi-partition pop
 const { messages, autopilot } = await queen.queue('q').popResult()   // + what the broker chose
+const msgs = await queen.queue('q').group('g').commitOnDelivery().pop()  // committed at delivery, nothing to ack
 ```
 
+A pop long-polls, waiting up to `timeoutMillis` (30 s) for a message, unless you call
+`.wait(false)`. Its messages come back leased, and the ack is yours.
+
+`.commitOnDelivery()` changes that for `pop()` and `popResult()`. The broker moves the group's
+cursor past the messages as it hands them out: there is no lease (`leaseId` is empty) and nothing
+to ack. This is at-most-once delivery: a crash after the pop loses the messages. The broker
+refuses it together with `.conflation()` (400). `consume()` always leases its messages, so it
+throws before any request when the builder has `.commitOnDelivery()`.
+
+`.autoAck()` is `consume()`'s ack after your handler and has no effect on a pop.
+
 ### Consume
 
 ```javascript
@@ -950,6 +963,18 @@ await queen.close()  // Flush buffers and close connections
 the broker. These values are what comes back with `.autopilot(false)` or
 `QUEEN_SDK_POP_AUTOPILOT=off`.
 
+### Pop Defaults
+
+```javascript
+{
+  batch: 1,              // autopilot OFF only, as for consume
+  wait: true,            // long-polls; .wait(false) returns at once
+  timeoutMillis: 30000,  // the long-poll limit
+  autoAck: false,        // consume()'s ack after the handler; no effect on pop()
+  commitOnDelivery: false // leased; .commitOnDelivery() commits at delivery (at-most-once)
+}
+```
+
 ---
 
 ## Logging

package/client-v2/Queen.js

@@ -319,8 +319,8 @@ export class Queen {
    *     creates it, which is what makes thousands of short-lived req/reply
    *     inboxes cheap (§1.1).
    *   * delivery is at-least-once while the owning broker lives, at-most-once
-   *     with `autoAck` (§1.3) -- NOT "at most once" as a class. Consumers still
-   *     need idempotency.
+   *     with `commitOnDelivery` (§1.3) -- NOT "at most once" as a class.
+   *     Consumers still need idempotency.
    *   * consumption semantics are the pop's `group`, exactly as on durable
    *     queues (§1.5): same group competes, own group fans out, no group is
    *     queue mode. There is no queue-level mode to set.

package/client-v2/README.md

@@ -1662,6 +1662,11 @@ const msgs = await queen.queue('q').partition('p1').pop()
 // capped at 200 total messages. All partitions share one leaseId.
 // Each returned message carries its own partitionId / partition / leaseId.
 const msgs = await queen.queue('q').batch(200).partitions(50).pop()
+
+// Commit at delivery: the broker moves the group's cursor past the messages
+// as it hands them out. No lease, nothing to ack, at-most-once: a crash after
+// the pop loses them. pop() and popResult() only; consume() throws.
+const msgs = await queen.queue('q').group('g').commitOnDelivery().pop()
 ```
 
 ### Consume
@@ -1915,8 +1920,9 @@ await queen.close()
 ```javascript
 {
   batch: 1,
-  wait: false,                        // No long polling
-  autoAck: false                      // Manual ack required
+  wait: true,                         // Long polling; .wait(false) returns at once
+  autoAck: false,                     // consume()'s ack after the handler; no effect on pop()
+  commitOnDelivery: false             // Manual ack required; .commitOnDelivery() commits at delivery
 }
 ```
 

package/client-v2/admin/Admin.js

@@ -101,15 +101,26 @@ export class Admin {
   }
 
   /**
-   * Clear all messages from a queue
+   * @deprecated The 2.x broker has no route that clears a queue, so this
+   *             always rejects, before any request. Seek each consumer group
+   *             to the end instead.
+   *
+   * The old DELETE /api/v1/queues/:name/clear answers 404 no_such_route on
+   * 2.x. A seek to the end moves one group's cursor past every queued message
+   * (and releases its live leases); the group of a pop without one is
+   * '__QUEUE_MODE__'. Deleting the queue is not a clear: it removes the queue
+   * itself, with its configuration.
    * @param {string} name - Queue name
-   * @param {string} [partition] - Optional partition to clear
-   * @returns {Promise<object>}
+   * @param {string} [partition] - Ignored
+   * @returns {Promise<never>}
    */
   async clearQueue(name, partition = null) {
     logger.log('Admin.clearQueue', { name, partition })
-    const queryString = partition ? `?partition=${encodeURIComponent(partition)}` : ''
-    return this.#httpClient.delete(`/api/v1/queues/${encodeURIComponent(name)}/clear${queryString}`)
+    throw new Error(
+      'Queen 2.x has no route that clears a queue. Move each consumer group past what is queued ' +
+      `with queen.admin.seekConsumerGroup(group, '${name}', { toEnd: true }); ` +
+      "a pop without a group reads as the group '__QUEUE_MODE__'."
+    )
   }
 
   /**
@@ -172,14 +183,25 @@ export class Admin {
   }
 
   /**
-   * Move a message to the Dead Letter Queue
+   * @deprecated The 2.x broker has no route that moves a message to the DLQ
+   *             by its address, so this always rejects, before any request.
+   *             Ack the leased message with the `dlq` status instead.
+   *
+   * The old POST /api/v1/messages/:partitionId/:transactionId/dlq answers 404
+   * no_such_route on 2.x. The broker files a dead letter when the consumer
+   * group acks the message with the `dlq` status while it holds the lease (an
+   * address alone cannot name the lease), or when a `failed` ack spends the
+   * queue's last retry.
    * @param {string} partitionId - Partition ID
    * @param {string} transactionId - Transaction ID
-   * @returns {Promise<object>}
+   * @returns {Promise<never>}
    */
   async moveMessageToDLQ(partitionId, transactionId) {
     logger.log('Admin.moveMessageToDLQ', { partitionId, transactionId })
-    return this.#httpClient.post(`/api/v1/messages/${partitionId}/${transactionId}/dlq`, {})
+    throw new Error(
+      'Queen 2.x has no route that moves a message to the DLQ by its address. Pop the message for ' +
+      "its consumer group and call queen.ack(message, 'dlq', { group }) while you hold its lease."
+    )
   }
 
   // ===========================

package/client-v2/builders/QueueBuilder.js

@@ -24,6 +24,12 @@ import * as logger from '../utils/logger.js'
 // this client cannot read is not a message it can report as stored.
 const ACCEPTED_PUSH_STATUSES = new Set(['queued', 'buffered'])
 
+// What consume() throws when the builder carries commitOnDelivery(): the loop
+// always pops leased and acks after the handler, so it cannot honour a commit
+// at delivery, and silently leasing would not be what the caller asked for.
+const COMMIT_ON_DELIVERY_NOT_FOR_CONSUME =
+  'commitOnDelivery() is a pop() option; consume() always leases its messages'
+
 export class QueueBuilder {
   #queen
   #httpClient
@@ -45,8 +51,14 @@ export class QueueBuilder {
   #batch = null
   #limit = CONSUME_DEFAULTS.limit
   #idleMillis = CONSUME_DEFAULTS.idleMillis
-  #autoAck = CONSUME_DEFAULTS.autoAck
-  #wait = CONSUME_DEFAULTS.wait
+  // autoAck and wait hold the USER's value, and null means the setter was never
+  // called: consume() applies CONSUME_DEFAULTS and pop() POP_DEFAULTS at
+  // emission time. autoAck is consume()'s alone; pop() never sends it.
+  #autoAck = null
+  #wait = null
+  // The pop's own option for the broker's commit at delivery: pop() and
+  // popResult() send it as autoAck=true, and consume() refuses it.
+  #commitOnDelivery = POP_DEFAULTS.commitOnDelivery
   #timeoutMillis = CONSUME_DEFAULTS.timeoutMillis
   #renewLease = CONSUME_DEFAULTS.renewLease
   #renewLeaseIntervalMillis = CONSUME_DEFAULTS.renewLeaseIntervalMillis
@@ -301,6 +313,12 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * consume(): ack each message after the handler returns (default true; the
+   * client acks, nothing is sent with the pop). No effect on pop(): it never
+   * reaches the wire. For the broker's at-most-once commit at delivery on a
+   * pop, use commitOnDelivery().
+   */
   autoAck(enabled) {
     this.#autoAck = enabled
     return this
@@ -344,8 +362,9 @@ export class QueueBuilder {
    * that does not echo the flag rather than draining it silently.
    *
    * Refused by the broker (400) when combined with queue mode (no consumer
-   * group) or with autoAck, which commits at delivery and would turn the
-   * "the newest state is definitely processed" guarantee into at-most-once.
+   * group) or with commitOnDelivery(), which commits at delivery and would
+   * turn the "the newest state is definitely processed" guarantee into
+   * at-most-once. pop() raises that 400 instead of returning [].
    */
   conflation(enabled = true) {
     this.#conflation = !!enabled
@@ -362,6 +381,10 @@ export class QueueBuilder {
   // ===========================
 
   consume(handler, options = {}) {
+    if (this.#commitOnDelivery) {
+      throw new Error(COMMIT_ON_DELIVERY_NOT_FOR_CONSUME)
+    }
+
     const consumeOptions = {
       queue: this.#queueName,
       partition: this.#partition !== 'Default' ? this.#partition : null,
@@ -372,8 +395,8 @@ export class QueueBuilder {
       batch: this.#batch,
       limit: this.#limit,
       idleMillis: this.#idleMillis,
-      autoAck: this.#autoAck,
-      wait: this.#wait,
+      autoAck: this.#autoAck ?? CONSUME_DEFAULTS.autoAck,
+      wait: this.#wait ?? CONSUME_DEFAULTS.wait,
       timeoutMillis: this.#timeoutMillis,
       renewLease: this.#renewLease,
       renewLeaseIntervalMillis: this.#renewLeaseIntervalMillis,
@@ -397,6 +420,10 @@ export class QueueBuilder {
   // Pop Methods
   // ===========================
 
+  /**
+   * Long-poll: wait up to timeoutMillis for a message instead of returning
+   * empty at once. Default true for both pop() and consume().
+   */
   wait(enabled) {
     this.#wait = enabled
     return this
@@ -416,6 +443,24 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * Commit the messages of pop() and popResult() at delivery.
+   *
+   * The broker moves the consumer group's cursor past the messages as it hands
+   * them out: no lease, nothing to ack (the messages come back with an empty
+   * leaseId). That is at-most-once: a crash after the pop loses them. The
+   * request carries autoAck=true, the parameter every 2.x broker reads.
+   *
+   * A pop option only: consume() always leases its messages, so it throws
+   * when this is set. The broker refuses it together with conflation() (400).
+   *
+   * @param {boolean} [enabled=true]
+   */
+  commitOnDelivery(enabled = true) {
+    this.#commitOnDelivery = !!enabled
+    return this
+  }
+
   /**
    * Claim messages and report what the broker chose for this pop.
    *
@@ -437,15 +482,17 @@ export class QueueBuilder {
   }
 
   async #popWithDecision() {
-    logger.log('QueueBuilder.pop', { queue: this.#queueName, partition: this.#partition, namespace: this.#namespace, task: this.#task, batch: this.#batch, wait: this.#wait, group: this.#group })
+    // For pop(), use POP defaults (not CONSUME defaults) for what the caller
+    // did not set. autoAck() is consume()'s ack after the handler and never
+    // reaches the wire; the broker's at-most-once autoAck travels only from
+    // commitOnDelivery(). Without it a pop comes back leased.
+    const effectiveWait = this.#wait ?? POP_DEFAULTS.wait
+
+    logger.log('QueueBuilder.pop', { queue: this.#queueName, partition: this.#partition, namespace: this.#namespace, task: this.#task, batch: this.#batch, wait: effectiveWait, group: this.#group })
     
     try {
       const path = this.#buildPopPath()
       
-      // For pop(), use POP defaults (not CONSUME defaults)
-      // Override autoAck to false unless explicitly set
-      const effectiveAutoAck = this.#autoAck !== CONSUME_DEFAULTS.autoAck ? this.#autoAck : POP_DEFAULTS.autoAck
-      
       // Batch, partitions and with them the autopilot flag. The RULE for which
       // of the three travel lives in one place (utils/autopilot.js) because
       // consume() builds its query string separately; only the PLACEMENT is
@@ -458,17 +505,18 @@ export class QueueBuilder {
         autopilot: this.#autopilotEnabled()
       })
 
-      // Build params with correct autoAck for pop
       const params = new URLSearchParams()
       if (sizing.autopilot) params.append('autopilot', 'true')
       if (sizing.batch !== null) params.append('batch', sizing.batch)
-      params.append('wait', this.#wait.toString())
+      params.append('wait', effectiveWait.toString())
       params.append('timeout', this.#timeoutMillis.toString())
 
       if (this.#group) params.append('consumerGroup', this.#group)
       if (this.#namespace) params.append('namespace', this.#namespace)
       if (this.#task) params.append('task', this.#task)
-      if (effectiveAutoAck) params.append('autoAck', 'true')
+      // Sent only when true, where earlier SDKs placed it: an absent autoAck
+      // is the broker's leased default.
+      if (this.#commitOnDelivery) params.append('autoAck', 'true')
       if (this.#subscriptionMode) params.append('subscriptionMode', this.#subscriptionMode)
       if (this.#subscriptionFrom) params.append('subscriptionFrom', this.#subscriptionFrom)
       if (sizing.partitions !== null) params.append('partitions', sizing.partitions)
@@ -483,7 +531,7 @@ export class QueueBuilder {
 
       // wait=true is a long-poll: on 429 it should back off and keep waiting
       // rather than give up after a handful of tries (retryKind: 'pop').
-      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey, this.#wait ? 'pop' : null)
+      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey, effectiveWait ? 'pop' : null)
 
       // Degrade-loudly (PLAN_CONFLATION §4), BEFORE the empty-response return:
       // an old broker's empty pop is a bodiless 204 (result === null), and that
@@ -517,8 +565,8 @@ export class QueueBuilder {
       // messages right now"; for a declared conflation it would mean "your
       // last-value policy is not in force and you will never be told", which is
       // the silent failure the feature is not allowed to have (§4). Both the
-      // missing-echo error and the broker's 400 refusals (queue mode / autoAck)
-      // are permanent config faults, so they raise.
+      // missing-echo error and the broker's 400 refusals (queue mode /
+      // commitOnDelivery) are permanent config faults, so they raise.
       if (error.code === CONFLATION_UNSUPPORTED || (this.#conflation && error.status === 400)) {
         logger.error('QueueBuilder.pop', { error: error.message, status: error.status, code: error.code, conflation: true })
         throw error
@@ -550,17 +598,18 @@ export class QueueBuilder {
 
   // NOTE: a second, DEAD copy of the pop parameter builder lived here and was
   // deleted with the kv/timers work (PLAN_KV_TIMERS.md §10.4). pop() builds its
-  // own params inline, above, because it has to override autoAck with the POP
-  // defaults; the dead copy did not. Anyone adding a parameter by looking for
-  // the method whose name says "build pop params" would have added it to the
-  // copy nobody calls: the pop would keep working and the parameter would
-  // simply never arrive, which reads as a server-side mystery and not as a
-  // client bug.
+  // own params inline, above, because it uses the POP defaults and carries
+  // commitOnDelivery, which consume() refuses. Anyone adding a parameter by
+  // looking for the method whose name says "build pop params" would have added
+  // it to the copy nobody calls: the pop would keep working and the parameter
+  // would simply never arrive, which reads as a server-side mystery and not as
+  // a client bug.
   //
   // The pair that is still live and MUST be kept in sync is pop()'s inline
   // params above and ConsumerManager#buildParams: every pop query parameter
   // (subscriptionMode, subscriptionFrom, partitions, conflation, ...) has to be
-  // appended in BOTH, because pop() and consume() share no builder.
+  // appended in BOTH, because pop() and consume() share no builder. The one
+  // exception is commitOnDelivery's autoAck=true: consume() throws instead.
 
   // ===========================
   // Buffer Management Methods

package/client-v2/consumer/ConsumerManager.js

@@ -211,20 +211,25 @@ export class ConsumerManager {
         try {
           // Process messages
           if (each) {
-            // Process one at a time
+            // Process one at a time. A nack releases the failed message's
+            // partition and clamps that partition's cursor at it: the later
+            // messages of THAT partition will be redelivered, so handling them
+            // now would only produce duplicates and rejected acks. The other
+            // partitions of a multi-partition pop are still leased to this
+            // worker, so their messages are handled now, not after the lease.
+            const nackedPartitions = new Set()
             for (const message of messages) {
               if (signal && signal.aborted) break
 
+              const partition = message.partitionId ?? message.partition
+              if (nackedPartitions.has(partition)) continue
+
               const ok = await this.#processMessage(message, handler, autoAck, group)
               processedCount++
 
-              // A nack releases the lease and clamps the server cursor at the
-              // failed message: everything after it in this popped batch WILL
-              // be redelivered. Processing it now would only produce duplicates
-              // and rejected acks — abandon the rest of the batch.
               if (!ok) {
-                logger.warn('ConsumerManager.worker', { workerId, status: 'batch-abandoned-after-nack', remaining: messages.length - messages.indexOf(message) - 1 })
-                break
+                nackedPartitions.add(partition)
+                logger.warn('ConsumerManager.worker', { workerId, status: 'partition-abandoned-after-nack', partition })
               }
 
               if (limit && processedCount >= limit) break

package/client-v2/ephemeral/Ephemeral.js

@@ -17,12 +17,13 @@
  * history to have.
  *
  * DELIVERY IS NOT "AT MOST ONCE" (§1.3), and the docs must not say it is. The
- * class picks what can be LOST; the ack mode picks the guarantee. `autoAck`
- * advances the cursor at delivery and is at-most-once. The default -- explicit
- * ack -- is at-least-once for as long as the owning broker incarnation lives:
- * an unacked message redelivers when its lease expires, with `attempts`
- * incremented, until `retryLimit`, after which it is DROPPED and counted (no
- * DLQ, §9). Consumers still need idempotency, exactly as on durable queues.
+ * class picks what can be LOST; the ack mode picks the guarantee.
+ * `commitOnDelivery` advances the cursor at delivery and is at-most-once. The
+ * default -- explicit ack -- is at-least-once for as long as the owning broker
+ * incarnation lives: an unacked message redelivers when its lease expires,
+ * with `attempts` incremented, until `retryLimit`, after which it is DROPPED
+ * and counted (no DLQ, §9). Consumers still need idempotency, exactly as on
+ * durable queues.
  *
  * CONSUMPTION SEMANTICS COME FROM THE GROUP, EXACTLY AS ON THE DURABLE ENGINE
  * (§1.5). There is no queue-level mode to choose:
@@ -404,7 +405,23 @@ export class Ephemeral {
    *
    * `group` is the whole of the consumption semantics (§1.5): same group =
    * competing consumers, own group = fan-out, no group = queue mode.
-   * `autoAck:true` commits at delivery and is at-most-once.
+   *
+   * `commitOnDelivery:true` commits at delivery: the broker moves the group's
+   * cursor past the messages as it hands them out, with no lease and nothing
+   * to ack. That is at-most-once: a crash after the pop loses them. It
+   * travels as `autoAck=true`, the parameter the broker reads.
+   *
+   * @param {string} queue
+   * @param {object} [opts]
+   * @param {string} [opts.partition]
+   * @param {number} [opts.batch]
+   * @param {boolean} [opts.wait]
+   * @param {number} [opts.timeout] Milliseconds; `timeoutMillis` is the same.
+   * @param {string} [opts.group]
+   * @param {boolean} [opts.commitOnDelivery] Commit at delivery (at-most-once).
+   * @param {boolean} [opts.autoAck] Deprecated: the old name of
+   *   `commitOnDelivery`, still read with the same meaning. Pass one or the
+   *   other, not both.
    */
   async pop(queue, opts = {}) {
     requireQueue(queue)
@@ -413,6 +430,7 @@ export class Ephemeral {
     const group = opts.group ?? null
     const wait = opts.wait === true
     const timeoutMillis = resolveTimeout(opts)
+    const commitOnDelivery = resolveCommitOnDelivery(opts)
 
     const params = new URLSearchParams({ queue })
     if (partition !== null) params.append('partition', partition)
@@ -424,7 +442,7 @@ export class Ephemeral {
       params.append('timeout', String(timeoutMillis))
     }
     if (group !== null) params.append('group', group)
-    if (opts.autoAck === true) params.append('autoAck', 'true')
+    if (commitOnDelivery) params.append('autoAck', 'true')
 
     logger.log('Ephemeral.pop', { queue, partition, group, batch: opts.batch ?? null, wait })
 
@@ -547,3 +565,17 @@ function resolveTimeout(opts) {
   if (hasMillis) return opts.timeoutMillis
   return DEFAULT_WAIT_TIMEOUT_MILLIS
 }
+
+/**
+ * The pop's commit at delivery, from `commitOnDelivery` or its deprecated
+ * alias `autoAck`. Both spellings at once are refused, as for the timeout: two
+ * values for one setting would have to be resolved by a rule nobody reads.
+ */
+function resolveCommitOnDelivery(opts) {
+  const hasName = opts.commitOnDelivery !== undefined && opts.commitOnDelivery !== null
+  const hasAlias = opts.autoAck !== undefined && opts.autoAck !== null
+  if (hasName && hasAlias) {
+    throw new Error('ephemeral: pass either `commitOnDelivery` or its deprecated alias `autoAck`, not both')
+  }
+  return (hasName ? opts.commitOnDelivery : opts.autoAck) === true
+}

package/client-v2/utils/defaults.js

@@ -81,9 +81,10 @@ export const CONSUME_DEFAULTS = {
 // As in CONSUME_DEFAULTS, batch is the autopilot-OFF default.
 export const POP_DEFAULTS = {
   batch: 1,                            // One message (autopilot off only)
-  wait: false,                         // No long polling (immediate return)
+  wait: true,                          // Long polling, as every pop has done; .wait(false) returns at once
   timeoutMillis: 30000,                // 30 seconds if wait=true
-  autoAck: false                       // Server-side auto-ack (false = manual ack required)
+  autoAck: false,                      // Never sent: autoAck() is consume()'s ack after the handler
+  commitOnDelivery: false              // Leased; true sends autoAck=true, the broker's at-most-once commit at delivery
 }
 
 export const BUFFER_DEFAULTS = {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "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": "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": "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/consumer-unit/nackScope.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-v2/pop-unit/popDefaults.test.js test-v2/admin-unit/removedRoutes.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",

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/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/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/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')
+    })
+  })
+})

package/test-v2/pop.js

@@ -361,3 +361,71 @@ export async function renewReportsAReleasedLease(client) {
                     released.success === false && released.newExpiresAt === null && typeof released.error === 'string'
     return { success, message: `live lease: ${JSON.stringify(live)}; after the ack: ${JSON.stringify(released)}` }
 }
+
+
+// autoAck() is consume()'s ack after the handler and never reaches the wire: a
+// pop after autoAck(true) is leased like any pop, and with a 1 s lease the
+// message comes back. The broker's at-most-once autoAck is commitOnDelivery().
+export async function popAutoAckStaysLeased(client) {
+    const queueName = 'test-queue-v2-pop-auto-ack'
+    const queue = await client.queue(queueName).config({ leaseTime: 1 }).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    await client.queue(queueName).push([{ data: { n: 1 } }])
+
+    const [message] = await client.queue(queueName).batch(1).wait(true).timeoutMillis(5000).autoAck(true).pop()
+    if (!message) {
+        return { success: false, message: 'Nothing popped' }
+    }
+    // Past the 1 s lease: a leased message is delivered again now.
+    await new Promise(resolve => setTimeout(resolve, 2500))
+    const again = await client.queue(queueName).batch(1).wait(true).timeoutMillis(3000).pop()
+
+    const success = typeof message.leaseId === 'string' && message.leaseId !== '' && again.length === 1
+    return { success, message: `leaseId ${JSON.stringify(message.leaseId)}, delivered again after the lease: ${again.length}` }
+}
+
+// commitOnDelivery() sends autoAck=true: the broker moves the group's cursor
+// past the message as it hands it out, so the pop has no lease and the message
+// does not come back after the 1 s lease of the queue.
+export async function popCommitOnDeliveryNotRedelivered(client) {
+    const queueName = 'test-queue-v2-pop-commit-on-delivery'
+    const queue = await client.queue(queueName).config({ leaseTime: 1 }).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    await client.queue(queueName).push([{ data: { n: 1 } }])
+
+    const [message] = await client.queue(queueName).batch(1).wait(true).timeoutMillis(5000).commitOnDelivery().pop()
+    if (!message) {
+        return { success: false, message: 'Nothing popped' }
+    }
+    // Past the 1 s lease: a leased message would be delivered again now.
+    await new Promise(resolve => setTimeout(resolve, 2500))
+    const again = await client.queue(queueName).batch(1).wait(true).timeoutMillis(1500).pop()
+
+    const success = !message.leaseId && again.length === 0
+    return { success, message: `leaseId ${JSON.stringify(message.leaseId)}, delivered again after the lease: ${again.length}` }
+}
+
+// pop() long-polls by default (POP_DEFAULTS.wait), and wait(false) returns at
+// once.
+export async function popLongPollsByDefault(client) {
+    const queueName = 'test-queue-v2-pop-wait-default'
+    const queue = await client.queue(queueName).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    let started = Date.now()
+    const waited = await client.queue(queueName).batch(1).timeoutMillis(1500).pop()
+    const waitedMillis = Date.now() - started
+    started = Date.now()
+    const atOnce = await client.queue(queueName).batch(1).wait(false).pop()
+    const atOnceMillis = Date.now() - started
+
+    return {
+        success: waited.length === 0 && waitedMillis >= 1000 && atOnce.length === 0 && atOnceMillis < 1000,
+        message: `empty pop: ${waitedMillis} ms by default (long poll of 1500 ms), ${atOnceMillis} ms with wait(false)`,
+    }
+}