queen-mq 1.3.0 → 2.0.0

package/client-v2/consumer/ConsumerManager.js

@@ -222,7 +222,7 @@ export class ConsumerManager {
               // 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 (autoAck && !ok) {
+              if (!ok) {
                 logger.warn('ConsumerManager.worker', { workerId, status: 'batch-abandoned-after-nack', remaining: messages.length - messages.indexOf(message) - 1 })
                 break
               }
@@ -316,62 +316,83 @@ export class ConsumerManager {
   async #processMessage(message, handler, autoAck, group) {
     try {
       await handler(message)
-
-      // Auto-ack on success if enabled
-      if (autoAck) {
-        const context = group ? { group } : {}
-        const res = await this.#queen.ack(message, true, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'ack-rejected', error: res.error })
-        } else {
-          logger.log('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'acked' })
-        }
-      }
-      return true
     } catch (error) {
-      // Auto-nack on error if enabled
-      if (autoAck) {
-        const context = group ? { group, error: error.message } : { error: error.message }
-        const res = await this.#queen.ack(message, false, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'nack-rejected', error: res.error })
-        }
-        logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, error: error.message, status: 'nacked' })
-        // Don't rethrow when autoAck is enabled - NACK was already sent
-        // This allows the consumer to continue and retry
-        return false
+      await this.#nackFailed(message, error, autoAck, group, 'ConsumerManager.processMessage')
+      return false
+    }
+
+    // Auto-ack on success if enabled
+    if (autoAck) {
+      const context = group ? { group } : {}
+      const res = await this.#queen.ack(message, true, context)
+      if (res && res.success === false) {
+        logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'ack-rejected', error: res.error })
+      } else {
+        logger.log('ConsumerManager.processMessage', { transactionId: message.transactionId, status: 'acked' })
       }
-      logger.error('ConsumerManager.processMessage', { transactionId: message.transactionId, error: error.message })
-      throw error
     }
+    return true
   }
 
   async #processBatch(messages, handler, autoAck, group) {
     try {
       await handler(messages)
+    } catch (error) {
+      await this.#nackFailed(messages, error, autoAck, group, 'ConsumerManager.processBatch')
+      return
+    }
 
-      // Auto-ack on success if enabled
-      if (autoAck) {
-        const context = group ? { group } : {}
-        const res = await this.#queen.ack(messages, true, context)
-        if (res && res.success === false) {
-          logger.error('ConsumerManager.processBatch', { count: messages.length, status: 'ack-rejected', error: res.error })
-        } else {
-          logger.log('ConsumerManager.processBatch', { count: messages.length, status: 'acked' })
-        }
+    // Auto-ack on success if enabled
+    if (autoAck) {
+      const context = group ? { group } : {}
+      const res = await this.#queen.ack(messages, true, context)
+      if (res && res.success === false) {
+        logger.error('ConsumerManager.processBatch', { count: messages.length, status: 'ack-rejected', error: res.error })
+      } else {
+        logger.log('ConsumerManager.processBatch', { count: messages.length, status: 'acked' })
       }
-    } catch (error) {
-      // Auto-nack on error if enabled
-      if (autoAck) {
-        const context = group ? { group, error: error.message } : { error: error.message }
-        await this.#queen.ack(messages, false, context)
-        logger.error('ConsumerManager.processBatch', { count: messages.length, error: error.message, status: 'nacked' })
-        // Don't rethrow when autoAck is enabled - NACK was already sent
-        // This allows the consumer to continue and retry
-        return
+    }
+  }
+
+  /**
+   * A handler threw: nack what it was given, and let the worker keep
+   * consuming. The same with `autoAck(false)`, which hands the SUCCESS path to
+   * the handler and not the failure path: a handler that threw did not get to
+   * settle its messages, and leaving them leased would hold the partition
+   * until the lease expires. Before this, a throw under autoAck(false) left
+   * the worker loop and stopped the consumer (the others kept running behind a
+   * consume() promise that had already rejected).
+   *
+   * The nack goes through the broker's retry budget like any other: the
+   * message is redelivered, and lands in the DLQ once the queue's retryLimit
+   * is spent. A message the handler already acked before throwing is already
+   * settled, so the broker refuses its nack and nothing changes for it. A
+   * handler that wants to decide for itself (ack, nack, DLQ, or stop)
+   * declares `.onError()`, which catches the error before it gets here.
+   */
+  async #nackFailed(messageOrMessages, error, autoAck, group, where) {
+    const batch = Array.isArray(messageOrMessages)
+    const subject = batch ? { count: messageOrMessages.length } : { transactionId: messageOrMessages.transactionId }
+    // A handler can throw anything, not only an Error.
+    const reason = error instanceof Error ? error.message : String(error)
+    logger.error(where, { ...subject, error: reason, status: 'handler-failed', autoAck })
+
+    const context = group ? { group, error: reason } : { error: reason }
+    try {
+      const res = await this.#queen.ack(messageOrMessages, false, context)
+      if (res && res.success === false) {
+        // Under autoAck(false) this is usually a handler that acked before it
+        // threw; with autoAck it means the lease ran out under the handler.
+        const log = autoAck ? logger.error : logger.warn
+        log(where, { ...subject, status: 'nack-rejected', error: res.error })
+      } else {
+        logger.log(where, { ...subject, status: 'nacked' })
       }
-      logger.error('ConsumerManager.processBatch', { count: messages.length, error: error.message })
-      throw error
+    } catch (nackError) {
+      // A message this client cannot even address (no partitionId) cannot be
+      // nacked; its lease expires and the broker redelivers it. Never a reason
+      // to stop the consumer.
+      logger.error(where, { ...subject, status: 'nack-failed', error: nackError.message })
     }
   }
 

