queen-mq 1.3.0 → 2.0.0

package/test-v2/runner-unit/fatalExit.test.js

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import net from 'node:net'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { describe, it } from 'node:test'
+
+const suiteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+// A loopback port with nothing listening on it: bind an ephemeral port, then
+// release it. Not port 1: fetch() rejects the Fetch-spec "bad ports" (1 is one
+// of them) before it ever connects, so the preflight would fail with "bad port"
+// and never exercise a refused connection.
+function closedLoopbackPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address()
+      server.close(error => (error ? reject(error) : resolve(port)))
+    })
+  })
+}
+
+function runWithUnreachableBroker(brokerUrl) {
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env, QUEEN_SERVER_URL: brokerUrl }
+    // TEST_CONFIG=multiple would point run.js at its fixed localhost URLs
+    // instead of QUEEN_SERVER_URL.
+    delete env.TEST_CONFIG
+    const child = spawn(process.execPath, ['test-v2/run.js', 'human'], {
+      cwd: suiteRoot,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+
+    let output = ''
+    const deadline = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`integration runner did not exit within 5s:\n${output}`))
+    }, 5000)
+    child.stdout.on('data', chunk => { output += chunk })
+    child.stderr.on('data', chunk => { output += chunk })
+    child.once('error', error => {
+      clearTimeout(deadline)
+      reject(error)
+    })
+    child.once('close', (code, signal) => {
+      clearTimeout(deadline)
+      resolve({ code, signal, output })
+    })
+  })
+}
+
+describe('integration runner lifecycle', () => {
+  it('returns a failure status when the broker preflight fails', async () => {
+    const port = await closedLoopbackPort()
+    const result = await runWithUnreachableBroker(`http://127.0.0.1:${port}`)
+
+    assert.equal(result.signal, null)
+    assert.equal(result.code, 1, result.output)
+    assert.match(result.output, /Main error: broker preflight .*ECONNREFUSED/)
+  })
+})

package/test-v2/semantics.js

@@ -16,9 +16,9 @@
  *     AFTER the group registered (durable subscription record).
  *  8. Queue-mode pops never skip backlog, even when carrying subscriptionMode.
  *  9. Empty polls while another worker holds the lease never strand backlog
