queen-mq 1.0.0 → 1.0.3

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

@@ -0,0 +1,222 @@
+/**
+ * Transaction wire contract for the kv and timers riders
+ * (PLAN_KV_TIMERS.md §6.3, §8.2, §8.3, §10.4).
+ *
+ * THE ONE SHAPE RULE, AND WHY IT IS NOT NEGOTIABLE. `kv` and `timers` are
+ * TOP-LEVEL fields of the request body, beside `operations` and never inside
+ * it. The reason is a silent failure in another language that this client's
+ * shape has to respect anyway, because the broker parses one wire for all
+ * seven: two Go struct fields carrying the same JSON key at the same level are
+ * BOTH DROPPED by encoding/json, with no error. A bundle would go out with
+ * zero kv ops, the broker would commit a transaction with no gate, and the
+ * putIfAbsent the bundle existed for would simply never have happened.
+ *
+ * BYTE-IDENTITY WHEN THE RIDERS ARE ABSENT. A transaction that carries neither
+ * array must produce exactly today's body -- no `kv: []`, no `timers: null`.
+ * Anything else is a wire change for every broker that has not been upgraded.
+ *
+ * AND THE ONE BEHAVIOUR CHANGE THIS FEATURE FORCES ON `commit()`: a lost
+ * `required` precondition RETURNS `{success:false, reason:'kv_precondition'}`,
+ * it does not throw. It is the expected outcome of every legitimate
+ * redelivery -- the idempotency marker doing its job -- and a throw would put
+ * the single most frequent outcome of the product inside every caller's
+ * catch-and-retry. Everything else that fails still throws.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Queen } from '../../client-v2/index.js'
+import { withPlanServer, ok } from './_planServer.js'
+
+const NS = 'test-txn-ns'
+const QUEUE = 'test-txn-q'
+
+const MSG = { transactionId: 'aaaaaaaa-aaaa-7aaa-8aaa-aaaaaaaaaaaa', partitionId: 'pppppppp-pppp-7ppp-8ppp-pppppppppppp', leaseId: 'llllllll-llll-7lll-8lll-llllllllllll' }
+
+const success = (results = []) => ok({ transactionId: 'txn-1', success: true, results })
+
+async function withQueen(plan, run) {
+  await withPlanServer(plan, success(), async (url, hits) => {
+    const queen = new Queen({ url, handleSignals: false })
+    try {
+      await run(queen, hits)
+    } finally {
+      await queen.close()
+    }
+  })
+}
+
+const b64 = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64')
+
+describe('Transaction wire — where the riders live', () => {
+  it('a bundle with no riders is byte-for-byte what it is today', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack(MSG).commit()
+      assert.deepEqual(Object.keys(hits[0].body).sort(), ['operations', 'requiredLeases'],
+        'no kv:[] and no timers:null — a bundle without riders must not change shape')
+    })
+  })
+
+  it('kv is a TOP-LEVEL array, never an element of operations', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(MSG)
+        .kv.putIfAbsent(NS, 'marker', true, { ttlSeconds: 3600 })
+        .commit()
+
+      const body = hits[0].body
+      assert.ok(Array.isArray(body.kv))
+      assert.deepEqual(body.kv, [{ op: 'putIfAbsent', ns: NS, key: 'marker', value: true, ttlSeconds: 3600 }])
+      assert.equal(body.operations.length, 1)
+      assert.equal(body.operations[0].type, 'ack')
+      for (const op of body.operations) {
+        assert.ok(op.type !== 'kv', 'an op typed `kv` inside operations is a named 400 from the broker, by design')
+      }
+    })
+  })
+
+  it('timers is the other top-level array, and carries the same op shape as the route', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(MSG)
+        .timer(QUEUE).key('k').delayMs(60_000).payload({ a: 1 }).txn('tx-9').schedule()
+        .commit()
+
+      assert.deepEqual(hits[0].body.timers, [{
+        op: 'schedule', queue: QUEUE, timerKey: 'k', delayMs: 60000, txn: 'tx-9', payload: b64({ a: 1 })
+      }])
+    })
+  })
+
+  it('a timer cancel inside a bundle is an op in the timers array', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction()
+        .ack(MSG)
+        .timer(QUEUE).key('k').txn('tx-9').cancel()
+        .commit()
+
+      assert.deepEqual(hits[0].body.timers, [{ op: 'cancel', queue: QUEUE, timerKey: 'k', txn: 'tx-9' }])
+    })
+  })
+
+  it('once() is the gate: putIfAbsent with required:true', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().ack(MSG).once(NS, 'order-9f1', { ttlSeconds: 86400 }).commit()
+      assert.deepEqual(hits[0].body.kv, [{
+        op: 'putIfAbsent', ns: NS, key: 'order-9f1', value: true, ttlSeconds: 86400, required: true
+      }])
+    })
+  })
+
+  it('until on a rider is resolved at COMMIT time, not when the op is queued', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      const tx = queen.transaction().ack(MSG).kv.put(NS, 'k', 1, { until: new Date(Date.now() + 60_000) })
+      await new Promise(r => setTimeout(r, 1100))
+      await tx.commit()
+      const sent = hits[0].body.kv[0]
+      assert.ok(!('until' in sent))
+      assert.ok(sent.ttlSeconds <= 59, `a delta computed at build time would still say 60; got ${sent.ttlSeconds}`)
+      assert.ok(sent.ttlSeconds >= 58)
+    })
+  })
+
+  it('getPrefix is refused before the request, with the surface that does allow it named', async () => {
+    await withQueen([], async (queen, hits) => {
+      assert.throws(() => queen.transaction().kv.getPrefix(NS, 'p'), (e) => {
+        assert.match(e.message, /\/api\/v1\/kv/)
+        return true
+      })
+      assert.equal(hits.length, 0)
+    })
+  })
+
+  it('a kv-only bundle is legal and commits without operations', async () => {
+    await withQueen([success()], async (queen, hits) => {
+      await queen.transaction().kv.put(NS, 'k', 1, { ttlSeconds: 60 }).commit()
+      assert.deepEqual(hits[0].body.operations, [])
+      assert.equal(hits[0].body.kv.length, 1)
+    })
+  })
+
+  it('an entirely empty transaction still refuses to commit', async () => {
+    await withQueen([], async (queen, hits) => {
+      await assert.rejects(() => queen.transaction().commit(), (e) => {
+        assert.match(e.message, /no operations/i)
+        return true
+      })
+      assert.equal(hits.length, 0)
+    })
+  })
+})
+
+describe('Transaction wire — the verdict that must not throw', () => {
+  const precondition = ok({
+    transactionId: 'txn-1',
+    success: false,
+    ok: false,
+    reason: 'kv_precondition',
+    error: 'kv_precondition_failed',
+    failedIndex: 1,
+    kvReason: 'exists',
+    version: 90101,
+    value: { owner: 'first-delivery' },
+    results: []
+  })
+
+  it('commit() RETURNS on a lost precondition', async () => {
+    await withQueen([precondition], async (queen) => {
+      const res = await queen.transaction()
+        .ack(MSG)
+        .once(NS, 'order-9f1', { ttlSeconds: 86400 })
+        .commit()
+
+      assert.equal(res.success, false)
+      assert.equal(res.reason, 'kv_precondition')
+      assert.equal(res.failedIndex, 1, 'the index is in the FLAT space of results[]')
+      assert.equal(res.kvReason, 'exists')
+      assert.equal(res.version, 90101)
+      assert.deepEqual(res.value, { owner: 'first-delivery' })
+    })
+  })
+
+  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: [] })
+    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')
+        return true
+      })
+    })
+  })
+
+  it('commit() throws on a duplicate and on a misalignment, with the reason attached', async () => {
+    const dup = ok({ transactionId: 'txn-1', success: false, reason: 'duplicate', error: 'QDUP duplicate transaction', results: [] })
+    const bad = ok({ transactionId: 'txn-1', success: false, reason: 'misaligned', error: 'QTXN rider results missing', results: [] })
+    await withQueen([dup, bad], async (queen) => {
+      await assert.rejects(() => queen.transaction().ack(MSG).commit(), (e) => { assert.equal(e.reason, 'duplicate'); return true })
+      await assert.rejects(() => queen.transaction().ack(MSG).commit(), (e) => { assert.equal(e.reason, 'misaligned'); return true })
+    })
+  })
+
+  it('a committed bundle hands back the flat results, riders included', async () => {
+    const results = [
+      { index: 0, type: 'ack', success: true },
+      { index: 1, type: 'kv', opIndex: 0, op: 'put', applied: true, key: 'k', version: 4 },
+      { index: 2, type: 'timer', opIndex: 0, ok: true, status: 'scheduled', timerKey: 'k' }
+    ]
+    await withQueen([success(results)], async (queen) => {
+      const res = await queen.transaction()
+        .ack(MSG)
+        .kv.put(NS, 'k', 1, { ttlSeconds: 60 })
+        .timer(QUEUE).key('k').delayMs(1).payload({}).txn('t').schedule()
+        .commit()
+
+      assert.equal(res.success, true)
+      assert.equal(res.results[1].type, 'kv')
+      assert.equal(res.results[1].applied, true)
+      assert.equal(res.results[2].status, 'scheduled')
+    })
+  })
+})

package/test-v2/kv.js

@@ -0,0 +1,273 @@
+/**
+ * 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
+ * `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 `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.
+ */
+
+import { KV_NS, sleep } from './_kvtimers.js'
+
+export async function kvPutGetDelete(client) {
+  const key = 'basic/put-get-delete'
+  const written = await client.kv.put(KV_NS, key, { hello: 'world', n: 1 }, { ttl: '10m' })
+  if (written.applied !== true) {
+    return { success: false, message: `put did not apply: ${JSON.stringify(written)}` }
+  }
+
+  const row = await client.kv.get(KV_NS, key)
+  if (row.found !== true || row.value.hello !== 'world' || row.version !== written.version) {
+    return { success: false, message: `get returned ${JSON.stringify(row)}` }
+  }
+  if (!row.expiresAt) {
+    return { success: false, message: 'a key written with a TTL must report expiresAt' }
+  }
+
+  const removed = await client.kv.delete(KV_NS, key)
+  const after = await client.kv.get(KV_NS, key)
+
+  return {
+    success: removed.applied === true && after.found === false,
+    message: 'put, get (row with version and expiresAt), delete, get-miss'
+  }
+}
+
+export async function kvNullIsAValueNotAnAbsence(client) {
+  const key = 'basic/null-value'
+  await client.kv.put(KV_NS, key, null, { ttl: '10m' })
+  const row = await client.kv.get(KV_NS, key)
+
+  return {
+    success: row.found === true && row.value === null,
+    message: row.found === true && row.value === null
+      ? 'a JSON null round-trips as {found:true, value:null}'
+      : `found and value were collapsed: ${JSON.stringify(row)}`
+  }
+}
+
+export async function kvPutIfAbsentIsExactlyOneWinner(client) {
+  const key = 'marker/exactly-once'
+  const first = await client.kv.putIfAbsent(KV_NS, key, { owner: 'first' }, { ttl: '10m' })
+  const second = await client.kv.putIfAbsent(KV_NS, key, { owner: 'second' }, { ttl: '10m' })
+
+  const ok = first.applied === true
+    && second.applied === false
+    && second.reason === 'exists'
+    && second.value && second.value.owner === 'first'
+    && second.version === first.version
+
+  return {
+    success: ok,
+    message: ok
+      ? 'exactly one winner, and the loser is handed the winner value without a second round trip'
+      : `first=${JSON.stringify(first)} second=${JSON.stringify(second)}`
+  }
+}
+
+/**
+ * §5.3's headline repair: `expect: N > 0` on an absent key must be a PURE
+ * UPDATE and create NOTHING. In the naive shape it falls into the INSERT
+ * branch and creates the row -- which in a saga fires the compensating command
+ * that `expect` existed to prevent.
+ */
+export async function kvExpectOnAbsentKeyCreatesNothing(client) {
+  const key = 'fence/absent-key'
+  const res = await client.kv.put(KV_NS, key, { compensate: true }, { ttl: '10m', expect: 90101 })
+  const row = await client.kv.get(KV_NS, key)
+
+  const ok = res.applied === false && res.reason === 'absent' && row.found === false
+  return {
+    success: ok,
+    message: ok
+      ? 'expect:N>0 on an absent key applied nothing and created nothing'
+      : `res=${JSON.stringify(res)} row=${JSON.stringify(row)}`
+  }
+}
+
+export async function kvExpectFencesAStaleWriter(client) {
+  const key = 'fence/stale-writer'
+  const v1 = await client.kv.put(KV_NS, key, { step: 1 }, { ttl: '10m' })
+  const v2 = await client.kv.put(KV_NS, key, { step: 2 }, { ttl: '10m', expect: v1.version })
+  // The stale holder still carries v1's version: its write must lose.
+  const stale = await client.kv.put(KV_NS, key, { step: 'stale' }, { ttl: '10m', expect: v1.version })
+  const row = await client.kv.get(KV_NS, key)
+
+  const ok = v2.applied === true && stale.applied === false && stale.reason === 'version' && row.value.step === 2
+  return {
+    success: ok,
+    message: ok
+      ? 'a fenced write from a stale holder loses with reason "version"'
+      : `v2=${JSON.stringify(v2)} stale=${JSON.stringify(stale)} row=${JSON.stringify(row)}`
+  }
+}
+
+/**
+ * §5.4: with `max`, `applied` IS the admission decision -- and the first call
+ * of a window is guarded too, which is repair 2 (the naive INSERT branch has
+ * no WHERE, so `max:5, delta:10` would admit 10 on the first call and blow the
+ * quota exactly when a limiter is being attacked).
+ */
+export async function kvIncrIsTheAdmissionDecision(client) {
+  const key = 'quota/window'
+  const a = await client.kv.incr(KV_NS, key, 1, { ttl: '10m', max: 2 })
+  const b = await client.kv.incr(KV_NS, key, 1, { ttl: '10m', max: 2 })
+  const c = await client.kv.incr(KV_NS, key, 1, { ttl: '10m', max: 2 })
+
+  const firstCallGuarded = await client.kv.incr(KV_NS, 'quota/first-call', 10, { ttl: '10m', max: 5 })
+
+  const ok = a.applied === true && a.value === 1
+    && b.applied === true && b.value === 2
+    && c.applied === false && c.reason === 'limit' && c.value === 2
+    && firstCallGuarded.applied === false && firstCallGuarded.reason === 'limit'
+
+  return {
+    success: ok,
+    message: ok
+      ? 'incr admits up to max, refuses beyond it without saturating, and guards the first call of the window'
+      : `a=${JSON.stringify(a)} b=${JSON.stringify(b)} c=${JSON.stringify(c)} first=${JSON.stringify(firstCallGuarded)}`
+  }
+}
+
+/**
+ * §5.4, repair 3: an expired non-numeric row must not poison the counter. Left
+ * unrepaired, every request of that customer is refused with `reason:'type'`
+ * until the sweeper prunes -- a reason no client handles as "retry".
+ */
+export async function kvIncrTreatsAnExpiredRowAsZero(client) {
+  const key = 'quota/expired-initializer'
+  await client.kv.put(KV_NS, key, { count: 0 }, { ttlSeconds: 1 })
+  await sleep(1500)
+  const res = await client.kv.incr(KV_NS, key, 1, { ttl: '10m', max: 5 })
+
+  return {
+    success: res.applied === true && res.value === 1,
+    message: res.applied === true
+      ? 'an expired non-numeric row counts as zero and starts a new window'
+      : `incr over an expired row answered ${JSON.stringify(res)}`
+  }
+}
+
+export async function kvGetManyReportsMissingExplicitly(client) {
+  await client.kv.put(KV_NS, 'many/a', 1, { ttl: '10m' })
+  await client.kv.put(KV_NS, 'many/b', 2, { ttl: '10m' })
+  const res = await client.kv.getMany(KV_NS, ['many/a', 'many/b', 'many/nope'])
+
+  const keys = res.rows.map(r => r.key).sort()
+  const ok = keys.length === 2 && keys[0] === 'many/a' && keys[1] === 'many/b'
+    && res.missing.length === 1 && res.missing[0] === 'many/nope'
+
+  return {
+    success: ok,
+    message: ok ? 'getMany returns rows plus an explicit missing list' : JSON.stringify(res)
+  }
+}
+
+export async function kvGetPrefixPagesAndListAllWalksThem(client) {
+  for (const i of [1, 2, 3, 4, 5]) {
+    await client.kv.put(KV_NS, `scan/item-${i}`, { i }, { ttl: '10m' })
+  }
+  // A neighbour that must NOT be caught by the prefix.
+  await client.kv.put(KV_NS, 'scanX/other', { i: 0 }, { ttl: '10m' })
+
+  const page = await client.kv.getPrefix(KV_NS, 'scan/', { limit: 2 })
+  if (page.rows.length !== 2 || page.truncated !== true || !page.nextAfter) {
+    return { success: false, message: `first page: ${JSON.stringify(page)}` }
+  }
+
+  const seen = []
+  for await (const row of client.kv.listAll(KV_NS, 'scan/')) seen.push(row.key)
+
+  const ok = seen.length === 5 && seen.every(k => k.startsWith('scan/'))
+  return {
+    success: ok,
+    message: ok
+      ? 'getPrefix pages on a keyset cursor and listAll walks every page'
+      : `listAll saw ${JSON.stringify(seen)}`
+  }
+}
+
+export async function kvExpiredKeyIsNeverReturned(client) {
+  const key = 'ttl/short'
+  await client.kv.put(KV_NS, key, { v: 1 }, { ttlSeconds: 1 })
+  const alive = await client.kv.get(KV_NS, key)
+  await sleep(1500)
+  const dead = await client.kv.get(KV_NS, key)
+  // And it must not count as existing either, well before the sweeper prunes.
+  const resurrect = await client.kv.putIfAbsent(KV_NS, key, { v: 2 }, { ttl: '10m' })
+
+  const ok = alive.found === true && dead.found === false && resurrect.applied === true
+  return {
+    success: ok,
+    message: ok
+      ? 'an expired key is never returned and never counts as existing, sweeper or not'
+      : `alive=${JSON.stringify(alive)} dead=${JSON.stringify(dead)} resurrect=${JSON.stringify(resurrect)}`
+  }
+}
+
+export async function kvOnceReportsTheWinner(client) {
+  const key = 'once/order-9f1'
+  const first = await client.kv.once(KV_NS, key, { ttl: '10m' })
+  const second = await client.kv.once(KV_NS, key, { ttl: '10m' })
+
+  return {
+    success: first.won === true && second.won === false,
+    message: first.won === true && second.won === false
+      ? 'once() wins once and loses forever after, inside the TTL'
+      : `first=${JSON.stringify(first)} second=${JSON.stringify(second)}`
+  }
+}
+
+/**
+ * THE IDIOM THE WHOLE FEATURE EXISTS FOR (§8.3, §10.2).
+ *
+ * A bundle that pushes and marks itself done in one transaction. On a
+ * redelivery the marker already exists, the transaction ABORTS, and `commit()`
+ * RETURNS `{success:false, reason:'kv_precondition'}` instead of throwing --
+ * because a lost precondition is the expected outcome of every legitimate
+ * redelivery and must not enter a retry policy. The push must not have landed.
+ */
+export async function kvTransactionGateBlocksTheSecondDelivery(client) {
+  const queue = await client.queue('test-kv-gate-out').create()
+  if (!queue.configured) return { success: false, message: 'Queue not created' }
+
+  const orderId = 'order-gate-1'
+  const first = await client.transaction()
+    .queue('test-kv-gate-out')
+    .push([{ data: { orderId, attempt: 1 } }])
+    .once(KV_NS, `gate/${orderId}`, { ttl: '10m' })
+    .commit()
+
+  if (first.success !== true) {
+    return { success: false, message: `the first delivery should commit: ${JSON.stringify(first)}` }
+  }
+
+  const second = await client.transaction()
+    .queue('test-kv-gate-out')
+    .push([{ data: { orderId, attempt: 2 } }])
+    .once(KV_NS, `gate/${orderId}`, { ttl: '10m' })
+    .commit()
+
+  if (second.success !== false || second.reason !== 'kv_precondition') {
+    return { success: false, message: `the redelivery should be gated, got ${JSON.stringify(second)}` }
+  }
+  if (second.kvReason !== 'exists' || typeof second.failedIndex !== 'number') {
+    return { success: false, message: `the verdict must carry kvReason and failedIndex: ${JSON.stringify(second)}` }
+  }
+
+  const delivered = await client.queue('test-kv-gate-out').batch(10).wait(false).pop()
+  const attempts = delivered.map(m => m.data.attempt)
+
+  const ok = attempts.length === 1 && attempts[0] === 1
+  return {
+    success: ok,
+    message: ok
+      ? 'the gate rolled back the second bundle whole: one message, not two, and commit() returned the verdict'
+      : `queue received attempts ${JSON.stringify(attempts)} (expected exactly [1])`
+  }
+}