package/client-v2/ephemeral/Ephemeral.js

@@ -11,8 +11,8 @@
  * WHAT THIS CLASS IS ABOUT, BEFORE ANY SIGNATURE: contents survive NOTHING
  * (§1.2). Not a restart, not a crash, not a deploy, not the ownership move that
  * a membership change causes. Treat a failover like a Redis restart. Declared
- * CONFIGURATION is durable -- it lives in PG and comes back after a restart, as
- * configured and EMPTY. There is no replay, no history, no subscriptionMode and
+ * CONFIGURATION is durable -- it lives in the broker's replicated log and comes
+ * back after a restart, as configured and EMPTY. There is no replay, no history, no subscriptionMode and
  * no DLQ, because none of those concepts has a referent when there is no
  * history to have.
  *
@@ -252,9 +252,9 @@ export class Ephemeral {
   // ------------------------------------------------------------ declaration
 
   /**
-   * Declare a queue and its bounds. Persists the OPTIONS in PG (§1.1): the
-   * configuration survives a restart, the contents never do, and the queue
-   * comes back declared and empty.
+   * Declare a queue and its bounds. Persists the OPTIONS in the broker's
+   * replicated log (§1.1): the configuration survives a restart, the contents
+   * never do, and the queue comes back declared and empty.
    *
    * Optional in every sense -- a push or a pop that names an unknown queue
    * creates it implicitly with the tenant defaults (§1.1). Declare when you
@@ -289,7 +289,7 @@ export class Ephemeral {
     return this.#call('POST', '/api/v1/ephemeral/reset', { queue }, { queue })
   }
 
-  /** Delete the queue: contents, cursors, and the declared configuration in PG. */
+  /** Delete the queue: contents, cursors, and the declared configuration. */
   async delete(queue) {
     requireQueue(queue)
     logger.log('Ephemeral.delete', { queue })
@@ -482,9 +482,7 @@ export class Ephemeral {
   /**
    * Every ephemeral queue this tenant currently has, declared and implicit.
    *
-   * Free to poll: the gauges are read out of the broker's own memory, with no
-   * database behind them -- unlike the durable meter, whose 1s poll is
-   * load-bearing on PG.
+   * Free to poll: the gauges are read out of the broker's own memory.
    */
   async queues() {
     logger.log('Ephemeral.queues', {})

package/client-v2/kv/Kv.js

@@ -2,8 +2,8 @@
  * The KV surface (PLAN_KV_TIMERS.md §5, §8.1).
  *
  * Seven operations, five code paths: get, getMany, getPrefix, put,
- * putIfAbsent (an alias that desugars to put with expect:0 inside the stored
- * procedure), delete, incr. Plus two conveniences this client owns: `once`,
+ * putIfAbsent (an alias that desugars to put with expect:0 inside the
+ * broker), delete, incr. Plus two conveniences this client owns: `once`,
  * which is the idempotency marker written the way people actually reach for
  * it, and `listAll`, which walks the keyset cursor of getPrefix.
  *
@@ -249,7 +249,7 @@ export class Kv {
     if (!results) {
       throw new Error('kv: unexpected response envelope — expected {"results":[...]}')
     }
-    // The stored procedure guarantees one result per op and raises rather than
+    // The broker answers one result per op and fails the call rather than
     // returning a short array (§6.4). A short one here means something between
     // the two rewrote the answer, and attributing result i to op j is how a
     // caller ends up trusting the wrong verdict.
@@ -293,7 +293,7 @@ export class Kv {
    * One key. Returns the ROW, not the value:
    * `{found, key, value?, version?, expiresAt?, updatedAt?}`.
    *
-   * `found` is separate from `value` because `null` is a legal JSONB value
+   * `found` is separate from `value` because `null` is a legal JSON value
    * (§5.5): `{found:true, value:null}` and `{found:false}` are different
    * things, and an SDK that returned "the value or null" would collapse them.
    */

package/client-v2/kv/expiry.js

@@ -95,7 +95,7 @@ function instantMs(value) {
  *
  * The empty answer is deliberate and is the reason this function validates so
  * little: §5.1's rule -- exactly one of `ttlSeconds` and `forever:true`, zero
- * or two being the same error -- lives in `kv_apply_v1`, so that all seven
+ * or two being the same error -- lives in the broker, so that all seven
  * clients AND the embedded broker (which never passes through an HTTP handler)
  * inherit it without a line of their own. Re-implementing it here would give
  * the product two places that can disagree about when a key dies. What IS

package/client-v2/streams/Stream.js

@@ -176,7 +176,7 @@ export class Stream {
    *
    * The user fn receives `(value, ctx)` where:
    *   - value: the message payload (post any pre-stage map/filter)
-   *   - ctx.state: mutable per-key state (loaded from queen_streams.state,
+   *   - ctx.state: mutable per-key state (loaded from the broker,
    *                persisted only if you return ALLOW for this message)
    *   - ctx.streamTimeMs: system clock for the cycle (use for refill math)
    *   - ctx.partitionId: source partition_id (= state shard)
@@ -186,7 +186,9 @@ export class Stream {
    * commits an ack for the prefix that was allowed and DOES NOT release the
    * source lease, so the denied message and its successors get redelivered
    * in their original order when the lease expires. FIFO per partition is
-   * preserved without any deferred queue.
+   * preserved without any deferred queue. The prefix is counted in source
+   * messages: after a `.flatMap()`, a message is allowed only if every value
+   * it produced is allowed.
    *
    * Example (token bucket rate limiter):
    *
@@ -258,7 +260,10 @@ export class Stream {
    * @param {number} [runOptions.batchSize=200] - messages per cycle
    * @param {number} [runOptions.maxPartitions=4] - lease up to N partitions/cycle
    * @param {number} [runOptions.maxWaitMillis=1000] - long-poll wait for source pop
-   * @param {string} [runOptions.subscriptionMode] - 'all' (default) | 'new'
+   * @param {string} [runOptions.subscriptionMode] - 'new' | 'all'. Unset, the
+   *   broker's default applies, which is 'new' (DEFAULT_SUBSCRIPTION_MODE): a
+   *   query registered after its source already holds messages starts at the
+   *   tail and skips them. Pass 'all' to process the backlog.
    * @param {string} [runOptions.subscriptionFrom] - ISO timestamp or 'now'
    * @param {boolean} [runOptions.conflation=false] - last-value delivery on the
    *   source pop: each cycle sees only the newest visible message per partition

package/client-v2/streams/helpers/rateLimiter.js

@@ -3,8 +3,8 @@
  * factories that return a function suitable for `.gate(fn)` on a Stream.
  *
  * The point of these helpers is purely ergonomic: the user shouldn't have to
- * re-write the refill math every time. The semantics (per-key state in
- * queen_streams.state, partial-ack on deny, FIFO order on lease expiry) all
+ * re-write the refill math every time. The semantics (per-key state in the
+ * broker, partial-ack on deny, FIFO order on lease expiry) all
  * come from the underlying Stream `.gate()` runtime — these factories only
  * decide HOW each request consumes from the bucket.
  *
@@ -31,7 +31,7 @@
  *
  * Returns a `(msg, ctx) => boolean` function suitable for `.gate(fn)`.
  * The bucket state lives in `ctx.state` (which the runtime persists per-key
- * in queen_streams.state on every ALLOWED message).
+ * in the broker on every ALLOWED message).
  *
  * @param {object} opts
  * @param {number}                 opts.capacity        Max tokens in the bucket (= max burst).
@@ -75,7 +75,7 @@ export function tokenBucketGate({
       ctx.state.tokens -= cost
       // Lightweight observability: the SDK persists ctx.state on ALLOW only,
       // so these counters automatically reflect "what the bucket actually let
-      // through" and can be inspected via SQL on queen_streams.state.
+      // through".
       ctx.state.allowedTotal = (ctx.state.allowedTotal || 0) + 1
       ctx.state.consumedTotal = (ctx.state.consumedTotal || 0) + cost
       return true

package/client-v2/streams/operators/GateOperator.js

@@ -7,8 +7,8 @@
  * Semantics
  * ---------
  * The runtime processes a popped batch sequentially in source order. For each
- * message, it builds a `ctx` object with mutable `state` (loaded from
- * `queen_streams.state` for the message's key) and invokes the user fn.
+ * message, it builds a `ctx` object with mutable `state` (loaded from the
+ * broker for the message's key) and invokes the user fn.
  *
  *   .gate((msg, ctx) => boolean)
  *
@@ -30,6 +30,13 @@
  * cycle entirely — no state, no push, no ack — and the lease times out
  * naturally.
  *
+ * K counts SOURCE MESSAGES, because the ack is an offset commit. A pre-stage
+ * can turn one message into several values (`.flatMap()`) or into none
+ * (`.filter()`): a message is allowed only when every value it produced is
+ * allowed, a denied value rolls back what its whole message did to the
+ * state, and a message the pre-stages dropped is settled with the prefix.
+ * A redelivery therefore replays whole messages, never half of one.
+ *
  * Ordering
  * --------
  * FIFO per-partition is preserved by construction: the same partition lease

package/client-v2/streams/operators/ReduceOperator.js

@@ -161,8 +161,8 @@ export class ReduceOperator {
  *
  * The `operatorTag` (e.g. "tumb:60", "slide:60:10", "sess:30", "cron:minute")
  * lets multiple window operators within one query coexist in the same
- * `queen_streams.state` table without colliding, and lets the idle-flush
- * scan filter to a single operator's keys via prefix LIKE matching.
+ * state store without colliding, and lets the idle-flush scan filter to a
+ * single operator's keys by key prefix.
  *
  * Reserved key prefix: state keys starting with "__" are internal (e.g.
  * "__wm__" for per-partition watermarks). User code should never write

package/client-v2/streams/operators/WindowSessionOperator.js

@@ -109,7 +109,7 @@ export class WindowSessionOperator {
     // events in this batch.
     const sessions = new Map()  // userKey -> { acc, sessionStart, lastEventTime, dirty, seeded }
 
-    // Seed from PG state.
+    // Seed from the loaded state.
     for (const [stateKey, value] of loadedState.entries()) {
       // Expected shape: `${operatorTag}\u001fopen\u001f${userKey}`
       const parts = stateKey.split('\u001f')
@@ -193,8 +193,8 @@ export class WindowSessionOperator {
       const stateKey = this.openSessionStateKey(userKey)
       if (s.closed) {
         if (s.seeded) stateOps.push({ type: 'delete', key: stateKey })
-        // Newly-opened sessions that closed in the same batch never made
-        // it to PG, so no delete needed.
+        // Newly-opened sessions that closed in the same batch were never
+        // persisted, so no delete needed.
       } else if (s.dirty) {
         stateOps.push({
           type: 'upsert',

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

@@ -99,7 +99,7 @@ export class Runner {
     // two in-process paths removes the race at its source.
     this._partitionMutexes     = new Map()   // partitionId -> tail promise
     this._recentPartitions     = new Map()   // partitionId -> { partitionName, touchedAt }
-    this._partitionWatermarks  = new Map()   // partitionId -> wmMs (cache; PG is source of truth)
+    this._partitionWatermarks  = new Map()   // partitionId -> wmMs (cache; the broker is source of truth)
     this._stats = {
       cyclesTotal:      0,
       flushCyclesTotal: 0,
@@ -323,8 +323,14 @@ export class Runner {
     const partitionId = group.partitionId
     const partitionName = group.partitionName
 
-    // Sort messages by (createdAt, id) to preserve partition FIFO order.
+    // Partition FIFO order. A 2.x broker answers each message with its offset,
+    // which IS that order, and the one the gate's partial ack counts in.
+    // (createdAt, id) is only the fallback for brokers that send no offset:
+    // createdAt is rendered to the millisecond, and pushes from concurrent
+    // producers share one with their ids out of offset order (measured
+    // 2026-10-02 on 2.0.0-beta.6: 69 of 400 positions disagreed).
     const orderedMessages = [...group.messages].sort((a, b) => {
+      if (Number.isFinite(a.offset) && Number.isFinite(b.offset)) return a.offset - b.offset
       const ta = Date.parse(a.createdAt || '') || 0
       const tb = Date.parse(b.createdAt || '') || 0
       if (ta !== tb) return ta - tb
@@ -396,9 +402,9 @@ export class Runner {
     }
 
     // 6. Build the source ack — advance the cursor to the LAST message
-    //    and tell the SP how many messages were in this cycle's batch
-    //    so partition_consumers.acked_count / lease release logic uses
-    //    the correct count (the cycle is atomic across the full batch).
+    //    and tell the broker how many messages were in this cycle's batch
+    //    so its acked count / lease release logic uses the correct count
+    //    (the cycle is atomic across the full batch).
     const lastMsg = orderedMessages[orderedMessages.length - 1]
     const ack = lastMsg
       ? {
@@ -431,13 +437,43 @@ export class Runner {
    * release_lease=false so the un-acked tail returns when the lease expires
    * (preserving FIFO per partition without a deferred queue).
    *
+   * The gate settles SOURCE MESSAGES, not envelopes. A pre-stage runs before
+   * it and breaks the one-to-one correspondence: `.filter()` leaves a message
+   * with no envelope, `.flatMap()` leaves it with several. The partial ack is
+   * an offset commit -- the broker advances `count` messages from the head of
+   * the leased batch -- so counting envelopes acks the wrong prefix: past a
+   * denied message (which is then never redelivered) after a flatMap, short of
+   * the allowed ones (which are then gated and pushed again) after a filter. A
+   * message is settled only when every envelope it produced was allowed, so a
+   * redelivery replays the whole message and never half of it.
+   *
    * State model: load ALL state rows for the partition once, evaluate the
    * gate in order, mutate in-memory state, then upsert only the keys whose
-   * ALLOWED messages mutated them.
+   * ALLOWED messages mutated them. What a denied message did to the state on
+   * its way to being denied is rolled back: a denied message did not happen.
    */
   async _processGateCycle({ stages, envelopes, orderedMessages, group, partitionId, partitionName }) {
     const gate = stages.gate
 
+    // One bucket of envelopes per claimed message, in partition order (the
+    // sort in _processPartitionCycleInner). Every pre-stage operator carries
+    // the source message through as `env.msg`.
+    const indexOf = new Map(orderedMessages.map((m, i) => [m, i]))
+    const buckets = orderedMessages.map(() => [])
+    for (const env of envelopes) {
+      const i = indexOf.get(env.msg)
+      if (i === undefined) {
+        // Not traceable to a claimed message, so not settleable by an offset
+        // commit. Hold the batch rather than ack past it: the lease lapses and
+        // the whole batch comes back.
+        this._reportError(new Error('.gate(): an envelope does not come from a message of this batch; holding the batch'), {
+          phase: 'gate-eval', partition: partitionId
+        })
+        return
+      }
+      buckets[i].push(env)
+    }
+
     // Load all state rows for this partition. Cheap: usually one row per
     // (rate-limit key) — for the canonical rate-limiter pattern that's a
     // single row, since partition == limit key.
@@ -465,46 +501,65 @@ export class Runner {
     }
 
     const streamTimeMs = Date.now()
-    let allowedCount = 0
-    let firstDenyIdx = -1
+    let settled = 0          // messages whose every envelope was allowed
+    let denied = false
     const allowedEnvelopes = []
 
-    for (let i = 0; i < envelopes.length; i++) {
-      const env = envelopes[i]
-      const key = env.key
-      const stateForKey = ensureState(key)
-      const ctx = {
-        state:        stateForKey,
-        streamTimeMs,
-        partitionId,
-        partition:    partitionName,
-        key
-      }
-      let decision
-      try {
-        decision = await gate.evaluate(env, ctx)
-      } catch (err) {
-        // Gate threw: treat as a transient cycle error. Don't commit
-        // anything. The lease will time out and the broker redelivers.
-        this._reportError(err, { phase: 'gate-eval', partition: partitionId, message: env.msg })
-        return
-      }
-      if (decision.allow) {
+    messages: for (const bucket of buckets) {
+      // What this message does to the state, to undo it if one of its
+      // envelopes is denied: key -> its value before this message
+      // (undefined: no entry yet), and the keys it touched first.
+      const before = new Map()
+      const newlyTouched = []
+      for (const env of bucket) {
+        const key = env.key
+        if (!before.has(key)) {
+          before.set(key, liveState.has(key) ? this._cloneState(liveState.get(key)) : undefined)
+        }
+        const stateForKey = ensureState(key)
+        const ctx = {
+          state:        stateForKey,
+          streamTimeMs,
+          partitionId,
+          partition:    partitionName,
+          key
+        }
+        let decision
+        try {
+          decision = await gate.evaluate(env, ctx)
+        } catch (err) {
+          // Gate threw: treat as a transient cycle error. Don't commit
+          // anything. The lease will time out and the broker redelivers.
+          this._reportError(err, { phase: 'gate-eval', partition: partitionId, message: env.msg })
+          return
+        }
+        if (!decision.allow) {
+          for (const [k, value] of before) {
+            if (value === undefined) liveState.delete(k)
+            else liveState.set(k, value)
+          }
+          for (const k of newlyTouched) touchedKeys.delete(k)
+          denied = true
+          break messages
+        }
         // Mutated state on this key is committable.
-        touchedKeys.add(key)
-        allowedCount++
-        allowedEnvelopes.push(env)
-      } else {
-        firstDenyIdx = i
-        break
+        if (!touchedKeys.has(key)) {
+          touchedKeys.add(key)
+          newlyTouched.push(key)
+        }
       }
+      // Settled, including a message the pre-stages dropped entirely: it
+      // has nothing to gate, and holding it would hold the whole batch.
+      allowedEnvelopes.push(...bucket)
+      settled++
     }
 
-    if (allowedCount === 0) {
-      // Nothing to commit: skip the cycle entirely. The lease stays held
-      // by us until it naturally expires; the messages are then
-      // redelivered (to us or another worker) in their original order.
-      this._stats.gateDenialsTotal = (this._stats.gateDenialsTotal || 0) + envelopes.length
+    if (settled === 0) {
+      // The first message was denied. Nothing to commit: skip the cycle
+      // entirely. The lease stays held by us until it naturally expires;
+      // the messages are then redelivered (to us or another worker) in
+      // their original order.
+      this._stats.gateDenialsTotal = (this._stats.gateDenialsTotal || 0) + orderedMessages.length
       return
     }
 
@@ -540,24 +595,26 @@ export class Runner {
       })))
     }
 
-    // Ack the LAST allowed message (cursor advances to it). The count
-    // tells the SP how many messages this commit covers.
-    const lastAllowedSrc = allowedEnvelopes[allowedEnvelopes.length - 1].msg
+    // Ack the LAST settled message (cursor advances to it). The count tells
+    // the broker how many messages this commit covers, counted from the head
+    // of the leased batch: on a partial ack it is the offset the cursor
+    // moves to, so it has to be the number of settled MESSAGES.
+    const lastSettled = orderedMessages[settled - 1]
     const ack = {
-      transactionId: lastAllowedSrc.transactionId,
-      leaseId:       lastAllowedSrc.leaseId || group.leaseId,
+      transactionId: lastSettled.transactionId,
+      leaseId:       lastSettled.leaseId || group.leaseId,
       status:        'completed',
-      count:         allowedCount
+      count:         settled
     }
 
-    const partial = firstDenyIdx >= 0   // some message was denied
-    const releaseLease = !partial
+    // Holding the lease on a partial ack is what preserves FIFO: the denied
+    // tail is not claimable by another worker, so it cannot be overtaken.
+    const releaseLease = !denied
 
-    if (firstDenyIdx >= 0) {
-      const tailUnacked = envelopes.length - allowedCount
-      this._stats.gateDenialsTotal = (this._stats.gateDenialsTotal || 0) + tailUnacked
+    if (denied) {
+      this._stats.gateDenialsTotal = (this._stats.gateDenialsTotal || 0) + (orderedMessages.length - settled)
     }
-    this._stats.gateAllowsTotal = (this._stats.gateAllowsTotal || 0) + allowedCount
+    this._stats.gateAllowsTotal = (this._stats.gateAllowsTotal || 0) + settled
 
     this._stats.stateOpsTotal  += stateOps.length
     this._stats.pushItemsTotal += pushItems.length
@@ -990,8 +1047,8 @@ export class Runner {
   }
 
   /**
-   * Use the streams_state_get_v1 SP's key_prefix + ripe_at_or_before
-   * filters to scope the fetch.
+   * Use the state route's key_prefix + ripe_at_or_before filters to scope
+   * the fetch.
    */
   async _fetchRipeStateRows(partitionId, keyPrefix, ripeAtMs) {
     const body = {

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

@@ -6,10 +6,10 @@
  *   - push_items: sink emissions (queue/partition/payload triples)
  *   - ack: source ack (transactionId, leaseId, status, optional error)
  *
- * The server runs streams_cycle_v1 in one transaction; on success the
- * SDK considers the source messages safely processed. On failure (including
- * EXCEPTION inside the SP), the entire cycle is rolled back and the source
- * messages remain visible for redelivery via Queen's existing lease/retry.
+ * The broker commits the cycle as one command, all or nothing; on success the
+ * SDK considers the source messages safely processed. On failure, nothing of
+ * the cycle is applied and the source messages remain visible for redelivery
+ * via Queen's existing lease/retry.
  */
 
 export async function commitCycle({ http, queryId, partitionId, consumerGroup, stateOps, pushItems, ack, releaseLease }) {

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

@@ -26,7 +26,7 @@ export async function registerQuery({ http, name, sourceQueue, sinkQueue, config
       const msg = err.body.error || 'config_hash mismatch'
       const hint =
         '\n\nHint: pass `reset: true` to Stream.run({...}) to wipe the existing ' +
-        'queen_streams.state for this queryId, or pick a new queryId.'
+        'stream state for this queryId, or pick a new queryId.'
       const e = new Error(msg + hint)
       e.code = 'STREAMS_CONFIG_HASH_MISMATCH'
       throw e

package/client-v2/utils/conflation.js

@@ -93,12 +93,6 @@ export function checkConflationResponse(result, ctx) {
 
   if (result && result.conflation === true) return
 
-  // Pop maintenance: the broker refused the pop before it reached the claim
-  // path, so there is no policy to echo and nothing to conclude from the
-  // absence of one. Reading it as "old broker" would stop every conflating
-  // consumer in the fleet the moment an operator pauses pops.
-  if (result && result.paused === true) return
-
   // The group is known to disagree with us; this response is that same
   // conflict, seen through a body that could not carry the flag.
   if (knownConflicts.has(key)) return