- *     (wildcard watermark guard).
- * 10. Push-only (never-configured) queues get a queen.queues row: visible in
- *     resources, discoverable by namespace pop.
+ *     (an empty answer must not hide the partition once the lease lapses).
+ * 10. Push-only (never-configured) queues are registered by the push: visible
+ *     in resources, discoverable by namespace pop.
  * 11. GET /api/v1/messages/:pid/:txn keeps the full v0.16.0 shape (including
  *     consumerGroups[].name — not .group).
  * 12. Transactions honor `retry` and `dlq` ack statuses (not collapsed to a
@@ -39,7 +39,7 @@
  * Run: node run.js <testName>   e.g. node run.js implicitAckCompletesBatch
  */
 
-import { dbPool, TEST_CONFIG } from './run.js'
+import { TEST_CONFIG } from './run.js'
 
 // Lazy: run.js imports this module before TEST_CONFIG is initialized (TDZ),
 // so the base URL must be resolved at call time, not module-eval time.
@@ -369,7 +369,7 @@ export async function queueModePopNeverSkipsBacklog(client) {
 }
 
 // ============================================================================
-// 9. Watermark: empty polls during a held lease must not strand backlog
+// 9. Empty polls during a held lease must not strand backlog
 // ============================================================================
 export async function leasedBacklogNotStrandedByEmptyPolls(client) {
     const queue = uniq('watermark-lease')
@@ -385,34 +385,26 @@ export async function leasedBacklogNotStrandedByEmptyPolls(client) {
     if (a.length !== 1) return { success: false, message: 'Worker A did not get the message' }
 
     // Worker B (same group) polls empty repeatedly while A holds the lease.
-    // A buggy engine advances the empty-scan watermark here even though the
-    // backlog is only invisible because of A's lease.
+    // The backlog is invisible here ONLY because of A's lease: a broker that
+    // remembers these empty answers as "nothing to deliver" keeps hiding the
+    // partition after the lease lapses.
     for (let i = 0; i < 3; i++) {
         await client.queue(queue).group(group).batch(1).wait(false).pop()
         await sleep(100)
     }
 
-    // Defeat the 2-minute candidate-filter grace so a wrongly-advanced
-    // watermark actually hides the partition (same trick as watermark.js).
-    // Queue identity is now the queen.queues id (log_queues merged away).
-    await dbPool.query(`
-        UPDATE queen.log_partitions p
-        SET last_write_at = last_write_at - interval '10 minutes'
-        FROM queen.queues q
-        WHERE p.queue_id = q.id AND q.name = $1
-    `, [queue])
-
-    // Wait for A's lease to lapse. NO new push arrives.
+    // Wait for A's lease to lapse. NO new push arrives, so nothing but the
+    // lease expiry can make the message deliverable again.
     await sleep(3500)
 
     const b = await popRetry(client, queue, { group, tries: 10 })
     if (b.length !== 1) {
         return {
             success: false,
-            message: 'Backlog stranded: empty polls during a held lease advanced the watermark past unconsumed data'
+            message: 'Backlog stranded: after empty polls during a held lease, the message never came back once the lease lapsed'
         }
     }
-    return { success: true, message: 'Backlog survived lease churn + empty polls (watermark guard holds)' }
+    return { success: true, message: 'Backlog survived lease churn + empty polls' }
 }
 
 // ============================================================================
@@ -433,7 +425,7 @@ export async function pushOnlyQueueIsDiscoverable(client) {
     const list = Array.isArray(body) ? body : (body.queues || [])
     const entry = list.find(q => (q.name || q.queue) === queue)
     if (!entry) {
-        return { success: false, message: 'Push-only queue missing from /api/v1/resources/queues (no queen.queues row?)' }
+        return { success: false, message: 'Push-only queue missing from /api/v1/resources/queues (never registered by the push?)' }
     }
     const entryNs = entry.namespace ?? entry.ns
     if (entryNs !== ns) {
@@ -455,19 +447,13 @@ export async function pushOnlyQueueIsDiscoverable(client) {
         if (!found) await sleep(200)
     }
 
-    // Cleanup: queue identity is now the queen.queues id, and deleting the
-    // queues row cascades partitions/watermarks/metadata/lag-metrics. Only
-    // log_txns/log_dlq are FK-less by design → explicit purge via partitions.
-    await dbPool.query(`
-        WITH parts AS (
-          SELECT lp.id FROM queen.log_partitions lp
-          JOIN queen.queues q ON q.id = lp.queue_id
-          WHERE q.name = $1
-        ),
-        d1 AS (DELETE FROM queen.log_txns WHERE partition_id IN (SELECT id FROM parts)),
-        d2 AS (DELETE FROM queen.log_dlq  WHERE partition_id IN (SELECT id FROM parts))
-        SELECT 1`, [queue])
-    await dbPool.query(`DELETE FROM queen.queues WHERE name = $1`, [queue])
+    // Best-effort cleanup through the public API. The lane's broker is thrown
+    // away after the run anyway, so a failed delete is not this test's verdict.
+    try {
+        await client.queue(queue).delete()
+    } catch (e) {
+        // Ignore
+    }
 
     if (!found) {
         return { success: false, message: 'Namespace discovery pop never found the push-only queue' }

package/test-v2/stream/_helpers.js

@@ -1,13 +1,12 @@
 /**
  * Shared utilities for streaming tests.
  *
- * Tests in test-v2/stream/* are run live against a Queen instance and a
- * Postgres database. Each test:
+ * Tests in test-v2/stream/* are run live against a Queen broker. Each test:
  *   - generates a unique queue/query name to avoid collisions across runs
  *   - sets up source + sink queues
  *   - runs a Stream pipeline for a bounded time
  *   - asserts on the resulting sink-queue contents and/or runner metrics
- *   - stops the stream and lets the global cleanup hook drop the rows
+ *   - stops the stream (the lane's broker is thrown away after the run)
  *
  * Test-name uniqueness is achieved with the test function's name + a
  * monotonic counter so the same suite can be re-run without state bleed.
@@ -20,7 +19,7 @@ let _nameCounter = 0
 
 /**
  * Build a unique queue/query name scoped to a test. The prefix is always
- * "test-stream-" so the global cleanup query in run.js deletes it.
+ * "test-stream-", the suite's test-name convention.
  *
  * @param {string} testName - e.g. fn.name
  * @param {string} suffix   - 'src' | 'sink' | 'query' | etc.
@@ -89,12 +88,12 @@ export async function pushSpread(client, queueName, items) {
  * the broker default of 'new' its cursor would be seeded at the sink's tail
  * and the emits under test would be invisible.
  *
- * NOTE on batch size: we use batch=1 so that each ack triggers
- * `acked_count >= batch_size` in queen.partition_consumers and the lease
- * is released between pops. With a larger batch the lease would stay
- * held until acked_count reached the full batch_size (often never on
- * intermittent emits), and subsequent pops would skip the partition as
- * "leased by another worker." Worth the round-trip overhead in tests.
+ * NOTE on batch size: we use batch=1 so that each ack reaches the end of
+ * the leased batch and the lease is released between pops. With a larger
+ * batch the lease would stay held until the acks reached the end of the
+ * full batch (often never on intermittent emits), and subsequent pops would
+ * skip the partition as "leased by another worker." Worth the round-trip
+ * overhead in tests.
  */
 export async function drainSink(client, queueName, { timeoutMs = 5000, group } = {}) {
   const cg = group || `drain-${Date.now()}-${Math.floor(Math.random() * 1e6)}`
@@ -110,7 +109,7 @@ export async function drainSink(client, queueName, { timeoutMs = 5000, group } =
       .pop()
     if (!popped || popped.length === 0) break
     for (const m of popped) out.push(m)
-    // Pass the consumer group so the SP validates the lease against OUR
+    // Pass the consumer group so the broker validates the lease against OUR
     // group, not the default __QUEUE_MODE__. queen-mq uses `context.group`
     // (NOT `consumerGroup`) for the ack-context shape.
     await client.ack(popped, true, { group: cg })
@@ -187,11 +186,3 @@ export async function runStreamFor(streamFactory, runMs) {
   await handle.stop()
   return handle
 }
-
-/**
- * Helpful guard for tests that need a clean queen_streams.queries row for
- * a given query name. Drops it (state cascades) before the test runs.
- */
-export async function dropStreamQuery(dbPool, queryName) {
-  await dbPool.query(`DELETE FROM queen_streams.queries WHERE name = $1`, [queryName])
-}

package/test-v2/stream/cron.js

@@ -3,7 +3,7 @@
  *   'second' | 'minute' | 'hour' | 'day' | 'week'
  *
  * Boundaries are anchored to UTC. Day = midnight UTC; week = Monday 00:00
- * UTC. Tests here exercise live behaviour (in-PG state) for the second
+ * UTC. Tests here exercise live behaviour (broker-side state) for the second
  * granularity (fast enough to test in seconds rather than hours).
  */
 

package/test-v2/stream/gate.js

@@ -0,0 +1,54 @@
+/**
+ * .gate() against a live broker: the partial ack counts SOURCE MESSAGES.
+ *
+ * The gate's partial ack is an offset commit -- the broker advances
+ * `ack.count` messages from the head of the leased batch and keeps the lease
+ * -- and the runner used to count the envelopes the gate saw instead. With a
+ * .flatMap() in front, a denied message was acked together with its
+ * predecessor and never came back (2026-10-02, 2.0.0-beta.6: 4 of 6 sink
+ * items, message 2 lost). The unit tests pin the cycle body
+ * (streams-unit/gate.test.js); this one pins the broker's side of it.
+ */
+
+import { Stream } from '../../client-v2/index.js'
+import { STREAMS_URL, mkName, drainUntil, expect, summarise } from './_helpers.js'
+
+export async function streamGateFlatMapPartialAck(client) {
+  const src = mkName('streamGateFlatMapPartialAck', 'src')
+  const sink = mkName('streamGateFlatMapPartialAck', 'sink')
+  const queryId = mkName('streamGateFlatMapPartialAck', 'q')
+
+  // A short lease: the denied tail comes back when it expires.
+  await client.queue(src).config({ leaseTime: 2 }).create()
+  await client.queue(sink).create()
+  await client.queue(src).partition('tenant-1').push([{ data: { n: 1 } }, { data: { n: 2 } }, { data: { n: 3 } }])
+
+  // Every message becomes two values; message 2 is denied the first time it
+  // is seen and allowed after its redelivery.
+  let deniedOnce = false
+  const handle = await Stream
+    .from(client.queue(src))
+    .flatMap(m => [m.data, m.data])
+    .gate((v) => {
+      if (v.n === 2 && !deniedOnce) {
+        deniedOnce = true
+        return false
+      }
+      return true
+    })
+    .to(client.queue(sink))
+    .run({ queryId, url: STREAMS_URL, batchSize: 10, maxPartitions: 1, reset: true, subscriptionMode: 'all' })
+
+  const drained = await drainUntil(client, sink, { until: out => out.length >= 6, timeoutMs: 15000 })
+  await handle.stop()
+
+  const count = (n) => drained.filter(m => m.data.n === n).length
+  const checks = [
+    expect(deniedOnce, '===', true, 'the gate denied message 2 once'),
+    expect(count(1), '===', 2, 'message 1 on the sink'),
+    expect(count(2), '===', 2, 'message 2 on the sink after its redelivery'),
+    expect(count(3), '===', 2, 'message 3 on the sink'),
+    expect(handle.metrics().errorsTotal, '===', 0, 'no errors')
+  ]
+  return summarise('streamGateFlatMapPartialAck', checks)
+}

package/test-v2/stream/index.js

@@ -12,6 +12,7 @@
  *   recovery.js   — config_hash mismatch + reset + mid-stream resume
  *   throughput.js — multi-partition / many-window throughput
  *   combined.js   — full pipelines + concurrent streams
+ *   gate.js       — .gate() partial acks against the broker
  */
 
 export * from './operators.js'
@@ -23,3 +24,4 @@ export * from './eventTime.js'
 export * from './recovery.js'
 export * from './throughput.js'
 export * from './combined.js'
+export * from './gate.js'

package/test-v2/stream/tumbling.js

@@ -294,9 +294,9 @@ export async function tumblingForeachCtxHasWindowAndPartition(client) {
   const queryId = mkName('tumblingForeachCtxHasWindowAndPartition', 'q')
 
   await client.queue(src).create()
-  for (let i = 0; i < 3; i++) {
-    await client.queue(src).partition('myKey').push([{ data: { v: i } }])
-  }
+  // One push, so all three get the same broker createdAt: three pushes can
+  // straddle a second and split across two 1 s windows (count 1, then 2).
+  await client.queue(src).partition('myKey').push([0, 1, 2].map(v => ({ data: { v } })))
 
   const captured = []
   const handle = await Stream

package/test-v2/streams-unit/ack.test.js

@@ -201,3 +201,64 @@ describe('Queen.ack batch (/api/v1/ack/batch)', () => {
     )
   })
 })
+
+// The consumer group of an ack. /ack and /ack/batch judge an ack that names no
+// group in queue mode, so a message popped by a group and acked without one
+// came back `invalid or expired lease` (found 2026-10-02 against
+// 2.0.0-beta.6). Every pop answers each message with its `consumerGroup`.
+describe('Queen.ack — the group the message was popped under', () => {
+  const okFor = (body) => (body.acknowledgments || [body]).map((a, i) => ackResultItem(i, a.transactionId, true))
+  const popped = (n, group) => ({ transactionId: `tx-${n}`, partitionId: 'p-1', leaseId: 'lease-1', consumerGroup: group })
+
+  it('single: takes consumerGroup from the message when the caller names none', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      await client.ack(popped(1, 'workers'), true)
+      assert.equal(requests[0].body.consumerGroup, 'workers')
+    })
+  })
+
+  it('single: a queue-mode or hand-built message still sends consumerGroup null', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      await client.ack(popped(1, '__QUEUE_MODE__'), true)
+      await client.ack(MSG, true)
+      assert.equal(requests[0].body.consumerGroup, null)
+      assert.equal(requests[1].body.consumerGroup, null)
+    })
+  })
+
+  it('single: an explicit { group } wins', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      await client.ack(popped(1, 'workers'), false, { group: 'auditors' })
+      assert.equal(requests[0].body.consumerGroup, 'auditors')
+    })
+  })
+
+  it('batch: the group the messages share', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      const result = await client.ack([popped(1, 'workers'), popped(2, 'workers')], true)
+      assert.equal(result.success, true)
+      assert.equal(requests[0].path, '/api/v1/ack/batch')
+      assert.equal(requests[0].body.consumerGroup, 'workers')
+    })
+  })
+
+  it('batch: queue-mode messages still send consumerGroup null', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      await client.ack([popped(1, '__QUEUE_MODE__'), popped(2, '__QUEUE_MODE__')], true)
+      assert.equal(requests[0].body.consumerGroup, null)
+    })
+  })
+
+  it('batch: messages from two groups are refused before anything is sent', async () => {
+    await withAckServer(okFor, async (client, requests) => {
+      await assert.rejects(
+        () => client.ack([popped(1, 'a'), popped(2, 'b')], true),
+        /different consumer groups in one call \(a, b\)/
+      )
+      assert.equal(requests.length, 0)
+      // ... unless the caller names the group, which is then theirs to get right.
+      await client.ack([popped(1, 'a'), popped(2, 'b')], true, { group: 'a' })
+      assert.equal(requests[0].body.consumerGroup, 'a')
+    })
+  })
+})

