queen-mq 0.14.1 → 0.16.0-beta.0

package/README.md

@@ -22,7 +22,7 @@ Queen MQ is a PostgreSQL-backed message queue system with a powerful feature set
 - **Consumer Groups** - Kafka-style consumer groups for scalability
 - **Flexible Semantics** - Exactly-once, at-least-once, and at-most-once delivery
 - **Transactions** - Atomic operations across push and ack
-- **High Performance** - 200K+ messages/sec with proper batching
+- **High Performance** — 104K msg/s push, 165K msg/s fan-out with consumer groups on a single 32-core node ([benchmarks](https://github.com/queen-mq/queen/tree/master/benchmark-queen/2026-04-26))
 - **Subscription Modes** - Process from beginning, new messages only, or from timestamp
 - **Dead Letter Queue** - Automatic failure handling and monitoring
 - **Message Tracing** - Debug distributed workflows with trace timelines
@@ -179,7 +179,7 @@ const queen = new Queen({
   urls: ['http://server1:6632', 'http://server2:6632'],
   timeoutMillis: 30000,
   retryAttempts: 3,
-  loadBalancingStrategy: 'round-robin',  // or 'session'
+  loadBalancingStrategy: 'affinity',  // or 'round-robin', 'session'
   enableFailover: true
 })
 ```
@@ -250,6 +250,47 @@ for (const message of messages) {
 }
 ```
 
+### Multi-Partition Pop (Drain Many Partitions Per Call)
+
+```javascript
+// One round-trip drains up to 200 messages spread across up to 50 partitions.
+// batch(200) is the GLOBAL cap on total messages; partitions(50) is the
+// hard cap on partitions claimed. All claimed partitions share one leaseId
+// — a single renew() call extends every partition's lease atomically.
+const messages = await queen.queue('events')
+  .batch(200)
+  .partitions(50)
+  .wait(true)
+  .pop()
+
+// Each message carries its own partition info (per-message partitionId,
+// partition name, leaseId, consumerGroup) — ACK and renew always work
+// message-by-message regardless of how many partitions the batch spans.
+for (const m of messages) {
+  console.log(`from ${m.partition}:`, m.data)
+}
+
+// Same builder works on .consume() for long-running workers
+await queen.queue('events')
+  .batch(100)
+  .partitions(8)
+  .consume(async (msgs) => {
+    for (const m of msgs) await process(m.data)
+  })
+```
+
+**When to use:** queues with many partitions where each partition only has
+a handful of new messages per polling interval (per-customer event streams,
+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.
+
+`.partitions(N)` only applies to **wildcard** pops; specifying
+`.partition('name')` ignores the cap.
+
 ### Transactions (Atomic Operations)
 
 ```javascript
@@ -451,6 +492,7 @@ await queen.queue('q').buffer({ messageCount: 100, timeMillis: 1000 }).push([...
 const msgs = await queen.queue('q').pop()
 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
 ```
 
 ### Consume
@@ -522,8 +564,10 @@ await queen.close()  // Flush buffers and close connections
   timeoutMillis: 30000,
   retryAttempts: 3,
   retryDelayMillis: 1000,
-  loadBalancingStrategy: 'round-robin',
-  enableFailover: true
+  loadBalancingStrategy: 'affinity',   // 'affinity' | 'round-robin' | 'session'
+  affinityHashRing: 128,
+  enableFailover: true,
+  healthRetryAfterMillis: 5000
 }
 ```
 
@@ -611,17 +655,18 @@ const messages: Message<OrderData>[] = await queen.queue('orders').pop()
 
 ## Documentation
 
-- **[Complete V2 Guide](client-v2/README.md)** - Full tutorial with all features (94 test examples)
-- **[HTTP API Reference](https://github.com/smartpricing/queen/blob/master/server/API.md)** - Raw HTTP endpoints
-- **[Server Guide](https://github.com/smartpricing/queen/blob/master/server/README.md)** - Server setup and configuration
-- **[Architecture Guide](https://github.com/smartpricing/queen/blob/master/documentation/ARCHITECTURE.md)** - Deep dive into internals
+- **[Complete V2 Guide](client-v2/README.md)** — full tutorial with all features
+- **[HTTP API Reference](https://github.com/queen-mq/queen/blob/master/server/API.md)** — raw HTTP endpoints
+- **[Server Guide](https://github.com/queen-mq/queen/blob/master/server/README.md)** — server setup and configuration
+- **[Architecture & internals](https://queenmq.com/architecture.html)** — published architecture overview
+- **[libqueen design notes](https://github.com/queen-mq/queen/blob/master/cdocs/LIBQUEEN_IMPROVEMENTS.md)** — adaptive engine deep-dive
 
 ---
 
 ## Support
 
-- **GitHub:** [smartpricing/queen](https://github.com/smartpricing/queen)
-- **Issues:** [GitHub Issues](https://github.com/smartpricing/queen/issues)
+- **GitHub:** [queen-mq/queen](https://github.com/queen-mq/queen)
+- **Issues:** [GitHub Issues](https://github.com/queen-mq/queen/issues)
 - **LinkedIn:** [Smartness](https://www.linkedin.com/company/smartness-com/)
 
 ---

package/client-v2/Queen.js

@@ -23,9 +23,12 @@ export class Queen {
   #admin = null
 
   constructor(config = {}) {
-    // Configure custom logger before anything else
+    // Configure custom logger before anything else.
+    // Opt into structured field logging with `structuredLogs: true` (the logger
+    // must accept a leading merge object, e.g. pino/bunyan); defaults to the
+    // backward-compatible single-string format.
     if (config && typeof config === 'object' && !Array.isArray(config) && config.logger) {
-      logger.configure(config.logger)
+      logger.configure(config.logger, { structured: config.structuredLogs === true })
     }
 
     logger.log('Queen.constructor', { config: typeof config === 'object' && !Array.isArray(config) ? { ...config, urls: config.urls?.length || 0 } : { type: typeof config } })

package/client-v2/README.md

@@ -1605,6 +1605,11 @@ const msgs = await queen.queue('q').batch(10).wait(true).pop()
 
 // Pop from partition
 const msgs = await queen.queue('q').partition('p1').pop()
+
+// Multi-partition pop: drain up to 50 partitions in one round-trip,
+// capped at 200 total messages. All partitions share one leaseId.
+// Each returned message carries its own partitionId / partition / leaseId.
+const msgs = await queen.queue('q').batch(200).partitions(50).pop()
 ```
 
 ### Consume
@@ -1625,6 +1630,12 @@ await queen.queue('q').concurrency(5).consume(async (msg) => { /* 5 parallel wor
 // Consume from partition
 await queen.queue('q').partition('p1').consume(async (msg) => { /* process */ })
 
+// Multi-partition consume: drain up to 8 partitions per poll.
+// batch(100) is a global cap on total messages across all claimed partitions.
+await queen.queue('q').batch(100).partitions(8).consume(async (msgs) => {
+  for (const m of msgs) await process(m.data)  // m.partitionId / m.partition baked in
+})
+
 // Consume with consumer group
 await queen.queue('q').group('my-group').consume(async (msg) => { /* process */ })
 
@@ -1777,11 +1788,13 @@ await queen.close()
 ### Client Defaults
 ```javascript
 {
-  timeoutMillis: 30000,               // 30 seconds
+  timeoutMillis: 30000,                  // 30 seconds
   retryAttempts: 3,
   retryDelayMillis: 1000,
-  loadBalancingStrategy: 'round-robin',
-  enableFailover: true
+  loadBalancingStrategy: 'affinity',     // 'affinity' | 'round-robin' | 'session'
+  affinityHashRing: 128,
+  enableFailover: true,
+  healthRetryAfterMillis: 5000
 }
 ```
 
@@ -1863,7 +1876,7 @@ Example log output:
 Here's a complete example showing many features together:
 
 ```javascript
-import { Queen } from './client-js/client-v2/index.js'
+import { Queen } from './index.js'
 
 const queen = new Queen('http://localhost:6632')
 
@@ -1982,9 +1995,10 @@ process.on('SIGINT', async () => {
 You now know everything about Queen v2! 🎉
 
 **Additional resources:**
-- [API Documentation](../../server/API.md) - Complete API reference
-- [Test Examples](../test-v2/) - 94 working test cases
-- [Architecture Guide](../../docs/) - Deep dive into Queen's internals
+- [API Documentation](../../../server/API.md) — complete HTTP API reference
+- [Test Examples](../test-v2/) — runnable test cases
+- [Architecture overview](https://queenmq.com/architecture.html) — published deep-dive
+- [libqueen design notes](../../../cdocs/LIBQUEEN_IMPROVEMENTS.md) — server internals
 
 **Need help?** Check out the test files in `test-v2/` - they're full of working examples!
 

package/client-v2/builders/QueueBuilder.js

@@ -49,6 +49,16 @@ export class QueueBuilder {
     this.#queueName = queueName
   }
 
+  /**
+   * Public read-only accessor for the queue name. Useful for tooling that
+   * holds a QueueBuilder reference and needs to know the underlying name —
+   * e.g. @queenmq/streams resolves sink-queue names from the QueueBuilder
+   * passed to .to(...).
+   */
+  get name() {
+    return this.#queueName
+  }
+
   // ===========================
   // Affinity Key Generation
   // ===========================

package/client-v2/index.js

@@ -1,8 +1,23 @@
 /**
  * Queen Message Queue Client - Entry Point
+ *
+ * One npm package for everything:
+ *   import { Queen, Stream, tokenBucketGate, slidingWindowGate } from 'queen-mq'
+ *
+ * The broker client (`Queen`, `Admin`) and the fluent streaming SDK
+ * (`Stream`, `tokenBucketGate`, `slidingWindowGate`, plus all operator
+ * classes) ship in the same package. ESM named exports + tree-shaking
+ * mean bundlers (Vite, Rollup, webpack with `sideEffects:false`) can
+ * drop the streaming code from your output if you only import broker
+ * symbols.
+ *
+ * Streaming source lives under `./streams/` of this package.
  */
 
 export { Queen } from './Queen.js'
 export { Admin } from './admin/Admin.js'
 export { CLIENT_DEFAULTS, QUEUE_DEFAULTS, CONSUME_DEFAULTS, POP_DEFAULTS, BUFFER_DEFAULTS } from './utils/defaults.js'
 
+// Streaming SDK — full source under ./streams/.
+export { Stream } from './streams/Stream.js'
+export { tokenBucketGate, slidingWindowGate } from './streams/helpers/rateLimiter.js'

package/client-v2/streams/Stream.js

@@ -0,0 +1,392 @@
+/**
+ * Stream — fluent builder for streaming pipelines.
+ *
+ * A Stream is an immutable chain of Operators that gets compiled and run
+ * by a Runner. Each combinator (`.map`, `.filter`, ...) returns a NEW Stream
+ * with the operator appended; the chain is finalized by `.run({ queryId })`.
+ *
+ * The chain shape (operator types + their stateful config) is fingerprinted
+ * via configHash so that re-deploying with a different chain under the same
+ * queryId is rejected at registration unless `{ reset: true }` is passed.
+ */
+
+import { MapOperator } from './operators/MapOperator.js'
+import { FilterOperator } from './operators/FilterOperator.js'
+import { FlatMapOperator } from './operators/FlatMapOperator.js'
+import { KeyByOperator } from './operators/KeyByOperator.js'
+import { WindowTumblingOperator } from './operators/WindowTumblingOperator.js'
+import { WindowSlidingOperator } from './operators/WindowSlidingOperator.js'
+import { WindowSessionOperator } from './operators/WindowSessionOperator.js'
+import { WindowCronOperator } from './operators/WindowCronOperator.js'
+import { ReduceOperator } from './operators/ReduceOperator.js'
+import { AggregateOperator } from './operators/AggregateOperator.js'
+import { GateOperator } from './operators/GateOperator.js'
+import { SinkOperator } from './operators/SinkOperator.js'
+import { ForeachOperator } from './operators/ForeachOperator.js'
+import { Runner } from './runtime/Runner.js'
+import { configHashOf } from './util/configHash.js'
+
+export class Stream {
+  /**
+   * Build a Stream sourced from a Queen QueueBuilder.
+   *
+   * @param {object} queueBuilder - the result of queen.queue('name') — must
+   *   expose .pop() / .ack() / .push() and the queue name.
+   * @param {object} [options]
+   * @returns {Stream}
+   */
+  static from(queueBuilder, options = {}) {
+    return new Stream({
+      source: queueBuilder,
+      operators: [],
+      sourceOptions: options
+    })
+  }
+
+  /**
+   * @param {object} args
+   * @param {object} args.source - source QueueBuilder
+   * @param {object} [args.sourceOptions]
+   * @param {Array} args.operators - operator chain
+   */
+  constructor({ source, operators, sourceOptions = {} }) {
+    this._source = source
+    this._sourceOptions = sourceOptions
+    this._operators = operators
+  }
+
+  // ---------------------------------------------------------------- Stateless
+
+  /** @param {(msg:object)=>any|Promise<any>} fn */
+  map(fn) {
+    return this._extend(new MapOperator(fn))
+  }
+
+  /** @param {(msg:object)=>boolean|Promise<boolean>} predicate */
+  filter(predicate) {
+    return this._extend(new FilterOperator(predicate))
+  }
+
+  /** @param {(msg:object)=>(any[]|Promise<any[]>)} fn */
+  flatMap(fn) {
+    return this._extend(new FlatMapOperator(fn))
+  }
+
+  // -------------------------------------------------------------------- Keying
+
+  /**
+   * Override the implicit partition-key for downstream stateful operators.
+   * If omitted, stateful operators use the source partition_id as the key,
+   * which is the natural fit for queues partitioned by entity.
+   *
+   * Warning: when the key differs from the partition, multiple workers
+   * holding different partition leases may write the same logical key,
+   * causing cross-worker contention on (query_id, partition_id, key) state
+   * rows. The repartition pattern (push to a co-keyed intermediate queue,
+   * then process) avoids this.
+   *
+   * @param {(msg:object)=>string} fn
+   */
+  keyBy(fn) {
+    return this._extend(new KeyByOperator(fn))
+  }
+
+  // -------------------------------------------------------------------- Windows
+
+  /**
+   * Fixed-size, non-overlapping windows.
+   * @param {{
+   *   seconds: number,
+   *   gracePeriod?: number,    // accept events for windowEnd + grace before closing
+   *   idleFlushMs?: number,    // close ripe windows on quiet partitions every N ms (default 5000)
+   *   eventTime?: (msg:any)=>(number|Date|string),  // event-time mode if set
+   *   allowedLateness?: number, // event-time only: drop events older than wm - allowedLateness
+   *   onLate?: 'drop' | 'include'
+   * }} opts
+   */
+  windowTumbling(opts) {
+    return this._extend(new WindowTumblingOperator(opts))
+  }
+
+  /**
+   * Overlapping fixed-size windows that hop every `slide` seconds.
+   * Each event creates `size/slide` state rows per key.
+   * @param {{size:number, slide:number, gracePeriod?:number, idleFlushMs?:number,
+   *          eventTime?:(msg:any)=>any, allowedLateness?:number, onLate?:string}} opts
+   */
+  windowSliding(opts) {
+    return this._extend(new WindowSlidingOperator(opts))
+  }
+
+  /**
+   * Per-key activity-based windows. A session for a key extends as long
+   * as events keep arriving within `gap` seconds of each other.
+   * @param {{gap:number, gracePeriod?:number, idleFlushMs?:number,
+   *          eventTime?:(msg:any)=>any, allowedLateness?:number, onLate?:string}} opts
+   */
+  windowSession(opts) {
+    return this._extend(new WindowSessionOperator(opts))
+  }
+
+  /**
+   * Wall-clock-aligned windows. Currently supports the `every:` shorthand
+   * (`'second'|'minute'|'hour'|'day'|'week'`); full cron syntax is reserved
+   * for v0.3.
+   * @param {{every:string, gracePeriod?:number, idleFlushMs?:number,
+   *          eventTime?:(msg:any)=>any, allowedLateness?:number, onLate?:string}} opts
+   */
+  windowCron(opts) {
+    return this._extend(new WindowCronOperator(opts))
+  }
+
+  // -------------------------------------------------------------------- Reduce
+
+  /**
+   * @template T
+   * @param {(acc:T, msg:object)=>T|Promise<T>} fn
+   * @param {T} initial
+   */
+  reduce(fn, initial) {
+    return this._extend(new ReduceOperator(fn, initial))
+  }
+
+  /**
+   * Sugar over reduce. Each provided extractor produces one named field on
+   * the aggregate value.
+   *
+   * Example:
+   *   .aggregate({ count: () => 1, sum: m => m.data.amount })
+   *
+   * Output value shape: { count: number, sum: number, ... }
+   *
+   * @param {Record<string,(msg:object)=>number>} extractors
+   */
+  aggregate(extractors) {
+    return this._extend(new AggregateOperator(extractors))
+  }
+
+  // ---------------------------------------------------------------------- Gate
+
+  /**
+   * Per-message ALLOW/DENY decision with persistent per-key state.
+   *
+   * Used to build rate limiters, throttlers, fairness gates, circuit
+   * breakers — anything where the semantics is "should this message
+   * proceed RIGHT NOW given the recent history of this key?".
+   *
+   * 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,
+   *                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)
+   *
+   * Return `true` (or `{allow:true}`) to let the message through.
+   * Return `false` (or `{allow:false}`) to halt the batch here. The runner
+   * 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.
+   *
+   * Example (token bucket rate limiter):
+   *
+   *   .gate((req, ctx) => {
+   *     const cfg = { capacity: 10, refillPerSec: 5 }
+   *     const now = ctx.streamTimeMs
+   *     ctx.state.tokens       ??= cfg.capacity
+   *     ctx.state.lastRefillAt ??= now
+   *     const elapsedSec = (now - ctx.state.lastRefillAt) / 1000
+   *     ctx.state.tokens = Math.min(
+   *       cfg.capacity,
+   *       ctx.state.tokens + elapsedSec * cfg.refillPerSec
+   *     )
+   *     ctx.state.lastRefillAt = now
+   *     if (ctx.state.tokens >= 1) {
+   *       ctx.state.tokens -= 1
+   *       return true
+   *     }
+   *     return false   // halt batch, lease expires, redelivered in order
+   *   })
+   *
+   * Constraints
+   *  - At most one .gate() per stream (multiple gates would compose
+   *    awkwardly with the partial-ack semantics; chain serially via two
+   *    streams if needed).
+   *  - .gate() is incompatible with windowing/reducing in the same stream.
+   *    The window+reducer model assumes the FULL batch is consumed atomically;
+   *    gating breaks that. Run them as two separate streams.
+   *
+   * @param {(value:any, ctx:{state:object, streamTimeMs:number, partitionId:string}) => boolean | {allow:boolean} | Promise<boolean | {allow:boolean}>} fn
+   */
+  gate(fn) {
+    return this._extend(new GateOperator(fn))
+  }
+
+  // ---------------------------------------------------------------------- Sink
+
+  /**
+   * Sink to a Queen queue. The cycle commits state + push + ack atomically.
+   *
+   * @param {object} sinkQueueBuilder - `queen.queue('sink-name')`
+   * @param {{partition?: string|((value:any)=>string)}} [opts]
+   */
+  to(sinkQueueBuilder, opts = {}) {
+    return this._extend(new SinkOperator(sinkQueueBuilder, opts))
+  }
+
+  /**
+   * Terminal at-least-once side-effect. The cycle acks the source only after
+   * `fn` has resolved successfully, so a crash mid-`fn` will redeliver. If
+   * you need exactly-once external effects, write to a sink queue and have
+   * a dedicated worker consume it.
+   *
+   * @param {(value:any)=>void|Promise<void>} fn
+   */
+  foreach(fn) {
+    return this._extend(new ForeachOperator(fn))
+  }
+
+  // ----------------------------------------------------------------- Compile/run
+
+  /**
+   * Start the streaming runner. Returns a handle exposing:
+   *   - stop(): graceful drain
+   *   - metrics(): cycle/throughput/lag stats
+   *
+   * @param {object} runOptions
+   * @param {string} runOptions.queryId - durable identity of this query
+   * @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.subscriptionFrom] - ISO timestamp or 'now'
+   * @param {boolean} [runOptions.reset=false] - wipe state on config_hash mismatch
+   * @param {(err:Error, ctx:object)=>void} [runOptions.onError] - cycle error hook
+   * @param {AbortSignal} [runOptions.abortSignal] - external cancellation
+   */
+  async run(runOptions) {
+    if (!runOptions || !runOptions.queryId) {
+      throw new Error('run({ queryId }) is required')
+    }
+    const compiled = this._compile()
+    const runner = new Runner({
+      ...runOptions,
+      stream: compiled
+    })
+    await runner.start()
+    return runner
+  }
+
+  // ===== internals =========================================================
+
+  /** @returns {Stream} */
+  _extend(operator) {
+    return new Stream({
+      source: this._source,
+      sourceOptions: this._sourceOptions,
+      operators: [...this._operators, operator]
+    })
+  }
+
+  /**
+   * Compile the operator chain into a runnable description: stages, sink,
+   * and the configHash. Exposed for the Runner.
+   */
+  _compile() {
+    const sink = this._operators.find(op => op.kind === 'sink' || op.kind === 'foreach')
+    const sinkIdx = sink ? this._operators.indexOf(sink) : this._operators.length
+
+    // Verify the sink (if present) is the last operator.
+    if (sink && sinkIdx !== this._operators.length - 1) {
+      throw new Error(
+        'sink operators (.to / .foreach) must be the last in the chain; ' +
+        `found ${sink.kind} at position ${sinkIdx} of ${this._operators.length}`
+      )
+    }
+
+    const upstream = sink ? this._operators.slice(0, sinkIdx) : this._operators
+
+    // Decompose into stages:
+    //   pre:    [stateless...] applied to each source record
+    //   keyBy:  optional KeyByOperator (operates on source record)
+    //   window: optional WindowTumblingOperator (annotates envelopes)
+    //   reducer: optional ReduceOperator/AggregateOperator
+    //   post:   [stateless...] applied to each emit value (post-reducer)
+    //   sink:   optional SinkOperator/ForeachOperator (terminal)
+    //
+    // "phase" walks from `pre` -> `keyed` -> `window` -> `reducer` -> `post`.
+    // Stateless operators belong to whichever side of the reducer they're
+    // declared on. A reducer is required to switch to `post`; without one,
+    // all stateless ops are pre-stage.
+    const stages = {
+      pre: [],
+      keyBy: null,
+      window: null,
+      reducer: null,
+      gate: null,
+      post: [],
+      sink
+    }
+    let phase = 'pre'
+    for (const op of upstream) {
+      if (op.kind === 'map' || op.kind === 'filter' || op.kind === 'flatMap') {
+        if (phase === 'pre' || phase === 'keyed') {
+          stages.pre.push(op)
+        } else if (phase === 'window') {
+          // Stateless ops between window and reducer are unusual; treat as pre
+          // (they see the windowed envelope but have no reducer state to act on).
+          stages.pre.push(op)
+        } else {
+          // post-reducer or post-gate: operates on each emit value.
+          stages.post.push(op)
+        }
+      } else if (op.kind === 'keyBy') {
+        if (stages.keyBy) throw new Error('only one .keyBy() per stream')
+        if (phase === 'reducer' || phase === 'gate') {
+          throw new Error('.keyBy() must come before window/reduce/gate')
+        }
+        stages.keyBy = op
+        if (phase === 'pre') phase = 'keyed'
+      } else if (op.kind === 'window') {
+        if (stages.window) throw new Error('only one window operator per stream')
+        if (phase === 'reducer') throw new Error('window must come before reduce/aggregate')
+        if (stages.gate) throw new Error('window+reduce is incompatible with .gate() in the same stream')
+        stages.window = op
+        phase = 'window'
+      } else if (op.kind === 'reduce' || op.kind === 'aggregate') {
+        if (stages.reducer) throw new Error('only one reduce/aggregate per stream')
+        if (!stages.window) {
+          throw new Error('reduce/aggregate requires a preceding window operator')
+        }
+        if (stages.gate) throw new Error('reduce/aggregate is incompatible with .gate() in the same stream')
+        stages.reducer = op
+        phase = 'reducer'
+      } else if (op.kind === 'gate') {
+        if (stages.gate) throw new Error('only one .gate() per stream')
+        if (stages.window || stages.reducer) {
+          throw new Error('.gate() is incompatible with windowing/reduce in the same stream')
+        }
+        stages.gate = op
+        phase = 'gate'
+      } else {
+        throw new Error(`unsupported operator: ${op.kind}`)
+      }
+    }
+    // Backwards-compat: keep the old name `stateless` aliasing `pre` so any
+    // existing code paths that referenced stages.stateless keep working.
+    stages.stateless = stages.pre
+
+    // Compute config_hash from the chain shape (operator kinds + their
+    // structural config; user functions are intentionally not hashed since
+    // we cannot stably serialise closures).
+    const config_hash = configHashOf(this._operators)
+
+    return {
+      source: this._source,
+      sourceOptions: this._sourceOptions,
+      stages,
+      operators: this._operators,
+      config_hash
+    }
+  }
+}