queen-mq 1.3.0 → 2.0.0

package/test-v2/http-unit/pushStatus.test.js

@@ -0,0 +1,142 @@
+/**
+ * Push per-item statuses.
+ *
+ * POST /api/v1/push answers 201 with one result per item, in input order, and
+ * a refused item fails INSIDE a successful request, so the per-item status is
+ * the only signal that a message was not stored. The statuses brokers send:
+ *
+ *   queued     stored                                            (every broker)
+ *   duplicate  its transactionId is already stored               (every broker)
+ *   error      refused, no per-item message                      (2.x)
+ *   failed     refused, with `error`                             (1.x)
+ *   buffered   written to the broker's failover file, replayed   (1.x)
+ *
+ * The client used to look for `failed` only, so a 2.x refusal (`error`) was
+ * neither reported nor thrown: push() resolved as if the message were stored.
+ * Found 2026-10-02 against 2.0.0-beta.6, which answers `error` when a
+ * partition's planned append exceeds QUEEN_RAFT_ENTRY_MAX_BYTES.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer } from '../kv-unit/_planServer.js'
+
+const QUEUE = 'test-push-status'
+
+const item = (index, status, extra = {}) => ({
+  index,
+  message_id: `0199aaaa-0000-7000-8000-00000000000${index}`,
+  transaction_id: `tx-${index}`,
+  queueName: QUEUE,
+  status,
+  ...extra
+})
+
+// The exact shape 2.0.0-beta.6 answered for an item it refused (no offset,
+// no error text).
+const created = (results) => ({ status: 201, body: results })
+
+async function withQueen(response, run) {
+  await withPlanServer([response], response, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('push — a refused item is reported, whatever the broker calls it', () => {
+  it('a 2.x `error` item makes push() reject, carrying the per-item results', async () => {
+    await withQueen(created([item(0, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => {
+          assert.match(err.message, /rejected by the broker/)
+          assert.match(err.message, /"error"/, 'the status the broker answered is named')
+          assert.deepEqual(err.results.map(r => r.status), ['error'])
+          return true
+        }
+      )
+    })
+  })
+
+  it('a 2.x `error` item goes to onError, and the stored ones still go to onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 0 }), item(1, 'error')]), async (queen) => {
+      let failedItems = null
+      let failure = null
+      let succeeded = null
+      const res = await queen.queue(QUEUE)
+        .push([{ data: { n: 1 } }, { data: { n: 2 } }])
+        .onError(async (items, err) => { failedItems = items; failure = err })
+        .onSuccess(async (items) => { succeeded = items })
+
+      assert.ok(Array.isArray(res), 'with onError the call resolves with the broker results')
+      assert.equal(failedItems.length, 1)
+      assert.deepEqual(failedItems[0].payload, { n: 2 })
+      assert.equal(failedItems[0].result.status, 'error')
+      assert.match(failure.message, /rejected by the broker/)
+      assert.equal(succeeded.length, 1)
+      assert.deepEqual(succeeded[0].payload, { n: 1 })
+    })
+  })
+
+  it('a 1.x `failed` item is reported with the broker\'s own text', async () => {
+    await withQueen(created([item(0, 'failed', { error: 'File buffer write failed' })]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.equal(err.message, 'File buffer write failed'); return true }
+      )
+    })
+  })
+
+  it('a status this client does not know is a failure, not a silent success', async () => {
+    await withQueen(created([item(0, 'refused-by-something-new')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: { n: 1 } }]) },
+        (err) => { assert.match(err.message, /refused-by-something-new/); return true }
+      )
+    })
+  })
+
+  it('several refused items: one error for the call, counting them', async () => {
+    await withQueen(created([item(0, 'error'), item(1, 'queued', { offset: 0 }), item(2, 'error')]), async (queen) => {
+      await assert.rejects(
+        async () => { await queen.queue(QUEUE).push([{ data: 1 }, { data: 2 }, { data: 3 }]) },
+        (err) => { assert.match(err.message, /^2 of 3 pushed items rejected/); return true }
+      )
+    })
+  })
+})
+
+describe('push — accepted statuses stay accepted', () => {
+  it('`queued` resolves with the broker results and reaches onSuccess', async () => {
+    await withQueen(created([item(0, 'queued', { offset: 7 })]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'queued')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('a 1.x `buffered` item is accepted: the broker owns its delivery', async () => {
+    await withQueen(created([item(0, 'buffered')]), async (queen) => {
+      let succeeded = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onSuccess(async (items) => { succeeded = items })
+      assert.equal(res[0].status, 'buffered')
+      assert.equal(succeeded.length, 1)
+    })
+  })
+
+  it('`duplicate` goes to onDuplicate and is not a failure', async () => {
+    await withQueen(created([item(0, 'duplicate', { offset: 3 })]), async (queen) => {
+      let dups = null
+      const res = await queen.queue(QUEUE).push([{ data: { n: 1 } }]).onDuplicate(async (items) => { dups = items })
+      assert.equal(res[0].status, 'duplicate')
+      assert.equal(dups.length, 1)
+    })
+  })
+})

package/test-v2/http-unit/renew.test.js

@@ -0,0 +1,96 @@
+/**
+ * Queen.renew() outcome.
+ *
+ * POST /api/v1/lease/:leaseId/extend answers HTTP 200 whether or not anything
+ * was renewed. `success` in the body is the only signal, and the client used
+ * to ignore it: renewing a lease that had expired, or that an ack had already
+ * released, reported `success: true` with `newExpiresAt: null` (found
+ * 2026-10-02 against 2.0.0-beta.6). The bodies below are what brokers send:
+ *
+ *   1.x and 2.x: {leaseId, success, renewed, newExpiresAt, expiresAt, lease_expires_at}
+ *   C++:         [{index, leaseId, success, error, expiresAt}]
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer } from '../kv-unit/_planServer.js'
+
+const LEASE = '01a0fcf2-1a28-7001-8810-d74deda1fd42'
+const EXPIRES = '2026-10-02T14:09:40.273Z'
+
+// What 2.0.0-beta.6 answered for a live lease covering two partitions, and
+// for a lease that no longer exists.
+const renewed = (leaseId = LEASE) => ({
+  leaseId, success: true, renewed: 2, newExpiresAt: EXPIRES, expiresAt: EXPIRES, lease_expires_at: EXPIRES
+})
+const notRenewed = (leaseId = LEASE) => ({
+  leaseId, success: false, renewed: 0, newExpiresAt: null, expiresAt: null, lease_expires_at: null
+})
+
+async function withQueen(plan, run) {
+  await withPlanServer(plan, { status: 200, body: renewed() }, async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false, retryAttempts: 1 })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+describe('Queen.renew — the broker\'s verdict, not the HTTP status', () => {
+  it('a renewed lease reports success, its new expiry, and how many partitions it covers', async () => {
+    await withQueen([{ body: renewed() }], async (queen, hits) => {
+      const res = await queen.renew(LEASE)
+      assert.deepEqual(res, { leaseId: LEASE, success: true, newExpiresAt: EXPIRES, renewed: 2 })
+      assert.equal(hits[0].url, `/api/v1/lease/${LEASE}/extend`)
+    })
+  })
+
+  it('a lease that is gone reports failure, with a reason', async () => {
+    await withQueen([{ body: notRenewed() }], async (queen) => {
+      const res = await queen.renew({ leaseId: LEASE, transactionId: 'tx-1' })
+      assert.equal(res.success, false)
+      assert.equal(res.renewed, 0)
+      assert.equal(res.newExpiresAt, null)
+      assert.match(res.error, /not renewed/)
+    })
+  })
+
+  it('an array of messages answers one outcome per distinct lease', async () => {
+    const other = '01a0fcf2-0000-7000-8000-000000000000'
+    await withQueen([{ body: renewed() }, { body: notRenewed(other) }], async (queen, hits) => {
+      const res = await queen.renew([
+        { leaseId: LEASE, transactionId: 'tx-1' },
+        { leaseId: LEASE, transactionId: 'tx-2' },
+        { leaseId: other, transactionId: 'tx-3' }
+      ])
+      assert.equal(hits.length, 2, 'one call per lease, not per message')
+      assert.deepEqual(res.map(r => [r.leaseId, r.success]), [[LEASE, true], [other, false]])
+    })
+  })
+
+  it('reads the C++ broker\'s array, including its error text', async () => {
+    await withQueen([
+      { body: [{ index: 0, leaseId: LEASE, success: true, error: null, expiresAt: EXPIRES }] },
+      { body: [{ index: 0, leaseId: LEASE, success: false, error: 'Lease already expired', expiresAt: null }] }
+    ], async (queen) => {
+      const ok = await queen.renew(LEASE)
+      assert.equal(ok.success, true)
+      assert.equal(ok.newExpiresAt, EXPIRES)
+      const gone = await queen.renew(LEASE)
+      assert.equal(gone.success, false)
+      assert.equal(gone.error, 'Lease already expired')
+    })
+  })
+
+  it('an HTTP failure is still a failed renewal, not a throw', async () => {
+    await withQueen([{ status: 500, body: { error: 'boom' } }], async (queen) => {
+      const res = await queen.renew(LEASE)
+      assert.equal(res.success, false)
+      assert.ok(res.error)
+    })
+  })
+})

package/test-v2/kv-unit/timerWire.test.js

@@ -10,7 +10,7 @@
  *      a tenant that is over quota -- while the fire never stops by itself, so
  *      that tenant keeps producing messages it cannot stop.
  *   2. delayMs, never delaySeconds and never an absolute instant (§4.2,
- *      §20.6). One clock, Postgres's. `deliverAt` in an op is a 22023.
+ *      §20.6). One clock, the broker's. `deliverAt` in an op is a 22023.
  *   3. The payload is base64 (§6.2), and the SDK encodes it, so a caller never
  *      has to know.
  *   4. `txn` is mandatory on a schedule and is echoed on `absent`, which is

package/test-v2/kv-unit/txnWire.test.js

@@ -181,11 +181,19 @@ describe('Transaction wire — the verdict that must not throw', () => {
   })
 
   it('commit() still THROWS on every other failure', async () => {
-    const rejected = ok({ transactionId: 'txn-1', success: false, reason: 'ack_rejected', error: 'QTXN invalid or expired lease', results: [] })
+    // The body a 2.0 broker answers for an ack whose lease is gone (a 1.x
+    // broker spelled the reason ack_rejected).
+    const rejected = ok({
+      transactionId: 'txn-1',
+      success: false,
+      reason: 'rejected_ack',
+      error: 'QTXN 1 acked message(s) on partition 3 are not leased by this worker or were already acked; the transaction rolled back',
+      results: []
+    })
     await withQueen([rejected], async (queen) => {
       await assert.rejects(() => queen.transaction().ack(MSG).commit(), (e) => {
         assert.match(e.message, /QTXN/)
-        assert.equal(e.reason, 'ack_rejected', 'the closed-taxonomy reason travels on the error, so nobody matches the message')
+        assert.equal(e.reason, 'rejected_ack', 'the broker\'s reason travels on the error, so nobody matches the message')
         return true
       })
     })
@@ -220,3 +228,94 @@ describe('Transaction wire — the verdict that must not throw', () => {
     })
   })
 })
+
+// ---------------------------------------------------------------------------
+// The consumer group of an ack op. The lease an ack has to match belongs to
+// the group the message was popped under, and an op that names no group is
+// judged in queue mode: a message popped by a group and acked without one
+// rolled the whole bundle back with `rejected_ack` (found 2026-10-02 against
+// 2.0.0-beta.6). Every pop answers each message with its `consumerGroup`.
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — the ack op carries the group the message was popped under', () => {
+  const fromGroup = (group, n = 1) => ({
+    ...MSG,
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    consumerGroup: group
+  })
+
+  it('takes consumerGroup from the message when the caller names none', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers')).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'workers')
+    })
+  })
+
+  it('a queue-mode message adds no consumerGroup key, as before', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('__QUEUE_MODE__')).commit()
+      await queen.transaction().ack(MSG).commit()   // hand-built, no group at all
+      for (const hit of hits) {
+        assert.deepEqual(Object.keys(hit.body.operations[0]).sort(), ['leaseId', 'partitionId', 'status', 'transactionId', 'type'])
+      }
+    })
+  })
+
+  it('an explicit group wins, as { consumerGroup } or as { group }', async () => {
+    await withQueen([success(), success()], async (queen, hits) => {
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { consumerGroup: 'auditors' }).commit()
+      await queen.transaction().ack(fromGroup('workers'), 'completed', { group: 'auditors' }).commit()
+      assert.equal(hits[0].body.operations[0].consumerGroup, 'auditors')
+      assert.equal(hits[1].body.operations[0].consumerGroup, 'auditors')
+    })
+  })
+
+  it('messages from different groups each keep their own', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([fromGroup('a', 1), fromGroup('b', 2)]).commit()
+      assert.deepEqual(hits[0].body.operations.map(op => op.consumerGroup), ['a', 'b'])
+    })
+  })
+})
+
+// The lease of an ack op. A Queen 2 broker fences each ack with the leaseId
+// the operation carries, and lends it one from requiredLeases only when every
+// lease in the bundle is the same lease. An ack whose lease travelled in
+// requiredLeases alone was applied unfenced in a bundle of two leases, even
+// after that lease expired and another consumer took the message (found
+// 2026-10-03 against 2.0.0-beta.6).
+// ---------------------------------------------------------------------------
+
+describe('Transaction wire — each ack op carries its own lease', () => {
+  const leased = (n, leaseId) => ({
+    transactionId: `aaaaaaaa-aaaa-7aaa-8aaa-00000000000${n}`,
+    partitionId: `pppppppp-pppp-7ppp-8ppp-00000000000${n}`,
+    ...(leaseId === undefined ? {} : { leaseId })
+  })
+
+  it('a bundle spanning two leases names each lease on its own ack', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(leased(1, 'lease-1'))
+        .ack(leased(2, 'lease-2'))
+        .ack(leased(3))
+        .commit()
+
+      const [first, second, third] = hits[0].body.operations
+      assert.equal(first.leaseId, 'lease-1')
+      assert.equal(second.leaseId, 'lease-2')
+      assert.ok(!('leaseId' in third), 'a message without a lease adds no leaseId key')
+      assert.deepEqual(hits[0].body.requiredLeases, ['lease-1', 'lease-2'])
+    })
+  })
+
+  it('a null or empty lease adds no leaseId key either', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack([leased(1, null), leased(2, '')]).commit()
+      for (const op of hits[0].body.operations) {
+        assert.ok(!('leaseId' in op))
+      }
+      assert.deepEqual(hits[0].body.requiredLeases, [])
+    })
+  })
+})

package/test-v2/kv.js

@@ -1,15 +1,16 @@
 /**
  * KV integration suite (PLAN_KV_TIMERS.md §5, §8.3).
  *
- * Every test here is repeatable ONLY because run.js purges `queen.kv` for the
- * `test-%` namespaces before the run (§10.4): without that purge a
+ * Every test here is repeatable ONLY because every run starts on a fresh broker
+ * (test/run.sh creates the lane's data volume empty and destroys it with
+ * `down -v`): against a broker that kept the previous run's keys, a
  * `putIfAbsent` test is green on its first execution and red forever after,
- * and an `incr` test accumulates between runs. If you add a test here, its
- * namespace must start with `test-` or it will be the one that rots.
+ * and an `incr` test accumulates between runs. Keep the namespaces under
+ * `test-`, like every other fixture of the suite.
  *
  * And `forever` is BANNED in this file. A test that goes wrong with a TTL
  * leaves state that expires by itself; a test that goes wrong with `forever`
- * leaves immortal state in a shared database.
+ * leaves immortal state in a shared broker.
  */
 
 import { KV_NS, sleep } from './_kvtimers.js'