package/test-v2/streams-unit/cycle.test.js

@@ -100,7 +100,7 @@ describe('Runner — windowed aggregation', () => {
     // The 10:00 window is closed (created and closed in the same batch
     // since the third message crosses the minute boundary). The 10:01
     // window stays open. Because the 10:00 window was never persisted to
-    // PG (created+closed in one cycle), no delete state op is emitted —
+    // the broker (created+closed in one cycle), no delete state op is emitted —
     // only the closed-window push and the open-window upsert.
     assert.equal(c.push_items.length, 1, 'one closed-window emit')
     assert.deepEqual(c.push_items[0].payload, { count: 2, sum: 30 })

package/test-v2/streams-unit/e2e.test.js

@@ -1,5 +1,5 @@
 /**
- * End-to-end test for queen-streams against a live Queen server + PG.
+ * End-to-end test for queen-streams against a live Queen server.
  *
  * What it covers (per the plan's Definition of Done):
  *   1. 10,000 messages across 50 partitions
@@ -8,14 +8,10 @@
  *   4. Exactly-once on the sink queue
  *   5. Per-partition state isolation
  *   6. Downstream consumer of sink wakes up immediately
- *      (validates inline update_partition_lookup_v1 in streams_cycle_v1)
  *
  * Prerequisites:
  *   - Queen running on QUEEN_URL (default http://localhost:6632)
- *   - The streams procedures applied (auto-loaded on Queen boot):
- *     002_streams_schema, 007_log_streams, 008_streams_register_query_v1,
- *     009_streams_state_get_v1 (the retired rows-era streams cycle's role
- *     now lives in 007_log_streams' log_streams_cycle_v1)
+ *   - A broker serving the /streams/v1 routes (register, state/get, cycle)
  *
  * Run:
  *   QUEEN_URL=http://localhost:6632 node --test test/e2e.test.js
@@ -129,7 +125,7 @@ describe('queen-streams e2e (live Queen)', { skip: !SHOULD_RUN }, () => {
 
     // 3. Mid-stream kill: after 1.5s, stop the runner abruptly to simulate
     //    a worker crash, then restart it. Cursor + state should reconcile
-    //    via Queen's lease/retry + queen_streams.state PK.
+    //    via Queen's lease/retry + the per-partition streams state key.
     setTimeout(async () => {
       if (!stopped) {
         await handle.stop()
@@ -205,8 +201,8 @@ describe('queen-streams e2e (live Queen)', { skip: !SHOULD_RUN }, () => {
       const winKey = m.data && m.data.__winKey
       // The aggregate value doesn't carry windowKey by default; we check for
       // duplicates by (partition + transactionId) instead, which Queen
-      // guarantees unique across a partition. The streams_cycle_v1 SP
-      // dedupes via the SAME unique constraint that push_messages_v3 uses.
+      // guarantees unique across a partition. The streams cycle's sink
+      // pushes go through the SAME transactionId dedup as any push.
       const dedupKey = `${m.partition}|${m.transactionId}`
       assert.ok(!seen.has(dedupKey), 'duplicate sink message for ' + dedupKey)
       seen.add(dedupKey)
@@ -214,7 +210,7 @@ describe('queen-streams e2e (live Queen)', { skip: !SHOULD_RUN }, () => {
 
     // 6. Per-partition state isolation: every cycle the runner committed
     //    must touch state rows ONLY for its own partition. We can't easily
-    //    observe this from the client side (no DB access), but the
+    //    observe this from the client side (the stored state is private), but the
     //    aggregate-shape correctness in (5) above implies it (a leaked
     //    cross-partition write would produce wrong sums).
 

package/test-v2/streams-unit/gate.test.js

@@ -0,0 +1,189 @@
+/**
+ * .gate() settles SOURCE MESSAGES, not envelopes.
+ *
+ * The gate's partial ack is an offset commit: a 2.x broker advances the
+ * cursor `ack.count` messages from the head of the leased batch and keeps the
+ * lease (release_lease=false). A pre-stage breaks the one-to-one map between
+ * messages and the envelopes the gate sees -- `.filter()` leaves a message
+ * with none, `.flatMap()` with several -- and the runner counted envelopes:
+ *
+ *   flatMap x2, message 2 denied   count 2 = messages 1 AND 2 acked; the
+ *                                  denied message was never redelivered
+ *                                  (reproduced live on 2.0.0-beta.6: 4 of 6
+ *                                  sink items, message 2 lost)
+ *   filter drops every message     nothing committed; the batch came back on
+ *                                  every lease expiry, forever
+ *
+ * Same fix as the Rust client (clients/client-rust/src/streams/runner.rs,
+ * gate_cycle): a message is settled only when every envelope it produced is
+ * allowed, and what a denied message did to the state is rolled back.
+ */
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Stream } from '../../client-v2/streams/Stream.js'
+import { createFakeStreamsServer, createFakeSource, fakeMessage } from './fakeServer.js'
+
+const PART = '00000000-0000-0000-0000-00000000ga7e'
+
+const batch = (...ns) => ns.map((n, i) => fakeMessage({
+  partitionId: PART,
+  partitionName: 'tenant-1',
+  data: { n },
+  createdAt: `2026-10-02T10:00:0${i}.000Z`
+}))
+
+const quiet = { info() {}, warn() {}, error() {}, debug() {} }
+
+// Run until `cycles` cycles were committed (or the time is up), then stop.
+async function runFor(server, stream, { cycles = 1, timeoutMs = 1500, queryId }) {
+  const baseline = server.recorded.cycles.length
+  const handle = await stream.run({ queryId, url: server.url, logger: quiet })
+  const start = Date.now()
+  while (server.recorded.cycles.length - baseline < cycles && Date.now() - start < timeoutMs) {
+    await new Promise(r => setTimeout(r, 20))
+  }
+  await handle.stop()
+  return { handle, cycles: server.recorded.cycles.slice(baseline) }
+}
+
+describe('.gate() — the partial ack counts source messages', () => {
+  let server
+  before(async () => { server = await createFakeStreamsServer() })
+  after(async () => { await server.close() })
+
+  it('flatMap before the gate: a denied message is not acked with its predecessor', async () => {
+    const msgs = batch(1, 2, 3)
+    const stream = Stream.from(createFakeSource('src', [msgs]))
+      .flatMap(m => [m.data, m.data])
+      .gate(v => v.n !== 2)
+      .to({ _queueName: 'sink' })
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.flatmap' })
+    assert.equal(cycles.length, 1)
+    const c = cycles[0]
+    assert.equal(c.ack.count, 1, 'one MESSAGE settled; two envelopes acked messages 1 and 2')
+    assert.equal(c.ack.transactionId, msgs[0].transactionId)
+    assert.equal(c.release_lease, false, 'the denied tail stays leased, in order')
+    assert.deepEqual(c.push_items.map(p => p.payload.n), [1, 1], 'only the settled message reaches the sink')
+  })
+
+  it('flatMap before the gate: a message half allowed is not settled at all', async () => {
+    let seen = 0
+    const stream = Stream.from(createFakeSource('src', [batch(1, 2)]))
+      .flatMap(m => [m.data, m.data])
+      .gate(() => ++seen === 1)     // the first value of message 1 passes, its second does not
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.half', timeoutMs: 400 })
+    assert.equal(cycles.length, 0, 'nothing settled, nothing committed: the lease brings both back')
+  })
+
+  it('filter before the gate: dropped messages are settled with the prefix', async () => {
+    const msgs = batch(1, 2, 3)
+    const stream = Stream.from(createFakeSource('src', [msgs]))
+      .filter(m => m.data.n === 3)
+      .gate(() => true)
+      .to({ _queueName: 'sink' })
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.filter' })
+    assert.equal(cycles.length, 1)
+    assert.equal(cycles[0].ack.count, 3, 'all three messages are done; one envelope is not one message')
+    assert.equal(cycles[0].ack.transactionId, msgs[2].transactionId)
+    assert.equal(cycles[0].release_lease, true)
+    assert.deepEqual(cycles[0].push_items.map(p => p.payload.n), [3])
+  })
+
+  it('filter that drops the whole batch: the batch is acked, not held forever', async () => {
+    const msgs = batch(1, 2)
+    const stream = Stream.from(createFakeSource('src', [msgs]))
+      .filter(() => false)
+      .gate(() => true)
+      .to({ _queueName: 'sink' })
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.allfiltered' })
+    assert.equal(cycles.length, 1, 'a cycle is committed even though the gate saw nothing')
+    assert.equal(cycles[0].ack.count, 2)
+    assert.equal(cycles[0].release_lease, true)
+    assert.equal(cycles[0].push_items.length, 0)
+    assert.equal(cycles[0].state_ops.length, 0)
+  })
+
+  it('filter, then a deny: the count stops before the denied message', async () => {
+    const msgs = batch(1, 2, 3, 4)
+    const stream = Stream.from(createFakeSource('src', [msgs]))
+      .filter(m => m.data.n !== 2)      // message 2 produces nothing
+      .gate(v => v.n !== 3)             // message 3 is denied
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.filterdeny' })
+    assert.equal(cycles.length, 1)
+    assert.equal(cycles[0].ack.count, 2, 'messages 1 and 2 settled; the gate allowed one envelope')
+    assert.equal(cycles[0].ack.transactionId, msgs[1].transactionId)
+    assert.equal(cycles[0].release_lease, false)
+  })
+
+  it('a denied first message still commits nothing', async () => {
+    const stream = Stream.from(createFakeSource('src', [batch(1, 2)]))
+      .gate(() => false)
+    const { cycles, handle } = await runFor(server, stream, { queryId: 'gate.firstdeny', timeoutMs: 400 })
+    assert.equal(cycles.length, 0)
+    assert.equal(handle.metrics().gateDenialsTotal, 2, 'denials are counted in messages')
+  })
+})
+
+describe('.gate() — a denied message did not happen', () => {
+  let server
+  before(async () => { server = await createFakeStreamsServer() })
+  after(async () => { await server.close() })
+
+  it('what a denied message did to the state is not persisted', async () => {
+    // A counter the gate bumps BEFORE deciding: message 1 is allowed at 1,
+    // message 2 bumps it to 2 and is denied. The state that commits is 1.
+    const stream = Stream.from(createFakeSource('src', [batch(1, 2)]))
+      .gate((v, ctx) => {
+        ctx.state.count = (ctx.state.count || 0) + 1
+        return v.n === 1
+      })
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.rollback' })
+    assert.equal(cycles.length, 1)
+    assert.equal(cycles[0].ack.count, 1)
+    assert.deepEqual(cycles[0].state_ops, [{ type: 'upsert', key: PART, value: { count: 1 } }])
+  })
+
+  it('a key only a denied message touched is not written at all', async () => {
+    const stream = Stream.from(createFakeSource('src', [batch(1, 2)]))
+      .keyBy(m => `k${m.data.n}`)
+      .gate((v, ctx) => {
+        ctx.state.seen = true
+        return v.n === 1
+      })
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.untouched' })
+    assert.equal(cycles.length, 1)
+    assert.deepEqual(cycles[0].state_ops.map(op => op.key), ['k1'])
+  })
+})
+
+describe('.gate() — the prefix is the broker\'s, in offset order', () => {
+  let server
+  before(async () => { server = await createFakeStreamsServer() })
+  after(async () => { await server.close() })
+
+  it('orders by offset when the broker sends one, not by (createdAt, id)', async () => {
+    // Two producers pushed in the same millisecond: same createdAt, and the
+    // message the broker stored FIRST carries the higher id. Sorting by
+    // (createdAt, id) put it second, so a deny on it acked it anyway.
+    const createdAt = '2026-10-02T10:00:00.000Z'
+    const first = { ...fakeMessage({ partitionId: PART, data: { n: 'first' }, createdAt }), id: 'msg-z', offset: 10 }
+    const second = { ...fakeMessage({ partitionId: PART, data: { n: 'second' }, createdAt }), id: 'msg-a', offset: 11 }
+    const stream = Stream.from(createFakeSource('src', [[second, first]]))
+      .gate(v => v.n === 'first')
+
+    const { cycles } = await runFor(server, stream, { queryId: 'gate.offsetorder' })
+    assert.equal(cycles.length, 1)
+    assert.equal(cycles[0].ack.count, 1)
+    assert.equal(cycles[0].ack.transactionId, first.transactionId, 'the settled prefix is offset 10, the one the broker acks')
+    assert.equal(cycles[0].release_lease, false)
+  })
+})