queen-mq 1.0.6 → 1.1.0

package/client-v2/utils/conflation.js

@@ -0,0 +1,118 @@
+/**
+ * Conflation response contract (PLAN_CONFLATION.md §3.3, §4).
+ *
+ * Conflation — last-value delivery for a consumer group — is declared as a pop
+ * query parameter and answered in the pop RESPONSE. Two response keys carry the
+ * whole client-side contract, and both are handled here so that pop() and the
+ * consume loop cannot drift apart:
+ *
+ *   "conflation": true          the broker actually applied last-value delivery.
+ *                               Rides EVERY conflating response, empty ones
+ *                               included — a conflating pop answers 200 with a
+ *                               body instead of a bodiless 204 precisely so the
+ *                               echo has somewhere to sit.
+ *   "conflationConflict": true  this consumer declared a policy the group does
+ *                               not have. The STORED group setting wins (§3.3);
+ *                               the consumer keeps working and warns once.
+ *
+ * DEGRADE LOUDLY (§4). No SDK negotiates a version with the broker. A 1.1.0
+ * client against an older broker sends `conflation=true`, the broker ignores the
+ * unknown query parameter, and the consumer silently processes the entire
+ * backlog message by message — the exact silent failure the feature must not
+ * have. So: requested conflation + no echo => raise, on the FIRST response,
+ * before a single message is handled. `null` (an old broker's 204 on an empty
+ * pop) is the most important case to raise on, not the least: it is what an idle
+ * queue looks like, and it is the first thing a fresh consumer sees.
+ */
+
+import * as logger from './logger.js'
+
+/** `error.code` on the degrade-loudly error, so callers can branch without string-matching. */
+export const CONFLATION_UNSUPPORTED = 'conflation_unsupported'
+
+/** The message the plan fixes for every SDK (§4). Keep it identical across clients. */
+export const CONFLATION_UNSUPPORTED_MESSAGE =
+  'conflation was requested but this broker did not apply it — requires broker >= 1.1.0'
+
+// Once per (queue, group) PER PROCESS, per §3.3: a mismatched fleet during a
+// rolling deploy would otherwise emit one warning per pop, forever.
+const warnedConflicts = new Set()
+
+// A (queue, group) whose conflict the broker has ALREADY told us about. Proof
+// that this broker understands the parameter, so a later response without the
+// echo for that same pair is the same known conflict and not an old broker.
+//
+// It is belt-and-braces now rather than the load-bearing part it once was: a
+// 1.1.0 broker keeps the 200 and the body whenever the answer has anything to
+// say about conflation (`pop_status`), so an EMPTY conflicting pop carries
+// `conflationConflict` too and the check above catches it on the first round
+// trip. Keeping the memo costs nothing and still covers a first contact whose
+// answer somehow arrives without either key.
+const knownConflicts = new Set()
+
+/**
+ * Identity of the thing a policy hangs on: the queue (or namespace/task pop
+ * target) and the consumer group. Deliberately NOT the affinity key, which
+ * includes the partition — the policy is per (queue, group).
+ */
+export function conflationKey({ queue, namespace, task, group }) {
+  const target = queue || `${namespace || '*'}/${task || '*'}`
+  return `${target}|${group || '__QUEUE_MODE__'}`
+}
+
+/**
+ * Inspect one pop response on behalf of a consumer that ASKED for conflation.
+ * Call it for every response, including empty ones — that is where the old
+ * broker shows itself first.
+ *
+ * @param {object|null} result - parsed pop response (null for a 204)
+ * @param {object} ctx - { queue, namespace, task, group }
+ * @throws {Error} with `.code === CONFLATION_UNSUPPORTED` when the broker did
+ *   not apply conflation and did not explain why.
+ */
+export function checkConflationResponse(result, ctx) {
+  const key = conflationKey(ctx)
+
+  if (result && result.conflationConflict === true) {
+    knownConflicts.add(key)
+    if (!warnedConflicts.has(key)) {
+      warnedConflicts.add(key)
+      logger.warn('Conflation.conflict', {
+        queue: ctx.queue || null,
+        namespace: ctx.namespace || null,
+        task: ctx.task || null,
+        group: ctx.group || null,
+        message:
+          'this consumer declared conflation but the consumer group is registered without it — ' +
+          'the STORED group setting wins and this consumer is receiving normal batches. ' +
+          'Delete/recreate the group to change its policy.'
+      })
+    }
+    return
+  }
+
+  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
+
+  const error = new Error(CONFLATION_UNSUPPORTED_MESSAGE)
+  error.code = CONFLATION_UNSUPPORTED
+  throw error
+}
+
+/**
+ * Test hook: the warn-once and known-conflict registries are process-wide by
+ * design, which makes them sticky across tests in one runner process.
+ */
+export function resetConflationWarnings() {
+  warnedConflicts.clear()
+  knownConflicts.clear()
+}

