queen-mq 1.1.0 → 1.3.0

package/README.md

@@ -333,12 +333,64 @@ per-tenant work queues, per-device telemetry). Reduces network round-trips
 from O(P) to O(P / N) while preserving per-partition FIFO ordering.
 
 **When not to use:** few partitions, or each one busy enough to fill
-`batch(B)` on its own. Default is `partitions(1)` which preserves the
-legacy single-partition behaviour.
+`batch(B)` on its own. Leaving `.partitions()` unset hands the sweep width to
+the broker (see Pop Autopilot below); `.partitions(1)` pins the legacy
+single-partition behaviour.
 
 `.partitions(N)` only applies to **wildcard** pops; specifying
 `.partition('name')` ignores the cap.
 
+### Pop Autopilot (Let the Broker Size the Pop)
+
+Since 1.2, `batch` and `partitions` that you do **not** set are chosen by the
+broker, per pop, from state the client cannot see: how many partitions of the
+group are ready, how old their oldest ready message is, how fast messages are
+arriving. The knobs you *do* set are never touched.
+
+```javascript
+// Both knobs are the broker's: it picks the sweep width and the budget.
+await queen.queue('events').group('workers')
+  .consume(async (msgs) => { /* ... */ })
+
+// One knob pinned, one delegated: this consumer stays on one partition
+// forever, and the broker sizes the batch for it.
+await queen.queue('events').group('workers').partitions(1)
+  .consume(async (msgs) => { /* ... */ })
+```
+
+The request carries `autopilot=true` and simply omits the delegated knobs.
+Setting both leaves nothing to decide, so nothing changes on the wire at all.
+
+**Two ways to switch it off**, both restoring the previous client-side
+defaults (batch 1, partitions 1) byte for byte:
+
+```javascript
+await queen.queue('events').autopilot(false).consume(handler)
+```
+
+```bash
+QUEEN_SDK_POP_AUTOPILOT=off   # whole process, read once at client creation
+```
+
+**What the broker chose** rides back on the response and is there for the
+reading, along with an optional pacing hint the consume loop honours in place
+of its own delay between empty polls:
+
+```javascript
+const { messages, autopilot } = await queen.queue('events').group('workers').popResult()
+if (autopilot) {
+  console.log(`${autopilot.partitions} partitions, batch ${autopilot.batch}, ` +
+              `poll again in ${autopilot.waitMillis}ms`)
+}
+```
+
+**Requires broker >= 1.2.** An older broker ignores the parameter, so the
+omitted knobs take *its* defaults (batch 200, partitions 1) instead of the old
+client-side ones. That is a sizing difference and nothing else — no message is
+lost, reordered or duplicated — so unlike conflation it degrades silently and
+on purpose. Pin the values explicitly, or turn autopilot off, if you need the
+old numbers against an old broker.
+
 ### Transactions (Atomic Operations)
 
 ```javascript
@@ -691,10 +743,11 @@ await queen.queue('q').buffer({ messageCount: 100, timeMillis: 1000 }).push([...
 ### Pop
 
 ```javascript