package/test-v2/pop.js

@@ -226,11 +226,14 @@ export async function popV4DefaultOne(client) {
 
     await new Promise(r => setTimeout(r, 500))
 
-    // No .partitions() → max_partitions defaults to 1 → single partition.
+    // No .partitions() and autopilot off → the pre-1.2 default of one
+    // partition. (With autopilot on, the SDK default, an unset width is the
+    // broker's to pick: one consumer and four ready partitions take all four.)
     const res = await client
     .queue(queueName)
     .batch(100)
     .wait(false)
+    .autopilot(false)
     .pop()
 
     if (res.length !== 5) {
@@ -334,3 +337,27 @@ export async function popV4SharedLeaseRenew(client) {
     return { success: true, message: 'Shared leaseId renewed once and dedup confirmed' }
 }
 
+
+// renew() reports the broker's verdict (2026-10-02, 2.0.0-beta.6): the extend
+// route answers HTTP 200 whether or not anything was renewed, and a lease an
+// ack had already released came back success:true.
+export async function renewReportsAReleasedLease(client) {
+    const queueName = 'test-queue-v2-renew-released'
+    const queue = await client.queue(queueName).config({ leaseTime: 60 }).create()
+    if (!queue.configured) {
+        return { success: false, message: 'Queue not created' }
+    }
+    await client.queue(queueName).push([{ data: { n: 1 } }])
+
+    const [message] = await client.queue(queueName).batch(1).wait(false).pop()
+    if (!message) {
+        return { success: false, message: 'Nothing popped' }
+    }
+    const live = await client.renew(message)
+    await client.ack(message, true)
+    const released = await client.renew(message)
+
+    const success = live.success === true && typeof live.newExpiresAt === 'string' &&
+                    released.success === false && released.newExpiresAt === null && typeof released.error === 'string'
+    return { success, message: `live lease: ${JSON.stringify(live)}; after the ack: ${JSON.stringify(released)}` }
+}

package/test-v2/run.js

@@ -1,4 +1,3 @@
-import pg from 'pg';
 import { Queen } from '../client-v2/index.js'
 import * as queueTests from './queue.js'
 import * as pushTests from './push.js'
@@ -9,7 +8,6 @@ import * as dlqTests from './dlq.js'
 import * as completeTests from './complete.js'
 import * as transactionTests from './transaction.js'
 import * as subscriptionTests from './subscription.js'
-import * as maintenanceTests from './maintenance.js'
 import * as retentionTests from './retention.js'
 import * as bootstrapTests from './bootstrap.js'
 import * as loggerTests from './logger.js'
@@ -28,46 +26,43 @@ import { LoadBalancer } from '../client-v2/http/LoadBalancer.js';
 
 export const TEST_CONFIG_SINGLE = {
     baseUrls: [process.env.QUEEN_SERVER_URL || 'http://localhost:6632'],
-    loadBalancingStrategy: 'affinity',
-    dbConfig: {
-      host: process.env.PG_HOST || 'localhost',
-      port: process.env.PG_PORT || 5432,
-      database: process.env.PG_DB || 'postgres',
-      user: process.env.PG_USER || 'postgres',
-      password: process.env.PG_PASSWORD || 'postgres'
-    }
+    loadBalancingStrategy: 'affinity'
   };
 
 export const TEST_CONFIG_MULTIPLE = {
   baseUrls: ['http://localhost:6632','http://localhost:6633'],
-  loadBalancingStrategy: 'round-robin',
-  dbConfig: {
-    host: process.env.PG_HOST || 'localhost',
-    port: process.env.PG_PORT || 5432,
-    database: process.env.PG_DB || 'postgres',
-    user: process.env.PG_USER || 'postgres',
-    password: process.env.PG_PASSWORD || 'postgres'
-  }
+  loadBalancingStrategy: 'round-robin'
 };
 
 export const TEST_CONFIG = process.env.TEST_CONFIG === 'multiple' ? TEST_CONFIG_MULTIPLE : TEST_CONFIG_SINGLE;
 console.log('TEST_CONFIG:', TEST_CONFIG);
 
 // Global test state
-export let dbPool;  
-
-// Initialize database pool
-export async function initDb() {
-  dbPool = new pg.Pool(TEST_CONFIG.dbConfig);
-  await dbPool.query('SELECT 1');
-  return dbPool;
-}
-
-// Close database pool
-export async function closeDb() {
-  if (dbPool) {
-    await dbPool.end();
-  }
+let activeClient;
+
+// The suite talks to the broker through its public HTTP API only: there is no
+// database and no cleanup step. test/run.sh gives every lane a FRESH broker
+// (its data volume is created empty and destroyed with `down -v`), so the
+// suite starts on an empty store. A second run against the same broker is not
+// expected to be green: fixed-name fixtures (docs.js's fixed transactionId,
+// the kv and timer suites) would find the first run's state.
+//
+// The preflight makes a missing or unhealthy broker fail the run up front,
+// with the reason, instead of as a wall of per-test connection errors.
+async function preflightBroker(baseUrl) {
+    const url = `${baseUrl}/health`
+    let res
+    try {
+        res = await fetch(url, { signal: AbortSignal.timeout(5000) })
+    } catch (e) {
+        throw new Error(`broker preflight ${url}: ${e.cause?.message || e.message}`)
+    }
+    // Drain the body so the connection is released either way.
+    await res.arrayBuffer().catch(() => {})
+    if (!res.ok) {
+        throw new Error(`broker preflight ${url}: HTTP ${res.status}`)
+    }
+    log(true, `Broker preflight ${url}: HTTP ${res.status}`)
 }
 
 function log (success, ...args) {
@@ -92,78 +87,13 @@ function printResults() {
     console.log('='.repeat(80))
 }
 
-export const cleanupTestData = async () => {
-    // All the LIKE patterns test queues use. The three exact names are the
-    // documentation queues (test-v2/docs.js): purging them here is what lets
-    // the published dedup snippet keep a fixed transactionId across runs.
-    const patterns = ['test-%', 'edge-%', 'pattern-%', 'workflow-%', 'orders', 'payments', 'invoices'];
-    try {
-      // Drop streaming queries first (CASCADE removes their state rows).
-      // Safe even when queen_streams isn't installed yet — we swallow the
-      // error if the schema doesn't exist.
-      try {
-        await dbPool.query(`DELETE FROM queen_streams.queries WHERE name LIKE 'test-%'`);
-      } catch (e) {
-        // queen_streams schema not installed — ignore.
-      }
-
-      // Queue identity is now the queen.queues id (log_queues was merged
-      // away): log_partitions, consumer_watermarks, consumer_groups_metadata
-      // and queue_lag_metrics all cascade from the queues row. Only log_txns
-      // and log_dlq have NO foreign key by design, so they get an explicit
-      // purge keyed via log_partitions first. Without it, every suite run
-      // inherits the previous run's messages and dedup window entries —
-      // fixed-transactionId tests report 'duplicate' on their FIRST push.
-      try {
-        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 LIKE ANY($1::text[])
-          ),
-          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`, [patterns]);
-      } catch (e) {
-        // Log-engine schema not installed (rows-only server) — ignore.
-      }
-
-      await dbPool.query(`DELETE FROM queen.queues WHERE name LIKE ANY($1::text[])`, [patterns]);
-
-      // KV keys and pending timers (PLAN_KV_TIMERS.md §10.4). NOT cosmetic:
-      // without this purge a putIfAbsent test is green on its first run and red
-      // forever after, an incr test accumulates between runs, and a timer left
-      // pending by an earlier run fires into a later one and shows up as a
-      // phantom message in an unrelated test. Neither table has a foreign key
-      // to queen.queues -- log_timers is keyed by NAMES on purpose -- so the
-      // queue delete above does not reach them.
-      //
-      // Both are deleted across every tenant: a test rig may run with
-      // QUEEN_TENANCY_HEADER on, and the rows to purge are identified by the
-      // test naming convention, never by tenant.
-      //
-      // These two used to be wrapped in a swallowing try/catch, on the grounds
-      // that a broker booted with the kv/timer flags off had never applied
-      // 024_kv.sql / 025_timers.sql. There are no such flags: schema.rs applies
-      // both on every boot, so a missing `queen.kv` or `queen.log_timers` is a
-      // broken rig and must be loud. Swallowing it would leave the purge silently
-      // undone, which is exactly the failure the purge exists to prevent -- a
-      // putIfAbsent test green on its first run and red forever after.
-      await dbPool.query(`DELETE FROM queen.kv WHERE namespace LIKE ANY($1::text[])`, [patterns]);
-      await dbPool.query(`DELETE FROM queen.log_timers WHERE queue LIKE ANY($1::text[])`, [patterns]);
-
-      log(true, 'Test data cleaned up (rows + segments + kv + timers)');
-    } catch (error) {
-      log(false, `Cleanup error: ${error.message}`);
-    }
-  };
-
 async function main() {
     const client = new Queen({
         urls: TEST_CONFIG.baseUrls,
         loadBalancingStrategy: TEST_CONFIG.loadBalancingStrategy
     })
-    await initDb()
+    activeClient = client
+    await preflightBroker(TEST_CONFIG.baseUrls[0])
 
     // Separate human and AI tests
     const humanTests = [
@@ -177,7 +107,6 @@ async function main() {
         transactionTests,
         subscriptionTests,
         retentionTests,
-        maintenanceTests,
         bootstrapTests,
         loggerTests,
         watermarkTests,
@@ -194,7 +123,7 @@ async function main() {
     ]
 
     // Streaming tests (queen-streams). Run via `node run.js stream`.
-    // Require Queen v0.2+ with the queen_streams schema applied.
+    // Require a broker that serves the /streams/v1 routes.
     const streamGroupTests = [streamTests]
 
     const allTests = [...humanTests, ...aiTests, ...streamGroupTests]
@@ -240,8 +169,7 @@ async function main() {
             humanTestFunctions.forEach(t => console.log(`  - ${t.name}`))
             console.log('\n🌊 queen-streams tests:')
             streamTestFunctions.forEach(t => console.log(`  - ${t.name}`))
-            await closeDb()
-            process.exit(1)
+            return 1
         }
         testsToRun = [testFunc]
         mode = 'single'
@@ -250,9 +178,6 @@ async function main() {
         log(true, `Running all tests (${allTestFunctions.length} tests)...`)
     }
 
-    // Cleanup test data
-    await cleanupTestData()
-    
     for (const test of testsToRun) {
         try {
             console.log('Running test:', test.name)
@@ -279,17 +204,28 @@ async function main() {
         console.log('\n💡 Tip: Run "node run.js" to test all tests')
     }
     
-    //await cleanupTestData()
-    await closeDb()
-    // Queen.close() destroys the per-client HTTP agent, releasing keep-alive
-    // sockets so the loop can drain; the explicit exit code is for CI.
-    await client.close()
     const failedCount = testResults.filter(x => !x.success).length
-    process.exit(failedCount > 0 ? 1 : 0)
+    return failedCount > 0 ? 1 : 0
 }
 
+let exitCode = 1
 try {
-    await main()
+    exitCode = await main()
 } catch (error) {
     log(false, 'Main error:', error.message)
-}
+} finally {
+    // Always release the client. Previously, an init failure skipped this
+    // teardown and the outer catch returned a successful process status,
+    // allowing a broken integration lane to appear green.
+    const cleanupResults = await Promise.allSettled([
+        activeClient ? activeClient.close() : Promise.resolve()
+    ])
+    for (const result of cleanupResults) {
+        if (result.status === 'rejected') {
+            exitCode = 1
+            log(false, 'Cleanup error:', result.reason?.message || String(result.reason))
+        }
+    }
+}
+
+process.exit(exitCode)