package/client-v2/utils/defaults.js

@@ -63,7 +63,14 @@ 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 (1 = legacy single-partition)
+  // 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
+  // client that never touches it is byte-identical on the wire. Requires
+  // broker >= 1.1.0 — an older one ignores the parameter, which the SDK
+  // detects from the missing response echo and raises on (§4).
+  conflation: false
 }
 
 export const POP_DEFAULTS = {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "1.0.6",
+  "version": "1.1.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 && 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": "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: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/conflation-unit/conflationWire.test.js

@@ -0,0 +1,398 @@
+/**
+ * Conflation: wire contract + degrade-loudly (PLAN_CONFLATION.md §3.1, §3.3, §4).
+ *
+ * Three things are pinned here, and each of them is a defect that ships
+ * silently if it is not:
+ *
+ *   1. `conflation` reaches the wire from BOTH entry points. pop() and
+ *      consume() build their query strings in two SEPARATE places
+ *      (QueueBuilder.pop's inline params and ConsumerManager#buildParams) —
+ *      the standing comment at QueueBuilder.js documents a bug of exactly this
+ *      shape, where the parameter was added to one builder and the other kept
+ *      working while the option "did nothing". Both directions are asserted,
+ *      including the negative: an undeclared conflation must not add the key at
+ *      all, because the broker's response bytes are pinned byte-for-byte for
+ *      flag-off deployments.
+ *
+ *   2. Degrade-loudly (§4). No SDK negotiates a version, so a new client against
+ *      a pre-1.1.0 broker sends `conflation=true`, the broker ignores the unknown
+ *      query parameter, and the consumer quietly drains the whole backlog one
+ *      message at a time. The detection is response-driven: a conflating broker
+ *      echoes `"conflation":true` on EVERY response, empty ones included (it
+ *      answers 200-with-body instead of 204 precisely so the echo has somewhere
+ *      to ride), so the first round trip is enough. An old broker's empty pop is
+ *      a bodiless 204 => `null` here, which is why null must raise too.
+ *
+ *   3. Declaration conflict (§3.3). The STORED group policy wins; the consumer
+ *      that disagreed keeps working and warns exactly ONCE per (queue, group)
+ *      per process. Rejecting instead would take down the correct half of a
+ *      rolling deploy (plan Q3), and warning per response would flood.
+ *
+ * Same style as http-unit/retry429.test.js and kv-unit/kvWire.test.js: a real
+ * node:http server playing a canned plan, real fetch, real JSON. No mocking
+ * framework, and every assertion is about bytes that actually crossed a socket.
+ */
+
+import { describe, it, beforeEach, 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 * as logger from '../../client-v2/utils/logger.js'
+import {
+  CONFLATION_UNSUPPORTED,
+  resetConflationWarnings
+} from '../../client-v2/utils/conflation.js'
+import { withPlanServer, ok } from '../kv-unit/_planServer.js'
+
+const QUEUE = 'test-conflation'
+const GROUP = 'workers'
+
+/** 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 conflation echo keys under test. */
+function popBody(extra = {}, frames = [frame()]) {
+  return ok({ messages: frames, partitionsClaimed: frames.length, ...extra })
+}
+
+/** A pre-1.1.0 broker's empty pop: bodiless 204 (HttpClient turns it into null). */
+const emptyNoContent = { status: 204 }
+
+/** Query parameters of a recorded hit. */
+function query(url) {
+  const i = url.indexOf('?')
+  return new URLSearchParams(i < 0 ? '' : url.slice(i + 1))
+}
+
+/** Path (without query) of a recorded hit. */
+function path(url) {
+  const i = url.indexOf('?')
+  return i < 0 ? url : url.slice(0, i)
+}
+
+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()
+    }
+  })
+}
+
+// The conflict warning is deliberately once-per-process state, so every test
+// starts from a clean registry.
+beforeEach(() => { resetConflationWarnings() })
+afterEach(() => { resetConflationWarnings(); logger.configure(null) })
+
+// ---------------------------------------------------------------------------
+// 1. The option reaches the wire — from pop() AND from consume().
+// ---------------------------------------------------------------------------
+
+describe('conflation — wire (pop)', () => {
+  it('pop() sends conflation=true when the builder declares it', async () => {
+    await withQueen([popBody({ conflation: true })], popBody({ conflation: true }), async (queen, hits) => {
+      const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+
+      assert.equal(messages.length, 1)
+      assert.equal(hits.length, 1)
+      assert.equal(path(hits[0].url), `/api/v1/pop/queue/${QUEUE}`)
+      assert.equal(query(hits[0].url).get('conflation'), 'true')
+      assert.equal(query(hits[0].url).get('consumerGroup'), GROUP)
+    })
+  })
+
+  it('pop() omits the parameter entirely when conflation is not declared', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE).group(GROUP).pop()
+
+      assert.equal(hits.length, 1)
+      assert.equal(
+        query(hits[0].url).has('conflation'),
+        false,
+        'a flag-off pop must be byte-identical to today: no conflation key at all'
+      )
+    })
+  })
+})
+
+describe('conflation — wire (consume)', () => {
+  it('consume() sends conflation=true through ConsumerManager#buildParams', async () => {
+    await withQueen([popBody({ conflation: true })], popBody({ conflation: true }), async (queen, hits) => {
+      let handled = 0
+      await queen.queue(QUEUE)
+        .group(GROUP)
+        .conflation(true)
+        .wait(false)
+        .autoAck(false)
+        .limit(1)
+        .consume(async () => { handled++ })
+
+      assert.equal(handled, 1)
+      assert.ok(hits.length >= 1)
+      assert.equal(path(hits[0].url), `/api/v1/pop/queue/${QUEUE}`)
+      assert.equal(
+        query(hits[0].url).get('conflation'),
+        'true',
+        'consume() builds its params in a DIFFERENT place than pop() — both must carry it'
+      )
+    })
+  })
+
+  it('consume() omits the parameter entirely when conflation is not declared', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      await queen.queue(QUEUE)
+        .group(GROUP)
+        .wait(false)
+        .autoAck(false)
+        .limit(1)
+        .consume(async () => {})
+
+      assert.ok(hits.length >= 1)
+      assert.equal(query(hits[0].url).has('conflation'), false)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Degrade-loudly (§4): an old broker must never be silent.
+// ---------------------------------------------------------------------------
+
+describe('conflation — degrade loudly against a pre-1.1.0 broker', () => {
+  it('pop() raises when the response carries messages but no conflation echo', async () => {
+    await withQueen([popBody()], popBody(), async (queen) => {
+      await assert.rejects(
+        () => queen.queue(QUEUE).group(GROUP).conflation(true).pop(),
+        (err) => {
+          assert.equal(err.code, CONFLATION_UNSUPPORTED)
+          assert.match(err.message, /requires broker >= 1\.1\.0/)
+          return true
+        }
+      )
+    })
+  })
+
+  it('pop() raises on the FIRST empty pop, which an old broker answers 204', async () => {
+    await withQueen([emptyNoContent], emptyNoContent, async (queen, hits) => {
+      await assert.rejects(
+        () => queen.queue(QUEUE).group(GROUP).conflation(true).pop(),
+        (err) => {
+          assert.equal(err.code, CONFLATION_UNSUPPORTED)
+          return true
+        }
+      )
+      assert.equal(hits.length, 1, 'the error fires on the first round trip, before any message')
+    })
+  })
+
+  it('consume() stops the loop and rejects before the handler ever runs', async () => {
+    await withQueen([popBody()], popBody(), async (queen, hits) => {
+      let handled = 0
+      // consume() returns a thenable ConsumeBuilder, not a Promise: await it
+      // inside the arrow so assert.rejects sees a real promise.
+      await assert.rejects(
+        async () => {
+          await queen.queue(QUEUE)
+            .group(GROUP)
+            .conflation(true)
+            .wait(false)
+            .autoAck(false)
+            .consume(async () => { handled++ })
+        },
+        (err) => {
+          assert.equal(err.code, CONFLATION_UNSUPPORTED)
+          assert.match(err.message, /requires broker >= 1\.1\.0/)
+          return true
+        }
+      )
+      assert.equal(handled, 0, 'not one message may be processed under a silent degrade')
+      assert.equal(hits.length, 1, 'the loop stops instead of draining the backlog')
+    })
+  })
+
+  it('leaves a conflation-less response alone when conflation was never requested', async () => {
+    await withQueen([popBody()], popBody(), async (queen) => {
+      const messages = await queen.queue(QUEUE).group(GROUP).pop()
+      assert.equal(messages.length, 1, 'today\'s behaviour is untouched when the flag is off')
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. Declaration conflict (§3.3): the stored policy wins, loudly but once.
+// ---------------------------------------------------------------------------
+
+/** Collect every warning the SDK emits while `run` executes. */
+async function captureWarnings(run) {
+  const warnings = []
+  logger.configure({
+    info() {},
+    warn(entry) { warnings.push(typeof entry === 'string' ? entry : JSON.stringify(entry)) },
+    error() {}
+  })
+  try {
+    await run()
+  } finally {
+    logger.configure(null)
+  }
+  return warnings
+}
+
+describe('conflation — declaration conflict', () => {
+  it('warns exactly once per (queue, group) and keeps delivering messages', async () => {
+    const conflicted = popBody({ conflationConflict: true })
+    await withQueen([conflicted, conflicted, conflicted], conflicted, async (queen, hits) => {
+      const warnings = await captureWarnings(async () => {
+        for (let i = 0; i < 3; i++) {
+          const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+          assert.equal(messages.length, 1, 'a conflict never costs the consumer its messages')
+        }
+      })
+
+      assert.equal(hits.length, 3)
+      const conflictWarnings = warnings.filter(w => w.includes('Conflation.conflict'))
+      assert.equal(
+        conflictWarnings.length,
+        1,
+        `exactly one warning per (queue,group) per process, got: ${JSON.stringify(conflictWarnings)}`
+      )
+      assert.match(conflictWarnings[0], new RegExp(QUEUE))
+      assert.match(conflictWarnings[0], new RegExp(GROUP))
+    })
+  })
+
+  it('warns again for a different group on the same queue', async () => {
+    const conflicted = popBody({ conflationConflict: true })
+    await withQueen([conflicted, conflicted], conflicted, async (queen) => {
+      const warnings = await captureWarnings(async () => {
+        await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+        await queen.queue(QUEUE).group('audit').conflation(true).pop()
+      })
+
+      const conflictWarnings = warnings.filter(w => w.includes('Conflation.conflict'))
+      assert.equal(conflictWarnings.length, 2, 'the warn-once key is (queue, group), not queue')
+    })
+  })
+
+  it('a conflict is never a degrade error — the broker plainly understood the flag', async () => {
+    const conflicted = popBody({ conflationConflict: true })
+    await withQueen([conflicted], conflicted, async (queen) => {
+      const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+      assert.equal(messages.length, 1)
+    })
+  })
+
+  it('an EMPTY conflicting pop is answered 200-with-body and must not raise', async () => {
+    // The steady state of a disagreeing consumer, and the case the SDK cannot
+    // rescue on its own: this is a consumer's FIRST poll of an idle queue, so
+    // the knownConflicts memo below is empty and only the response can say what
+    // is going on. The broker keeps the 200 whenever the answer has anything to
+    // say about conflation (`pop_status`); if it ever regressed to a bodiless
+    // 204 here, every conflicting consumer would exit on its first poll.
+    const emptyConflict = ok({ messages: [], partitionsClaimed: 0, conflationConflict: true })
+    await withQueen([emptyConflict], emptyConflict, async (queen, hits) => {
+      const warnings = await captureWarnings(async () => {
+        const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+        assert.equal(messages.length, 0)
+      })
+      assert.equal(hits.length, 1)
+      assert.equal(warnings.filter(w => w.includes('Conflation.conflict')).length, 1)
+    })
+  })
+
+  it('pop maintenance is not a version skew', async () => {
+    // `{"messages":[],"paused":true}` means an operator turned pops off. The
+    // request never reached the claim path, so there is no echo to expect —
+    // raising here would stop every conflating consumer in the fleet on a
+    // routine operator action.
+    const paused = ok({ messages: [], paused: true })
+    await withQueen([paused], paused, async (queen) => {
+      const messages = await queen.queue(QUEUE).group(GROUP).conflation(true).pop()
+      assert.equal(messages.length, 0)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 4. The streams runtime pops through the same QueueBuilder — so the option has
+//    to be threaded there too, or `run({ conflation: true })` is a no-op.
+// ---------------------------------------------------------------------------
+
+/** A QueueBuilder-shaped source 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() { calls.push(['pop']); return [] }
+  }
+  return qb
+}
+
+function runnerWith(opts, calls) {
+  return new Runner({
+    url: 'http://127.0.0.1:1',
+    queryId: 'test-conflation-query',
+    stream: { source: recordingSource(calls), stages: {}, config_hash: 'hash' },
+    ...opts
+  })
+}
+
+describe('conflation — streams runtime', () => {
+  it('Stream.run({ conflation: true }) declares it on the source pop', async () => {
+    const calls = []
+    await runnerWith({ conflation: true }, calls)._popMessages()
+    assert.deepEqual(calls.filter(c => c[0] === 'conflation'), [['conflation', true]])
+  })
+
+  it('leaves the source pop untouched when the option is absent', async () => {
+    const calls = []
+    await runnerWith({}, calls)._popMessages()
+    assert.deepEqual(calls.filter(c => c[0] === 'conflation'), [])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 5. Depth: the new fields must survive the admin call (§2.5/§5.3).
+// ---------------------------------------------------------------------------
+
+describe('conflation — queue depth', () => {
+  it('getQueueDepth surfaces partitionsPending / conflation / effectivePending', async () => {
+    const depth = ok({
+      queue: QUEUE,
+      group: GROUP,
+      pending: 4000000,
+      partitionsPending: 12,
+      conflation: true,
+      effectivePending: 12,
+      partitions: [{ partition: 'a', pending: 333333 }]
+    })
+    await withQueen([depth], depth, async (queen, hits) => {
+      const got = await queen.admin.getQueueDepth(QUEUE, GROUP)
+
+      assert.equal(path(hits[0].url), `/api/v1/resources/queues/${QUEUE}/depth`)
+      assert.equal(query(hits[0].url).get('group'), GROUP)
+      // Log depth vs work depth: 4M positions to retire, 12 handler calls owed.
+      assert.equal(got.pending, 4000000)
+      assert.equal(got.partitionsPending, 12)
+      assert.equal(got.conflation, true)
+      assert.equal(got.effectivePending, 12)
+    })
+  })
+})

package/test-v2/ephemeral-unit/_planServer.js

@@ -0,0 +1,73 @@
+/**
+ * The scripted plan server, plus the ephemeral envelopes these tests answer
+ * with.
+ *
+ * The server itself is kv-unit's -- a real node:http socket driven by a canned
+ * list of responses, recording method, url, raw bytes and parsed body for every
+ * request. It is IMPORTED rather than copied for the same reason
+ * conflation-unit imports it: two plan servers would drift, and the day one of
+ * them stops recording `raw` is the day a byte-identity pin silently becomes a
+ * shape check.
+ *
+ * What is local here is the vocabulary: the ephemeral routes have their own
+ * envelopes (§3.1), and a test that spells `{queue, messages}` out by hand at
+ * every call site hides the wire behind its own noise.
+ */
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer, ok } from '../kv-unit/_planServer.js'
+
+export { withPlanServer, ok }
+
+/** `POST /api/v1/ephemeral/push` -> 201 `{pushed}` (all-or-nothing per request). */
+export function pushed(count) {
+  return { status: 201, body: { pushed: count } }
+}
+
+/** `GET /api/v1/ephemeral/pop` -> 200 `{queue, messages}`; empty array on timeout. */
+export function popped(queue, messages = []) {
+  return ok({ queue, messages })
+}
+
+/** One delivered frame, shaped like a real ephemeral pop element (§3.1). */
+export function frame(n = 1, extra = {}) {
+  return { id: `e:beef:Default:${n}`, partition: 'Default', payload: { n }, attempts: 0, ...extra }
+}
+
+/** `POST /api/v1/ephemeral/ack` -> 200 `{results:[{id, outcome}]}`. */
+export function acked(...results) {
+  return ok({ results })
+}
+
+/**
+ * What a broker or proxy older than 1.1 answers on every route of this family:
+ * the broker because the routes do not exist, the proxy because an unknown API
+ * path is `route_blocked` and fails closed.
+ */
+export const OLD_BROKER = { status: 404, body: { error: 'not_found' } }
+export const OLD_PROXY = { status: 404, body: { error: 'route_blocked', code: 'route_blocked' } }
+
+/**
+ * The OTHER 404, and the reason the mapping has to read the body: a broker that
+ * fully supports the family, answering `depth` about a queue that is not there.
+ */
+export const QUEUE_NOT_FOUND = {
+  status: 404,
+  body: { error: 'ephemeral queue not found', code: 'ephemeral_queue_not_found' }
+}
+
+/**
+ * Run `fn(ephemeral, hits, queen)` against a plan server, closing the client
+ * afterwards. `handleSignals:false` because a test process must not have its
+ * SIGINT handler replaced by every client it builds.
+ */
+export async function withEphemeral(plan, run, clientOptions = {}) {
+  await withPlanServer(plan, ok({ ok: true }), async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, ...clientOptions })
+    try {
+      await run(queen.ephemeral, hits, queen)
+    } finally {
+      await queen.close()
+    }
+  })
+}