-const msgs = await queen.queue('q').pop()
+const msgs = await queen.queue('q').pop()                            // broker-sized (see Pop Autopilot)
 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
 ```
 
 ### Consume
@@ -828,7 +881,8 @@ await queen.close()  // Flush buffers and close connections
 ```javascript
 {
   concurrency: 1,
-  batch: 1,
+  batch: 1,              // autopilot OFF only -- unset means the broker sizes it
+  partitions: 1,         // autopilot OFF only -- unset means the broker sizes it
   autoAck: true,
   wait: true,            // Long polling
   timeoutMillis: 30000,
@@ -837,6 +891,11 @@ await queen.close()  // Flush buffers and close connections
 }
 ```
 
+`batch` and `partitions` are the **autopilot-off** defaults: with autopilot on
+(the default) a knob you never set is not defaulted at all, it is delegated to
+the broker. These values are what comes back with `.autopilot(false)` or
+`QUEEN_SDK_POP_AUTOPILOT=off`.
+
 ---
 
 ## Logging

package/client-v2/Queen.js

@@ -14,6 +14,7 @@ import { Ephemeral } from './ephemeral/Ephemeral.js'
 import { StreamBuilder } from './stream/StreamBuilder.js'
 import { StreamConsumer } from './stream/StreamConsumer.js'
 import { Admin } from './admin/Admin.js'
+import { popAutopilotDisabledByEnv } from './utils/autopilot.js'
 import { CLIENT_DEFAULTS } from './utils/defaults.js'
 import { validateUrl, validateUrls } from './utils/validation.js'
 import * as logger from './utils/logger.js'
@@ -68,6 +69,11 @@ export class Queen {
   #admin = null
   #kv = null
   #ephemeral = null
+  // Process-wide kill switch for pop autopilot, read from
+  // QUEEN_SDK_POP_AUTOPILOT once here rather than on every pop: it is a
+  // deployment-level rollback, and re-reading it per request would let a
+  // running process change wire shape halfway through.
+  #autopilotOff = false
 
   constructor(config = {}) {
     // Configure custom logger before anything else.
@@ -83,6 +89,9 @@ export class Queen {
     // Normalize config
     this.#config = this.#normalizeConfig(config)
 
+    // Pop autopilot: on unless the environment rolls it back (utils/autopilot.js).
+    this.#autopilotOff = popAutopilotDisabledByEnv()
+
     // Create HTTP client
     this.#httpClient = this.#createHttpClient()
 
@@ -97,6 +106,15 @@ export class Queen {
     logger.log('Queen.constructor', { status: 'initialized', urls: this.#config.urls.length, handleSignals: this.#config.handleSignals })
   }
 
+  /**
+   * Whether pop autopilot is off for this client because the environment asked
+   * (QUEEN_SDK_POP_AUTOPILOT). Read by the builders; a per-call
+   * `.autopilot(...)` still outranks it.
+   */
+  get autopilotOff() {
+    return this.#autopilotOff
+  }
+
   #normalizeConfig(config) {
     // Handle different input formats
     if (typeof config === 'string') {

package/client-v2/builders/QueueBuilder.js

@@ -13,6 +13,7 @@ import { isValidUUID } from '../utils/validation.js'
 import { durableAddress } from '../buffer/sinks.js'
 import { QUEUE_DEFAULTS, CONSUME_DEFAULTS, POP_DEFAULTS } from '../utils/defaults.js'
 import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/conflation.js'
+import { popSizing, parseAutopilotDecision } from '../utils/autopilot.js'
 import * as logger from '../utils/logger.js'
 
 export class QueueBuilder {
@@ -28,7 +29,12 @@ export class QueueBuilder {
 
   // Consume options
   #concurrency = CONSUME_DEFAULTS.concurrency
-  #batch = CONSUME_DEFAULTS.batch
+  // batch / maxPartitions hold the USER's value, and null means the setter was
+  // never called -- which is the dimension pop autopilot gets to choose. The
+  // client-side defaults are applied at emission time (utils/autopilot.js), not
+  // here, because filling them in here would erase the difference between
+  // "never called batch()" and "called batch(1)".
+  #batch = null
   #limit = CONSUME_DEFAULTS.limit
   #idleMillis = CONSUME_DEFAULTS.idleMillis
   #autoAck = CONSUME_DEFAULTS.autoAck
@@ -40,7 +46,10 @@ export class QueueBuilder {
   #subscriptionFrom = CONSUME_DEFAULTS.subscriptionFrom
   #conflation = CONSUME_DEFAULTS.conflation
   #each = false
-  #maxPartitions = 1
+  #maxPartitions = null
+  // Per-call override for pop autopilot: null = the client default (on unless
+  // QUEEN_SDK_POP_AUTOPILOT turned it off).
+  #autopilot = null
 
   // Buffer options
   #bufferOptions = null
@@ -214,8 +223,15 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * Pin the message budget for one pop. Leave it unset and the broker sizes it
+   * (see `autopilot`), where it used to mean the client-side default of 1.
+   *
+   * `batch(0)` is not "a batch of zero" and never was: it is the absence of an
+   * opinion, so it reads as unset.
+   */
   batch(size) {
-    this.#batch = Math.max(1, size)
+    this.#batch = size > 0 ? size : null
     return this
   }
 
@@ -228,13 +244,45 @@ export class QueueBuilder {
    * partitions, in a single network round-trip. All N share one leaseId
    * (renewing once extends them all).
    *
-   * Default 1 = legacy single-partition behavior.
+   * Leave it unset and the broker chooses the sweep width (see `autopilot`);
+   * `partitions(1)` pins the legacy single-partition behaviour, which is a
+   * decision the broker is told about and never overrides.
    */
   partitions(n) {
-    this.#maxPartitions = Math.max(1, n)
+    this.#maxPartitions = n > 0 ? n : null
+    return this
+  }
+
+  /**
+   * Turn broker-side pop sizing on or off for this builder.
+   *
+   * On (the default) the broker chooses `batch` and `partitions` for the pops
+   * of this builder. Even then, a `batch` or `partitions` set explicitly
+   * travels on the wire as it always did and is never second-guessed: autopilot
+   * only ever fills the knobs left unset.
+   *
+   * `autopilot(false)` restores this SDK's pre-1.2 behaviour byte for byte: the
+   * client-side defaults come back (batch 1, partitions 1) and no autopilot
+   * parameter is sent. QUEEN_SDK_POP_AUTOPILOT=off does the same for a whole
+   * process; an explicit call here outranks the environment in both directions.
+   *
+   * Setting BOTH batch and partitions leaves autopilot nothing to decide, so no
+   * autopilot parameter is sent in that case either, whatever this flag says.
+   */
+  autopilot(enabled = true) {
+    this.#autopilot = !!enabled
     return this
   }
 
+  /**
+   * This builder's resolved autopilot decision: its own flag when set,
+   * otherwise the client-wide default settled in the Queen constructor.
+   */
+  #autopilotEnabled() {
+    if (this.#autopilot !== null) return this.#autopilot
+    return !this.#queen || !this.#queen.autopilotOff
+  }
+
   limit(count) {
     this.#limit = count
     return this
@@ -326,6 +374,11 @@ export class QueueBuilder {
       conflation: this.#conflation,
       each: this.#each,
       maxPartitions: this.#maxPartitions,
+      // Resolved here so ConsumerManager sees a decision and not a null. batch
+      // and maxPartitions keep their null when autopilot is on, and that null
+      // has to survive all the way to #buildParams: it is the ONLY record that
+      // the user said nothing about that dimension.
+      autopilot: this.#autopilotEnabled(),
       signal: options.signal
     }
 
@@ -355,7 +408,27 @@ export class QueueBuilder {
     return this
   }
 
+  /**
+   * Claim messages and report what the broker chose for this pop.
+   *
+   * Same call as `pop()` — this is the shape that also carries the additive
+   * `autopilot` echo, which is null when this pop did not engage autopilot or
+   * the broker is older than 1.2.
+   *
+   *   const { messages, autopilot } = await client.queue('events').group('w').popResult()
+   *   if (autopilot) console.log(autopilot.partitions, autopilot.batch, autopilot.waitMillis)
+   *
+   * @returns {Promise<{messages: object[], autopilot: {partitions: number, batch: number, waitMillis: number}|null}>}
+   */
+  async popResult() {
+    return this.#popWithDecision()
+  }
+
   async pop() {
+    return (await this.#popWithDecision()).messages
+  }
+
+  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 })
     
     try {
@@ -365,20 +438,32 @@ export class QueueBuilder {
       // Override autoAck to false unless explicitly set
       const effectiveAutoAck = this.#autoAck !== CONSUME_DEFAULTS.autoAck ? this.#autoAck : POP_DEFAULTS.autoAck
       
-      // Build params with correct autoAck for pop
-      const params = new URLSearchParams({
-        batch: this.#batch.toString(),
-        wait: this.#wait.toString(),
-        timeout: this.#timeoutMillis.toString()
+      // 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
+      // here, and it is the pre-autopilot placement so an autopilot-off request
+      // is byte-identical to the one this SDK used to send.
+      const sizing = popSizing({
+        batch: this.#batch,
+        maxPartitions: this.#maxPartitions,
+        fallbackBatch: POP_DEFAULTS.batch,
+        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('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')
       if (this.#subscriptionMode) params.append('subscriptionMode', this.#subscriptionMode)
       if (this.#subscriptionFrom) params.append('subscriptionFrom', this.#subscriptionFrom)
-      if (this.#maxPartitions > 1) params.append('partitions', this.#maxPartitions.toString())
+      if (sizing.partitions !== null) params.append('partitions', sizing.partitions)
       // Conflation (PLAN_CONFLATION §3.1): sent ONLY when true, so an
       // undeclared pop is byte-identical to today. NOTE: this is the pop
       // builder; consume() builds its params in ConsumerManager#buildParams —
@@ -405,14 +490,19 @@ export class QueueBuilder {
         })
       }
 
+      // The broker's own account of how it sized this pop, when the request
+      // engaged autopilot and the answer had a body to carry it (a bodiless 204
+      // cannot, so an empty short pop reports null).
+      const autopilot = parseAutopilotDecision(result)
+
       if (!result || !result.messages) {
         logger.log('QueueBuilder.pop', { status: 'no-messages' })
-        return []
+        return { messages: [], autopilot }
       }
 
       const messages = result.messages.filter(msg => msg != null)
       logger.log('QueueBuilder.pop', { status: 'success', count: messages.length })
-      return messages
+      return { messages, autopilot }
     } catch (error) {
       // Conflation is the one thing this method does NOT swallow. The
       // swallow-to-[] contract exists for transport faults, where [] means "no
@@ -431,7 +521,7 @@ export class QueueBuilder {
       // both are logged with their `.code` rather than raising, matching this
       // method's existing swallow-to-[] contract.
       logger.error('QueueBuilder.pop', { error: error.message, status: error.status, code: error.code })
-      return []
+      return { messages: [], autopilot: null }
     }
   }
 

package/client-v2/consumer/ConsumerManager.js

@@ -4,6 +4,8 @@
 
 import * as logger from '../utils/logger.js'
 import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/conflation.js'
+import { popSizing, parseAutopilotDecision, emptyPollDelayMillis } from '../utils/autopilot.js'
+import { CONSUME_DEFAULTS } from '../utils/defaults.js'
 
 export class ConsumerManager {
   #httpClient
@@ -51,6 +53,7 @@ export class ConsumerManager {
       conflation,
       each,
       maxPartitions,
+      autopilot,
       signal
     } = options
 
@@ -70,7 +73,7 @@ export class ConsumerManager {
 
     // Build the path and params for pop requests
     const path = this.#buildPath(queue, partition, namespace, task)
-    const baseParams = this.#buildParams(batch, wait, timeoutMillis, group, subscriptionMode, subscriptionFrom, namespace, task, autoAck, maxPartitions, conflation)
+    const baseParams = this.#buildParams(batch, wait, timeoutMillis, group, subscriptionMode, subscriptionFrom, namespace, task, autoAck, maxPartitions, conflation, this.#autopilotEnabled(autopilot))
     
     // Generate affinity key for consistent routing to same backend
     const affinityKey = this.#getAffinityKey(queue, partition, namespace, task, group)
@@ -174,8 +177,11 @@ export class ConsumerManager {
           if (wait) {
             continue // Long polling timeout, retry
           } else {
-            // Short delay before retry
-            await new Promise(resolve => setTimeout(resolve, 100))
+            // Short delay before retry -- the broker's advised pacing when this
+            // pop engaged autopilot and the broker had an opinion (it knows the
+            // arrival rate on this queue and this client does not), otherwise
+            // the historical 100ms.
+            await new Promise(resolve => setTimeout(resolve, emptyPollDelayMillis(parseAutopilotDecision(result))))
             continue
           }
         }
@@ -472,20 +478,46 @@ export class ConsumerManager {
     throw new Error('Must specify queue, namespace, or task')
   }
 
-  #buildParams(batch, wait, timeoutMillis, group, subscriptionMode, subscriptionFrom, namespace, task, autoAck, maxPartitions, conflation) {
-    const params = new URLSearchParams({
-      batch: batch.toString(),
-      wait: wait.toString(),
-      timeout: timeoutMillis.toString()  // Server expects 'timeout', not 'timeoutMillis'
+  /**
+   * The autopilot decision for one consume: the caller's explicit option if
+   * there is one, otherwise the client-wide default settled in the Queen
+   * constructor. The builder path has already resolved it; the undefined case
+   * is for callers that drive ConsumerManager with options of their own.
+   */
+  #autopilotEnabled(autopilot) {
+    if (typeof autopilot === 'boolean') return autopilot
+    return !this.#queen || !this.#queen.autopilotOff
+  }
+
+  #buildParams(batch, wait, timeoutMillis, group, subscriptionMode, subscriptionFrom, namespace, task, autoAck, maxPartitions, conflation, autopilot = true) {
+    // Batch, partitions and with them the autopilot flag. null/0 means the user
+    // set nothing (QueueBuilder leaves it that way on purpose), which is the
+    // dimension the broker gets to choose. THE RULE lives in one place
+    // (utils/autopilot.js) precisely because this is the SECOND parameter
+    // builder; only the placement of the keys is here, and it is the
+    // pre-autopilot placement so an autopilot-off request is byte-identical.
+    const sizing = popSizing({
+      batch,
+      maxPartitions,
+      fallbackBatch: CONSUME_DEFAULTS.batch,
+      autopilot
     })
 
+    const params = new URLSearchParams()
+    if (sizing.autopilot) params.append('autopilot', 'true')
+    if (sizing.batch !== null) params.append('batch', sizing.batch)
+    params.append('wait', wait.toString())
+    params.append('timeout', timeoutMillis.toString())  // Server expects 'timeout', not 'timeoutMillis'
+
     if (group) params.append('consumerGroup', group)
     if (subscriptionMode) params.append('subscriptionMode', subscriptionMode)
     if (subscriptionFrom) params.append('subscriptionFrom', subscriptionFrom)
     if (namespace) params.append('namespace', namespace)
     if (task) params.append('task', task)
-    // v4 multi-partition pop: drain up to N sparse partitions per call.
-    if (maxPartitions && maxPartitions > 1) params.append('partitions', maxPartitions.toString())
+    // v4 multi-partition pop: drain up to N sparse partitions per call. Under
+    // autopilot a pinned width travels even when it is 1, because 1 is then a
+    // decision and not the absence of one.
+    if (sizing.partitions !== null) params.append('partitions', sizing.partitions)
     // Conflation (PLAN_CONFLATION §3.1): last-value delivery for this group.
     // Sent ONLY when true, so a consumer that never declares it puts no new
     // bytes on the wire. THIS IS THE SECOND PARAMETER BUILDER — the pop() one

package/client-v2/streams/runtime/Runner.js

@@ -240,9 +240,14 @@ export class Runner {
       .timeoutMillis(this.maxWaitMillis)
       .group(this.consumerGroup)
 
-    if (this.maxPartitions > 1) {
-      qb = qb.partitions(this.maxPartitions)
-    }
+    // Unconditional, and it has to be: the runtime has already defaulted
+    // maxPartitions (to 4), so this is always a decision the streams layer
+    // made. Skipping the call for maxPartitions === 1 used to be a harmless
+    // optimisation -- 1 was what an omitted `partitions` meant on the wire --
+    // but with pop autopilot an omitted `partitions` means "broker, you
+    // choose", which would widen a query that explicitly asked for one
+    // partition per pop.
+    qb = qb.partitions(this.maxPartitions)
     if (this.subscriptionMode) qb = qb.subscriptionMode(this.subscriptionMode)
     if (this.subscriptionFrom) qb = qb.subscriptionFrom(this.subscriptionFrom)
     if (this.conflation) qb = qb.conflation(true)

package/client-v2/utils/autopilot.js

@@ -0,0 +1,168 @@
+/**
+ * Pop autopilot, client side.
+ *
+ * The broker owns a controller that sizes a pop from state this client cannot
+ * see: how many partitions of the (queue, group) are ready, how old their
+ * oldest ready message is, at what rate messages are arriving. Two knobs are
+ * under its control — `partitions` (the sweep width) and `batch` (the message
+ * budget for the sweep).
+ *
+ * THE RULE, and it is the only one: an explicit user value is sacred. Autopilot
+ * applies ONLY to the knobs the user left unset, and it applies to them one by
+ * one. A consumer that pins `partitions(1)` and says nothing about batch keeps
+ * its single-partition claim forever and lets the broker size the batch; the
+ * pinned dimension is never "adjusted", not even towards a value the controller
+ * would consider better.
+ *
+ * The wire shape follows the conflation precedent (see conflation.js): a client
+ * that is not engaging autopilot sends the byte-identical request it sent
+ * before this feature existed.
+ *
+ *   autopilot=true      emitted ONLY when at least one of the two knobs is
+ *                       being left to the broker. Never as autopilot=false.
+ *   partitions / batch  OMITTED for the dimensions the broker is choosing,
+ *                       sent exactly as before for the ones the user set.
+ *
+ * WHAT AN OLD BROKER DOES, and why there is no capability check here. A broker
+ * older than 1.2 ignores unknown query params: the request succeeds, and the
+ * two omitted knobs fall back to the SERVER-side defaults (batch 200,
+ * partitions 1) instead of the old client-side ones. That is a sizing
+ * difference, not a correctness one — nothing is lost, misordered or delivered
+ * twice — so unlike conflation (which silently hands a last-value consumer a
+ * whole backlog, hence CONFLATION_UNSUPPORTED) this degrades quietly and on
+ * purpose. Callers who need the old numbers against an old broker set them
+ * explicitly, or turn autopilot off.
+ */
+
+/**
+ * The environment variable that disables pop autopilot for a whole process:
+ * QUEEN_SDK_POP_AUTOPILOT=off restores the client-side defaults this SDK
+ * applied before autopilot existed, byte for byte. It is read once, in the
+ * Queen constructor, so a single deployment can be rolled back without touching
+ * code.
+ *
+ * "off", "false", "0", "no" and "disabled" all disable it (case-insensitive,
+ * surrounding space ignored). Every other value, including the empty one,
+ * leaves autopilot on.
+ */
+export const ENV_POP_AUTOPILOT = 'QUEEN_SDK_POP_AUTOPILOT'
+
+const DISABLING_VALUES = new Set(['off', 'false', '0', 'no', 'disabled'])
+
+/** Whether ENV_POP_AUTOPILOT asks for the pre-autopilot behavior. */
+export function popAutopilotDisabledByEnv() {
+  // `process` is absent in a browser bundle; there the variable cannot be set
+  // and autopilot is simply on.
+  const raw = typeof process !== 'undefined' && process.env ? process.env[ENV_POP_AUTOPILOT] : undefined
+  return DISABLING_VALUES.has(String(raw ?? '').trim().toLowerCase())
+}
+
+/**
+ * The batch/partitions/autopilot decision for one pop — the values that travel
+ * and the ones that do not.
+ *
+ * IT EXISTS SO THERE IS EXACTLY ONE COPY OF THE EMISSION RULE. pop() and
+ * consume() build their query strings separately (QueueBuilder.pop's inline
+ * params vs ConsumerManager#buildParams) and the two have drifted before — the
+ * standing comment in QueueBuilder.js is there because of it. A rule with three
+ * branches and a per-dimension carve-out is precisely the kind that gets copied
+ * wrong, so both builders call this and then only PLACE what it returns; where
+ * each key sits in the query string stays with the builder, because the
+ * pre-autopilot key order is part of what "byte-identical" means here.
+ *
+ * @param {object} opts
+ * @param {number|null} opts.batch - the USER's batch. null/0/undefined means
+ *   unset: the dimension the broker gets to choose. Neither builder may
+ *   substitute a default before calling this.
+ * @param {number|null} opts.maxPartitions - the USER's sweep width, same
+ *   convention.
+ * @param {number} opts.fallbackBatch - client-side default applied to an unset
+ *   batch when autopilot is NOT engaged.
+ * @param {boolean} opts.autopilot - the resolved decision for this call.
+ * @returns {{autopilot: boolean, batch: string|null, partitions: string|null}}
+ *   Strings are ready to append; null means "this key does not travel".
+ */
+export function popSizing({ batch, maxPartitions, fallbackBatch, autopilot }) {
+  const batchSet = typeof batch === 'number' && batch > 0
+  const partitionsSet = typeof maxPartitions === 'number' && maxPartitions > 0
+
+  // Note the case that looks like an omission and is not: when the user set
+  // BOTH knobs there is nothing left for the controller to decide, so
+  // autopilot=true is NOT emitted and the request is byte-identical to the one
+  // this SDK sent before autopilot existed. Sending the flag anyway would be
+  // harmless on the broker and dishonest in a packet capture.
+  if (autopilot && !(batchSet && partitionsSet)) {
+    return {
+      autopilot: true,
+      batch: batchSet ? String(batch) : null,
+      partitions: partitionsSet ? String(maxPartitions) : null
+    }
+  }
+
+  return {
+    autopilot: false,
+    batch: String(batchSet ? batch : fallbackBatch),
+    // The legacy gate: partitions travels only above 1, because 1 IS the
+    // server-side default and a v4-era client never sent it.
+    partitions: partitionsSet && maxPartitions > 1 ? String(maxPartitions) : null
+  }
+}
+
+/**
+ * What the broker chose for one pop, echoed back in the response under
+ * "autopilot" when the request engaged autopilot. It is additive: a broker that
+ * does not send it, or a pop that never asked, yields null everywhere it is
+ * exposed.
+ *
+ * Reading it is optional — the messages are already sized by it — but it is the
+ * only way to see the controller working from the client side, and the only
+ * input to the empty-poll pacing below.
+ *
+ * Unknown keys inside it are ignored, and an unknown-shaped value is treated as
+ * absent rather than as an error: this field is the broker telling the client
+ * what it did, and a client that refuses to run because a newer broker grew a
+ * fourth number would be a self-inflicted outage.
+ *
+ * @param {object|null} result - parsed pop response (null for a 204)
+ * @returns {{partitions: number, batch: number, waitMillis: number}|null}
+ */
+export function parseAutopilotDecision(result) {
+  const raw = result && typeof result === 'object' ? result.autopilot : null
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+  return {
+    /** Sweep width the broker used for this pop. */
+    partitions: num(raw.partitions),
+    /** Message budget the broker used for this pop. */
+    batch: num(raw.batch),
+    /**
+     * The broker's advice on how long to wait before polling again (wire name:
+     * waitMs). Present only when the broker has an opinion, and it is advice,
+     * not a lease: the consume loop honors it for the sleep it was already
+     * taking between empty non-waiting pops, nothing more. 0 = no advice.
+     */
+    waitMillis: num(raw.waitMs)
+  }
+}
+
+/**
+ * The sleep the consume loop has always taken between two empty pops that are
+ * NOT long-polling. A waiting pop already blocks on the broker, so it never
+ * reaches here.
+ */
+export const EMPTY_POLL_BACKOFF_MILLIS = 100
+
+/**
+ * How long to wait after an empty pop: the broker's advice when it gave one,
+ * the historical constant otherwise.
+ *
+ * The advice is honored as given, without a ceiling of this client's invention.
+ * The sleep it feeds is raced against the caller's abort signal by the loop, so
+ * even an absurd value cannot outlive a cancellation — which is the only
+ * property that has to hold locally.
+ */
+export function emptyPollDelayMillis(decision) {
+  if (decision && decision.waitMillis > 0) return decision.waitMillis
+  return EMPTY_POLL_BACKOFF_MILLIS
+}

package/client-v2/utils/defaults.js

@@ -51,9 +51,14 @@ export const QUEUE_DEFAULTS = {
   encryptionEnabled: false             // No encryption by default
 }
 
+// batch and maxPartitions here are the AUTOPILOT-OFF defaults. With autopilot on
+// (the default) a knob the caller never set is not defaulted at all -- it is
+// omitted from the pop so the broker sizes it (see utils/autopilot.js). These
+// values are what comes back with QueueBuilder.autopilot(false), or with
+// QUEEN_SDK_POP_AUTOPILOT=off for a whole process.
 export const CONSUME_DEFAULTS = {
   concurrency: 1,                      // Single worker
-  batch: 1,                            // One message at a time
+  batch: 1,                            // One message at a time (autopilot off only)
   autoAck: true,                       // Client-side auto-ack (NOT sent to server)
   wait: true,                          // Long polling enabled
   timeoutMillis: 30000,                // 30 seconds long poll timeout
@@ -63,7 +68,7 @@ export const CONSUME_DEFAULTS = {
   renewLeaseIntervalMillis: null,      // Auto-renewal interval when enabled
   subscriptionMode: null,              // No subscription mode (standard queue mode)
   subscriptionFrom: null,              // No subscription start point
-  maxPartitions: 1,                    // v4 multi-partition pop cap (1 = legacy single-partition)
+  maxPartitions: 1,                    // v4 multi-partition pop cap (autopilot off only)
   // Last-value delivery for this consumer group (PLAN_CONFLATION §1.1): a pop
   // of a partition delivers only the NEWEST visible message and commits past
   // the ones it skipped. Off by default, and only ever SENT when true, so a
@@ -73,8 +78,9 @@ export const CONSUME_DEFAULTS = {
   conflation: false
 }
 
+// As in CONSUME_DEFAULTS, batch is the autopilot-OFF default.
 export const POP_DEFAULTS = {
-  batch: 1,                            // One message
+  batch: 1,                            // One message (autopilot off only)
   wait: false,                         // No long polling (immediate return)
   timeoutMillis: 30000,                // 30 seconds if wait=true
   autoAck: false                       // Server-side auto-ack (false = manual ack required)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Partitioned message queue on PostgreSQL — broker client + fluent streaming SDK (windows, joins, gates) in one package",
   "main": "client-v2/index.js",
   "scripts": {
-    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js && node test-v2/run.js human",
-    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js",
+    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/autopilot-unit/autopilotWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js && node test-v2/run.js human",
+    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js test-v2/streams-unit/ack.test.js test-v2/http-unit/retry429.test.js test-v2/http-unit/hostHeader.test.js test-v2/kv-unit/kvWire.test.js test-v2/kv-unit/timerWire.test.js test-v2/kv-unit/txnWire.test.js test-v2/buffer-unit/buffer.test.js test-v2/conflation-unit/conflationWire.test.js test-v2/autopilot-unit/autopilotWire.test.js test-v2/ephemeral-unit/ephemeralWire.test.js test-v2/ephemeral-unit/ephemeralBuffer.test.js test-v2/ephemeral-unit/durableSinkPin.test.js",
     "test: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/autopilot-unit/autopilotWire.test.js

@@ -0,0 +1,410 @@
+/**
+ * Pop autopilot, client side.
+ *
+ * The four things a client can be wrong about here, and why each is asserted
+ * against the WHOLE query string rather than against one parameter:
+ *
+ *  1. BOTH BUILDERS MUST AGREE. pop() and consume() assemble their query
+ *     strings separately (QueueBuilder.pop's inline params vs
+ *     ConsumerManager#buildParams) — the hazard the standing comment in
+ *     QueueBuilder.js already names. Every case below is run through both, and
+ *     both are compared to the same expected string, so a rule implemented in
+ *     one and not the other cannot pass.
+ *
+ *  2. NOT ENGAGING AUTOPILOT MUST BE BYTE-IDENTICAL TO THE OLD SDK. The escape
+ *     hatch is only worth having if it is exact, and "exact" is not something a
+ *     test of one parameter can show: a stray autopilot=true, or a batch that
+ *     stopped being emitted, is a different request. Hence full-string equality
+ *     including the parameters this feature never touches, and including their
+ *     ORDER — this SDK appends rather than sorting, so order is part of the
+ *     bytes.
+ *
+ *  3. AN EXPLICIT VALUE IS SACRED, PER DIMENSION. partitions(1) and "never
+ *     called partitions" both used to reach the wire as nothing at all; they are
+ *     now different requests, and the pinned one must survive autopilot.
+ *
+ *  4. THE ADDITIVE RESPONSE FIELD MUST NOT BE LOAD-BEARING. A broker that does
+ *     not send it, sends it half-filled, or sends it with fields this SDK has
+ *     never heard of, all have to work.
+ *
+ * Same style as conflation-unit/conflationWire.test.js: a real node:http server
+ * playing a canned plan, real fetch, real JSON, and every assertion is about
+ * bytes that actually crossed a socket.
+ */
+
+import { describe, it, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { Runner } from '../../client-v2/streams/runtime/Runner.js'
+import {
+  ENV_POP_AUTOPILOT,
+  popAutopilotDisabledByEnv,
+  popSizing,
+  parseAutopilotDecision,
+  emptyPollDelayMillis,
+  EMPTY_POLL_BACKOFF_MILLIS
+} from '../../client-v2/utils/autopilot.js'
+import { withPlanServer, ok } from '../kv-unit/_planServer.js'
+
+const QUEUE = 'q'
+const GROUP = 'g'
+
+/** One delivered frame, shaped like a real pop response element. */
+function frame(n = 1) {
+  return {
+    transactionId: `txn-${n}`,
+    partitionId: `part-${n}`,
+    partition: 'Default',
+    payload: { n },
+    leaseId: 'lease-1',
+    consumerGroup: GROUP
+  }
+}
+
+/** A 200 pop body; `extra` carries the additive autopilot echo under test. */
+function popBody(extra = {}, frames = [frame()]) {
+  return ok({ messages: frames, partitionsClaimed: frames.length, ...extra })
+}
+
+/** Query string of a recorded hit, exactly as it crossed the socket. */
+function rawQuery(url) {
+  const i = url.indexOf('?')
+  return i < 0 ? '' : url.slice(i + 1)
+}
+
+/** Only the pop hits — consume also acks, and the ack is not under test here. */
+function popHits(hits) {
+  return hits.filter(h => h.url.startsWith('/api/v1/pop'))
+}
+
+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()
+    }
+  })
+}
+
+afterEach(() => { delete process.env[ENV_POP_AUTOPILOT] })
+
+// ---------------------------------------------------------------------------
+// 1. Param assembly, from both builders.
+// ---------------------------------------------------------------------------
+
+// The shared spine of every case: a named queue and group, no long poll,
+// default timeout. Everything that varies below is sizing.
+const GROUP_AND_TAIL = `wait=false&timeout=30000&consumerGroup=${GROUP}`
+
+const CASES = [
+  {
+    // (a) nothing set: both knobs go to the broker, neither travels.
+    name: 'nothing set',
+    build: qb => qb,
+    want: `autopilot=true&${GROUP_AND_TAIL}`
+  },
+  {
+    // (b) partitions pinned, batch left to the broker.
+    name: 'partitions only',
+    build: qb => qb.partitions(4),
+    want: `autopilot=true&${GROUP_AND_TAIL}&partitions=4`
+  },
+  {
+    // (b') the pin that used to be indistinguishable from unset. partitions(1)
+    // is a decision — hold this consumer to one partition — and the broker has
+    // to be told, or autopilot would widen it.
+    name: 'partitions pinned to one',
+    build: qb => qb.partitions(1),
+    want: `autopilot=true&${GROUP_AND_TAIL}&partitions=1`
+  },
+  {
+    // (c) batch pinned, sweep width left to the broker.
+    name: 'batch only',
+    build: qb => qb.batch(50),
+    want: `autopilot=true&batch=50&${GROUP_AND_TAIL}`
+  },
+  {
+    // (d) both set: nothing left to decide, so no autopilot parameter and the
+    // exact request the pre-autopilot SDK sent.
+    name: 'both set',
+    build: qb => qb.batch(50).partitions(4),
+    want: `batch=50&${GROUP_AND_TAIL}&partitions=4`
+  },
+  {
+    // (d') both set with partitions at 1: still byte-identical to the old SDK,
+    // which never emitted partitions=1.
+    name: 'both set, partitions one',
+    build: qb => qb.batch(50).partitions(1),
+    want: `batch=50&${GROUP_AND_TAIL}`
+  },
+  {
+    // (e) escape hatch, nothing set: the client-side defaults are back.
+    name: 'autopilot off, nothing set',
+    build: qb => qb.autopilot(false),
+    want: `batch=1&${GROUP_AND_TAIL}`
+  },
+  {
+    // (e') escape hatch with a pin: partitions=1 stays off the wire, exactly as
+    // before autopilot existed.
+    name: 'autopilot off, partitions pinned to one',
+    build: qb => qb.autopilot(false).partitions(1),
+    want: `batch=1&${GROUP_AND_TAIL}`
+  },
+  {
+    name: 'autopilot off, both set',
+    build: qb => qb.autopilot(false).batch(50).partitions(4),
+    want: `batch=50&${GROUP_AND_TAIL}&partitions=4`
+  },
+  {
+    // autopilot(true) is the default, spelled out. It must not change anything,
+    // including for a caller who set both knobs.
+    name: 'autopilot explicitly on, both set',
+    build: qb => qb.autopilot(true).batch(50).partitions(4),
+    want: `batch=50&${GROUP_AND_TAIL}&partitions=4`
+  },
+  {
+    // batch(0) is not "a batch of zero" and never was: it is the absence of an
+    // opinion, which now means the broker decides.
+    name: 'batch zero is unset',
+    build: qb => qb.batch(0),
+    want: `autopilot=true&${GROUP_AND_TAIL}`
+  }
+]
+
+describe('pop autopilot — param assembly (pop)', () => {
+  for (const tc of CASES) {
+    it(tc.name, async () => {
+      await withQueen([popBody()], popBody(), async (queen, hits) => {
+        await tc.build(queen.queue(QUEUE).group(GROUP).wait(false)).pop()
+
+        assert.equal(popHits(hits).length, 1)
+        assert.equal(rawQuery(popHits(hits)[0].url), tc.want)
+      })
+    })
+  }
+})
+
+describe('pop autopilot — param assembly (consume)', () => {
+  for (const tc of CASES) {
+    it(tc.name, async () => {
+      await withQueen([popBody()], popBody(), async (queen, hits) => {
+        let handled = 0
+        await tc.build(queen.queue(QUEUE).group(GROUP).wait(false))
+          .limit(1)
+          .consume(() => { handled++ })
+
+        assert.equal(handled, 1)
+        const pops = popHits(hits)
+        assert.ok(pops.length >= 1, 'consume made no pop request')
+        assert.equal(rawQuery(pops[0].url), tc.want)
+      })
+    })
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 2. The process-wide rollback.
+// ---------------------------------------------------------------------------
+
+describe('pop autopilot — QUEEN_SDK_POP_AUTOPILOT', () => {
+  it('a client built while the variable is set sends the pre-autopilot request', async () => {
+    process.env[ENV_POP_AUTOPILOT] = 'off'
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).wait(false).pop()
+
+      assert.equal(rawQuery(popHits(hits)[0].url), `batch=1&${GROUP_AND_TAIL}`)
+    })
+  })
+
+  it('is read ONCE, at construction — changing it later does not move a live client', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      process.env[ENV_POP_AUTOPILOT] = 'off'
+      await queen.queue(QUEUE).group(GROUP).wait(false).pop()
+
+      assert.equal(rawQuery(popHits(hits)[0].url), `autopilot=true&${GROUP_AND_TAIL}`)
+    })
+  })
+
+  it('an explicit .autopilot(true) outranks the environment', async () => {
+    process.env[ENV_POP_AUTOPILOT] = 'off'
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).wait(false).autopilot(true).pop()
+
+      assert.equal(rawQuery(popHits(hits)[0].url), `autopilot=true&${GROUP_AND_TAIL}`)
+    })
+  })
+
+  it('accepts the whole vocabulary, and nothing else', () => {
+    for (const v of ['off', 'OFF', ' off ', 'false', '0', 'no', 'disabled']) {
+      process.env[ENV_POP_AUTOPILOT] = v
+      assert.equal(popAutopilotDisabledByEnv(), true, `${v} should disable autopilot`)
+    }
+    for (const v of ['', 'on', 'true', '1', 'yes', 'nonsense']) {
+      process.env[ENV_POP_AUTOPILOT] = v
+      assert.equal(popAutopilotDisabledByEnv(), false, `${v} should leave autopilot on`)
+    }
+    delete process.env[ENV_POP_AUTOPILOT]
+    assert.equal(popAutopilotDisabledByEnv(), false, 'unset leaves autopilot on')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. The additive response field.
+// ---------------------------------------------------------------------------
+
+describe('pop autopilot — the echo', () => {
+  it('parses what the broker chose and ignores what it did not', () => {
+    assert.equal(parseAutopilotDecision(null), null)
+    assert.equal(parseAutopilotDecision({ messages: [] }), null, 'absent')
+    assert.equal(parseAutopilotDecision({ autopilot: null }), null, 'null')
+    assert.equal(parseAutopilotDecision({ autopilot: true }), null, 'not an object')
+    assert.equal(parseAutopilotDecision({ autopilot: [] }), null, 'an array is not an object')
+
+    assert.deepEqual(
+      parseAutopilotDecision({ autopilot: { partitions: 8, batch: 200, waitMs: 25 } }),
+      { partitions: 8, batch: 200, waitMillis: 25 }
+    )
+    // waitMs is optional: the broker sends it only when it has an opinion.
+    assert.deepEqual(
+      parseAutopilotDecision({ autopilot: { partitions: 4, batch: 64 } }),
+      { partitions: 4, batch: 64, waitMillis: 0 }
+    )
+    // Forward compatibility: a newer broker growing a field must not cost this
+    // client the fields it does understand.
+    assert.deepEqual(
+      parseAutopilotDecision({
+        autopilot: { partitions: 2, batch: 10, waitMs: 5, reason: 'ready_age', confidence: 0.9 }
+      }),
+      { partitions: 2, batch: 10, waitMillis: 5 }
+    )
+    // A field of the wrong type is dropped, not fatal.
+    assert.deepEqual(
+      parseAutopilotDecision({ autopilot: { partitions: 'eight', batch: 10 } }),
+      { partitions: 0, batch: 10, waitMillis: 0 }
+    )
+  })
+
+  it('popResult() hands the caller what the broker chose', async () => {
+    const body = popBody({ autopilot: { partitions: 8, batch: 200, waitMs: 25 } })
+    await withQueen([body], body, async (queen) => {
+      const res = await queen.queue(QUEUE).group(GROUP).wait(false).popResult()
+
+      assert.equal(res.messages.length, 1)
+      assert.deepEqual(res.autopilot, { partitions: 8, batch: 200, waitMillis: 25 })
+    })
+  })
+
+  it('popResult() reports null when the broker said nothing — a 1.1 broker, say', async () => {
+    await withQueen([popBody()], popBody(), async (queen) => {
+      const res = await queen.queue(QUEUE).group(GROUP).wait(false).popResult()
+
+      assert.equal(res.messages.length, 1)
+      assert.equal(res.autopilot, null)
+    })
+  })
+
+  it('pop() still returns a bare array of messages', async () => {
+    const body = popBody({ autopilot: { partitions: 8, batch: 200 } })
+    await withQueen([body], body, async (queen) => {
+      const messages = await queen.queue(QUEUE).group(GROUP).wait(false).pop()
+
+      assert.ok(Array.isArray(messages))
+      assert.equal(messages.length, 1)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. Empty-poll pacing.
+// ---------------------------------------------------------------------------
+
+describe('pop autopilot — empty-poll pacing', () => {
+  it('honours the broker advice, and falls back to the historical delay', () => {
+    assert.equal(emptyPollDelayMillis(null), EMPTY_POLL_BACKOFF_MILLIS)
+    assert.equal(emptyPollDelayMillis({ partitions: 1, batch: 1, waitMillis: 0 }), EMPTY_POLL_BACKOFF_MILLIS)
+    assert.equal(emptyPollDelayMillis({ partitions: 1, batch: 1, waitMillis: 250 }), 250)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 5. The rule itself, in isolation.
+// ---------------------------------------------------------------------------
+
+describe('pop autopilot — popSizing', () => {
+  it('leaves a pinned dimension alone and delegates only the unset one', () => {
+    assert.deepEqual(
+      popSizing({ batch: null, maxPartitions: null, fallbackBatch: 1, autopilot: true }),
+      { autopilot: true, batch: null, partitions: null }
+    )
+    assert.deepEqual(
+      popSizing({ batch: 50, maxPartitions: null, fallbackBatch: 1, autopilot: true }),
+      { autopilot: true, batch: '50', partitions: null }
+    )
+    assert.deepEqual(
+      popSizing({ batch: null, maxPartitions: 1, fallbackBatch: 1, autopilot: true }),
+      { autopilot: true, batch: null, partitions: '1' }
+    )
+    // Both set: nothing to decide, so the flag does not travel either.
+    assert.deepEqual(
+      popSizing({ batch: 50, maxPartitions: 4, fallbackBatch: 1, autopilot: true }),
+      { autopilot: false, batch: '50', partitions: '4' }
+    )
+    // Off: the client-side default comes back and partitions keeps its >1 gate.
+    assert.deepEqual(
+      popSizing({ batch: null, maxPartitions: null, fallbackBatch: 1, autopilot: false }),
+      { autopilot: false, batch: '1', partitions: null }
+    )
+    assert.deepEqual(
+      popSizing({ batch: null, maxPartitions: 1, fallbackBatch: 1, autopilot: false }),
+      { autopilot: false, batch: '1', partitions: null }
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 6. The streams runtime pins its width.
+// ---------------------------------------------------------------------------
+
+describe('pop autopilot — streams runtime', () => {
+  /** A QueueBuilder stand-in that records the chain the runner builds. */
+  function recordingSource(calls) {
+    const qb = {
+      batch(v) { calls.push(['batch', v]); return qb },
+      wait(v) { calls.push(['wait', v]); return qb },
+      timeoutMillis(v) { calls.push(['timeoutMillis', v]); return qb },
+      group(v) { calls.push(['group', v]); return qb },
+      partitions(v) { calls.push(['partitions', v]); return qb },
+      subscriptionMode(v) { calls.push(['subscriptionMode', v]); return qb },
+      subscriptionFrom(v) { calls.push(['subscriptionFrom', v]); return qb },
+      conflation(v) { calls.push(['conflation', v]); return qb },
+      async pop() { return [] }
+    }
+    return qb
+  }
+
+  it('pins maxPartitions even at 1, so autopilot cannot widen a stream cycle', async () => {
+    const calls = []
+    const runner = Object.create(Runner.prototype)
+    Object.assign(runner, {
+      stream: { source: recordingSource(calls) },
+      batchSize: 100,
+      maxWaitMillis: 1000,
+      consumerGroup: 'stream-g',
+      maxPartitions: 1,
+      subscriptionMode: null,
+      subscriptionFrom: null,
+      conflation: false
+    })
+
+    await runner._popMessages()
+
+    assert.deepEqual(
+      calls.filter(([k]) => k === 'partitions'),
+      [['partitions', 1]],
+      'the streams layer always decided its own width; it must keep saying so'
+    )
+  })
+})

package/test-v2/retention.js

@@ -1,6 +1,27 @@
 
-// To pass this test the server needs to 
-// be started with RETENTION_INTERVAL=2000
+// The sweep is periodic AND backs off, so the wait below is a bound, not a guess.
+//
+// retention.rs gives a partition a strike for every visit that deletes nothing
+// and skips it for BACKOFF_BASE_CYCLES (8) cycles after the first one. The
+// sweep that runs while these 100 messages are still younger than
+// `retentionSeconds` is exactly such a fruitless visit, so the partition is
+// parked for 8 * RETENTION_INTERVAL before anything can be deleted:
+//
+//     worst case = retentionSeconds + BACKOFF_BASE_CYCLES * RETENTION_INTERVAL
+//                = 10s             + 8                   * 5s (the default)
+//                = 50s
+//
+// The old wait was 15s, taken from a comment that assumed the broker ran with
+// RETENTION_INTERVAL=2000 -- which no stack in test/compose has ever set. It
+// could not pass once the backoff landed (751435f5), and it is why `suites (js)`
+// was 172/173 red on master for weeks. Measured on the single stack: still
+// present at 15s/25s/35s, deleted by 50s.
+//
+// Do NOT turn this into a poll loop: pop() CONSUMES, so a poll that pops early
+// empties the queue itself and the next read returns 0 whether retention ran or
+// not -- a test that passes for the wrong reason.
+const RETENTION_SWEEP_WAIT_MS = 65000
+
 export async function retentionTest(client) {
     const queueName = 'test-queue-retention-01';
     const queue = await client
@@ -20,7 +41,7 @@ export async function retentionTest(client) {
         .push([{ data: { message: i } }])
     }
 
-    await new Promise(resolve => setTimeout(resolve, 15000))
+    await new Promise(resolve => setTimeout(resolve, RETENTION_SWEEP_WAIT_MS))
 
     const messages = await client
     .queue(queueName)
@@ -32,12 +53,12 @@ export async function retentionTest(client) {
         return { success: true, message: 'Messages cleaned up' }
     }
 
-    return { success: false }
+    return { success: false, message: `retention left ${messages.length}/100 messages after ${RETENTION_SWEEP_WAIT_MS / 1000}s` }
 }
 
 
-// To pass this test the server needs to 
-// be started with RETENTION_INTERVAL=2000
+// maxWaitTimeSeconds eviction, which is a different retention phase with its own
+// backoff map -- so it is not subject to the bound above and 15s has held.
 export async function retentionTestMaxTime(client) {
     const queueName = 'test-queue-retention-02';
     const queue = await client
@@ -65,5 +86,5 @@ export async function retentionTestMaxTime(client) {
         return { success: true, message: 'Messages cleaned up' }
     }
 
-    return { success: false }
+    return { success: false, message: `max-wait eviction left ${messages.length}/100 messages` }
 }

package/test-v2/stream/tumbling.js

@@ -149,12 +149,16 @@ export async function tumblingAggregateAllStats(client) {
   await client.queue(src).create()
   await client.queue(sink).create()
 
-  // Push 5 values into the SAME window (all within 1 second), then idle
-  // flush will close it. Sum = 50, count = 5, avg = 10, min = 2, max = 30.
-  const values = [10, 5, 30, 2, 3]
-  for (const v of values) {
-    await client.queue(src).partition('p').push([{ data: { v } }])
-  }
+  // One batched push = one segment = one timestamp, so the five values cannot
+  // straddle a 3-second window boundary. Pushing them "within 1 second" of each
+  // other does NOT put them in one window: the bucket is absolute-aligned
+  // (floor(ts / 3000) * 3000), so two pushes milliseconds apart still split when
+  // a boundary falls between them, and the assertion below reads only the FIRST
+  // emit. Sum = 50, count = 5, avg = 10, min = 2, max = 30.
+  await client.queue(src).partition('p').push([
+    { data: { v: 10 } }, { data: { v: 5 } }, { data: { v: 30 } },
+    { data: { v: 2 } }, { data: { v: 3 } },
+  ])
 
   const handle = await Stream
     .from(client.queue(src))