package/test-v2/pop.js

@@ -25,13 +25,11 @@ export async function popNonEmptyQueue(client) {
     // wait(false) wildcard pop can race past the not-yet-committed lookup
     // row. Long-poll re-runs the candidate scan and picks up the row
     // once it commits (typically within ms).
-    // docs:start(js-pop)
     const res = await client
     .queue('test-queue-v2-pop-non-empty')
     .batch(1)
     .wait(true)
     .pop()
-    // docs:end
     return { success: res.length === 1 }
 }
 

package/test-v2/push.js

@@ -5,11 +5,9 @@ export async function pushMessage(client) {
     if (!queue.configured) {
         return { success: false, message: 'Queue not created' }
     }
-    // docs:start(js-push)
     const res = await client
     .queue('test-queue-v2')
     .push([{ data: { message: 'Hello, world!' } }])
-    // docs:end
 
     return { success: res[0].status === 'queued' }
 }
@@ -19,7 +17,6 @@ export async function pushDuplicateMessage(client) {
     if (!queue.configured) {
         return { success: false, message: 'Queue not created' }
     }
-    // docs:start(js-push-dedup)
     const res1 = await client
     .queue('test-queue-v2')
     .push([{ transactionId: 'test-transaction-id', data: { message: 'Hello, world!' } }])
@@ -28,7 +25,6 @@ export async function pushDuplicateMessage(client) {
     .queue('test-queue-v2')
     .push([{ transactionId: 'test-transaction-id', data: { message: 'Hello, world!' } }])
     // res1[0].status === 'queued', res2[0].status === 'duplicate'
-    // docs:end
 
     return { success: res1[0].status === 'queued' && res2[0].status === 'duplicate' }
 }

package/test-v2/run.js

@@ -17,7 +17,10 @@ import * as watermarkTests from './watermark.js'
 import * as authTests from './auth.js'
 import * as semanticsTests from './semantics.js'
 import * as ackWindowTests from './ackwindow.js'
+import * as kvTests from './kv.js'
+import * as timerTests from './timers.js'
 import * as streamTests from './stream/index.js'
+import * as docsTests from './docs.js'
 import { LoadBalancer } from '../client-v2/http/LoadBalancer.js';
 
 
@@ -90,8 +93,10 @@ function printResults() {
 }
 
 export const cleanupTestData = async () => {
-    // All the LIKE patterns test queues use.
-    const patterns = ['test-%', 'edge-%', 'pattern-%', 'workflow-%'];
+    // 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
@@ -125,7 +130,29 @@ export const cleanupTestData = async () => {
 
       await dbPool.query(`DELETE FROM queen.queues WHERE name LIKE ANY($1::text[])`, [patterns]);
 
-      log(true, 'Test data cleaned up (rows + segments)');
+      // 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}`);
     }
@@ -156,7 +183,10 @@ async function main() {
         watermarkTests,
         authTests,
         semanticsTests,
-        ackWindowTests
+        ackWindowTests,
+        kvTests,
+        timerTests,
+        docsTests
     ]
     
     const aiTests = [

package/test-v2/semantics.js

@@ -47,7 +47,11 @@ const baseUrl = () => TEST_CONFIG.baseUrls[0]
 const sleep = ms => new Promise(r => setTimeout(r, ms))
 const uniq = prefix => `test-sem-${prefix}-${Date.now()}`
 
-/** Raw pop via fetch — used where the client builder has no knob (leaseSeconds). */
+/**
+ * Raw pop via fetch — used where the client builder has no knob (leaseSeconds).
+ * Callers that name a consumer group and expect the backlog they pushed must
+ * pass subscriptionMode: 'all' (the broker default seeds new groups at the tail).
+ */
 async function rawPop(queue, params = {}) {
     const qs = new URLSearchParams({ batch: '1', wait: 'false', ...params })
     const res = await fetch(`${baseUrl()}/api/v1/pop/queue/${queue}?${qs}`)
@@ -58,10 +62,11 @@ async function rawPop(queue, params = {}) {
 }
 
 /** Pop retrying briefly — rides out push→visibility latency (fusion hold). */
-async function popRetry(client, queue, { group = null, batch = 1, tries = 20 } = {}) {
+async function popRetry(client, queue, { group = null, batch = 1, tries = 20, mode = null } = {}) {
     for (let i = 0; i < tries; i++) {
         let b = client.queue(queue).batch(batch).wait(false)
         if (group) b = b.group(group)
+        if (mode) b = b.subscriptionMode(mode)
         const msgs = await b.pop()
         if (msgs.length > 0) return msgs
         await sleep(150)
@@ -374,8 +379,9 @@ export async function leasedBacklogNotStrandedByEmptyPolls(client) {
     await client.queue(queue).partition('Default')
         .push([{ data: { n: 1 }, transactionId: `${queue}-tx` }])
 
-    // Worker A claims the only partition and never acks.
-    const a = await popRetry(client, queue, { group })
+    // Worker A claims the only partition and never acks. It is the group's
+    // first contact and the message is already there, so it must ask for 'all'.
+    const a = await popRetry(client, queue, { group, mode: 'all' })
     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.
@@ -437,7 +443,10 @@ export async function pushOnlyQueueIsDiscoverable(client) {
     // (b) Namespace-discovery pop must find it.
     let found = false
     for (let i = 0; i < 10 && !found; i++) {
-        const qs = new URLSearchParams({ namespace: ns, batch: '1', wait: 'false', consumerGroup: `${ns}-cg` })
+        const qs = new URLSearchParams({
+            namespace: ns, batch: '1', wait: 'false',
+            consumerGroup: `${ns}-cg`, subscriptionMode: 'all'
+        })
         const popRes = await fetch(`${baseUrl()}/api/v1/pop?${qs}`)
         if (popRes.status === 200) {
             const pb = await popRes.json()
@@ -478,7 +487,7 @@ export async function messageDetailKeepsFullShape(client) {
         .push([{ data: { hello: 'world' }, transactionId: tx }])
 
     // Pop (don't ack) so a consumer row exists for consumerGroups[].
-    const msgs = await popRetry(client, queue, { group })
+    const msgs = await popRetry(client, queue, { group, mode: 'all' })
     if (msgs.length !== 1) return { success: false, message: 'Message not delivered' }
     const pid = msgs[0].partitionId
 
@@ -773,7 +782,7 @@ export async function popLeaseSecondsOverride(client) {
     // Claim with a 1-second per-request override.
     let got = []
     for (let i = 0; i < 20 && got.length === 0; i++) {
-        got = await rawPop(queue, { consumerGroup: group, leaseSeconds: '1' })
+        got = await rawPop(queue, { consumerGroup: group, leaseSeconds: '1', subscriptionMode: 'all' })
         if (got.length === 0) await sleep(150)
     }
     if (got.length !== 1) return { success: false, message: 'Message not delivered on override pop' }