queen-mq 1.0.0 → 1.0.5

package/README.md

@@ -28,6 +28,7 @@ Queen MQ is a PostgreSQL-backed message queue system with a powerful feature set
 - **Message Tracing** - Debug distributed workflows with trace timelines
 - **Client-Side Buffering** - 10x-100x throughput boost for high-volume pushes
 - **Real-time Streaming** - Windowed aggregation and processing
+- **Key/Value State and Timers** - Transactional state and scheduled messages
 
 This client provides a fluent, promise-based API for Node.js applications.
 
@@ -373,6 +374,145 @@ await queen.queue('orders').consume(async (msg) => {
 
 ---
 
+## Key/Value State and Timers
+
+Both surfaces are **always there**. There is nothing to enable: kv and timers are part of the
+broker the way push and pop are, on every cell that runs it. There is no capability to probe and
+no 404 that means "this cell does not have the feature" — a 404 from these routes is a bug.
+
+What an operator can still do is **pause** them, with the runtime kill switch in
+`queen.system_state` (`kv_enabled`, `timers_schedule_enabled`, `timers_fire_enabled`) — the same
+class of lever as maintenance mode, pulled live during an incident and expected to be pulled back.
+A paused surface answers `503` with `Retry-After` and `error: 'kv_disabled'` / `'timers_disabled'`,
+which this client retries like any other 5xx. Inside a transaction it is a `403` on the `kv` or
+`timers` rider instead, so a bundle holding messages does not spin forever on a paused cell.
+
+```javascript
+try {
+  await queen.kv.put('orders', 'order:9f1', { state: 'held' }, { ttl: '60s' })
+} catch (e) {
+  if (e.code === 'kv_disabled') { /* paused by an operator; it will come back */ }
+  throw e
+}
+```
+
+Branch on `e.code`, never on the message. And write that branch as "temporarily paused", not as
+"this deployment lacks KV": handling the refusal is right, treating it as a configuration to check
+before you use the surface is not.
+
+### Key/Value
+
+```javascript
+// An expiry is MANDATORY on every write: exactly one of ttlSeconds (or the
+// sugar ttl / until) and forever: true. A put never inherits the previous TTL.
+await queen.kv.put('orders', 'order:9f1', { state: 'held' }, { ttl: '60s' })
+
+const row = await queen.kv.get('orders', 'order:9f1')
+if (row.found) console.log(row.value, row.version)   // found is separate: null is a legal value
+
+// "Did I win?" in one call. This is the idempotency marker.
+const { won, value } = await queen.kv.once('dedup', eventId, { ttl: '24h' })
+if (!won) return                                     // somebody already did this
+
+// Optimistic lock. expect: 0 means "must not exist"; expect: N is a pure
+// update that creates nothing when it matches no row.
+const res = await queen.kv.put('orders', 'order:9f1', { state: 'shipped' },
+                               { ttl: '60s', expect: row.version })
+if (!res.applied) console.log(res.reason)            // 'version' | 'exists' | 'absent' | 'limit' | 'type'
+
+// Rate limiting without a CAS loop. With max, `applied` IS the admission
+// decision: nothing saturates, nothing truncates, a refusal spends no budget.
+const hit = await queen.kv.incr('quota', `${customer}:${hour}`, 1, { max: 1000, ttl: '1h' })
+if (!hit.applied) throw new TooManyRequests()
+
+for await (const r of queen.kv.listAll('saga', 'order:9f1:')) { /* follows nextAfter */ }
+```
+
+Seven operations: `get`, `getMany`, `getPrefix`, `put`, `putIfAbsent`, `delete`, `incr`, plus the
+two conveniences this client owns, `once` and `listAll`.
+
+**Every write returns an OBJECT, and objects are always truthy.** `if (await queen.kv.delete(ns,
+key))` is always taken and is a bug. Read `.applied`, or `.won` on `once`, or `.found` on a read.
+That holds for all five writes, and it is the one trap this language cannot defend against
+structurally.
+
+**A write that did not apply is not an error.** `applied: false` answers HTTP 200 with the current
+value and version, so the loser needs no second round trip.
+
+**Read-modify-write across two calls is safe only when the KV key derives from the partition key.**
+Otherwise the lanes do not serialise it for you: use `incr`, or carry `expect`.
+
+**`putIfAbsent` plus a TTL is not a distributed lock.** A lock that expires is not revoked: the old
+holder keeps working, it simply no longer has the row. Carry your `version` as `expect` on every
+later write so a lapsed holder fails with `reason: 'version'` instead of overwriting the new one.
+
+### Timers
+
+```javascript
+// Fire no earlier than 30 minutes from now, into a real queue, through the log.
+const res = await queen.timer('reminders')
+  .key(`order:${orderId}`)
+  .delay('30m')                    // or .delayMs(250)
+  .payload({ orderId })
+  .schedule()                      // status: 'scheduled' | 'rescheduled' | 'too_late'
+
+await queen.timer('reminders').key(`order:${orderId}`).peek()
+await queen.timer('reminders').list({ limit: 50 })
+await queen.timer('reminders').key(`order:${orderId}`).cancel()
+```
+
+Scheduling the same `(queue, timerKey)` again is the same upsert, so a retry after a client crash
+is safe by construction and `status` says which it was. A reschedule mints a new `txn` and resets
+the retry budget.
+
+Durations that can be sub-second are in **milliseconds** (`delayMs`), the ones that cannot are in
+**seconds** (`ttlSeconds`). Only relative delays exist, because there is one clock and it is the
+database's. A delay in the past is legal and fires on the first cycle.
+
+`deliverAt` is **"not before"**, never "exactly at".
+
+**`absent` means "no longer pending" and may mean ALREADY DELIVERED.** There is no tombstone: a
+fired timer has no row left, so `absent` carries `ok: false` and the answer echoes the `txn` so the
+authority, the log, can be consulted without a second API. A saga that cancels a compensation timer
+must have the compensating consumer re-check the saga's KV state before compensating, because the
+cancel may have arrived 5 ms after the fire.
+
+Use `queen.timer(q).key(k).cancel()` rather than a cancel inside a bundle when the cancel must land
+regardless: it takes the DELETE route, the one a quota is forbidden to block. A tenant that cannot
+cancel keeps producing messages it cannot stop.
+
+### Inside a transaction
+
+The transaction is the **primary fence**; `expect` is only the secondary assertion. A state write
+that shares the transaction with its ack is undone when an expired lease makes the ack fail, which
+a compare-and-set cannot do.
+
+```javascript
+const result = await queen.transaction()
+  .ack(message)
+  .queue('emails').push([{ data: mail }])
+  .once('sent', message.transactionId, { ttl: '24h' })   // the gate
+  .timer('reminders').key(orderId).delay('24h').payload({ orderId }).schedule()
+  .commit()
+
+if (result.success === false) {
+  // RETURNED, not thrown: a lost gate is the expected outcome of a legitimate
+  // redelivery, so it stays out of your retry policy and your error metrics.
+  result.reason        // 'kv_precondition'
+  result.failedIndex, result.kvReason, result.version, result.value
+  return
+}
+```
+
+`once` is `putIfAbsent` with `required: true`, and `required` is what makes it a gate: without it a
+lost precondition is only a verdict in the results, and the push and the ack still go through.
+
+`kv.getPrefix` is not available inside a transaction and throws here rather than at the broker: its
+cost is not bounded by the caller. `get` and `getMany` are allowed, because they are. Everything
+other than the lost precondition still throws.
+
+---
+
 ## Examples
 
 ### Complete Pipeline with Consumer Groups
@@ -521,6 +661,41 @@ await queen.transaction()
   .queue('output')
   .push([{ data: { result: 'processed' } }])
   .commit()
+
+// Riders. commit() RETURNS on a lost gate, and throws on everything else.
+await queen.transaction()
+  .ack(message)
+  .kv.put('saga', sagaId, { step: 'charged' }, { ttl: '24h' })
+  .once('dedup', message.transactionId, { ttl: '24h' })
+  .timer('reminders').key(orderId).delay('30m').payload({ orderId }).schedule()
+  .commit()
+```
+
+### Key/Value
+
+```javascript
+await queen.kv.get(ns, key)                      // {found, key, value, version, expiresAt, updatedAt}
+await queen.kv.getMany(ns, [k1, k2])             // {rows, missing, truncated}
+await queen.kv.getPrefix(ns, prefix, { limit: 100, after, keysOnly })
+await queen.kv.put(ns, key, value, { ttl: '24h', expect, required })
+await queen.kv.putIfAbsent(ns, key, value, { ttlSeconds: 86400 })
+await queen.kv.delete(ns, key, { expect })
+await queen.kv.incr(ns, key, 1, { max: 1000, min, ttl: '1h' })
+await queen.kv.once(ns, key, { ttl: '24h' })     // {won, value, version, result}
+for await (const row of queen.kv.listAll(ns, prefix)) { }
+```
+
+### Timers
+
+```javascript
+// Builder steps: .key(timerKey) required, .delayMs(250) or .delay('30m') required,
+// .payload(anyJsonOrBuffer) required to schedule, .partition(name) optional
+// (defaults to 'Default'), .txn(transactionId) optional (minted when absent).
+
+await queen.timer(q).key(k).delay('30m').payload(p).schedule()   // {ok, status, txn, messageId, deliverAt}
+await queen.timer(q).key(k).cancel()                             // {ok, status, txn}
+await queen.timer(q).key(k).peek()                               // {found, ...}
+await queen.timer(q).list({ limit: 50, after })                  // {rows, truncated, nextAfter}
 ```
 
 ### Lease Renewal

package/client-v2/Queen.js

@@ -8,6 +8,8 @@ import { LoadBalancer } from './http/LoadBalancer.js'
 import { BufferManager } from './buffer/BufferManager.js'
 import { QueueBuilder } from './builders/QueueBuilder.js'
 import { TransactionBuilder } from './builders/TransactionBuilder.js'
+import { TimerBuilder } from './builders/TimerBuilder.js'
+import { Kv } from './kv/Kv.js'
 import { StreamBuilder } from './stream/StreamBuilder.js'
 import { StreamConsumer } from './stream/StreamConsumer.js'
 import { Admin } from './admin/Admin.js'
@@ -57,6 +59,7 @@ export class Queen {
   #config
   #shutdownHandlers = []
   #admin = null
+  #kv = null
 
   constructor(config = {}) {
     // Configure custom logger before anything else.
@@ -216,6 +219,57 @@ export class Queen {
     return this.#admin
   }
 
+  // ===========================
+  // KV API Entry Point
+  // ===========================
+
+  /**
+   * Transactional key/value state, alongside the log
+   * (PLAN_KV_TIMERS.md §5).
+   *
+   *     const { won } = await queen.kv.once('idem', orderId, { ttl: '24h' })
+   *     const row = await queen.kv.get('saga', sagaId)   // {found, value, version, ...}
+   *
+   * Two things to carry into every use of it:
+   *   * every write returns an OBJECT, and objects are always truthy --
+   *     `if (await queen.kv.delete(ns, key))` is always true. Read `.applied`.
+   *   * an expiry is MANDATORY on every write: exactly one of `ttlSeconds`
+   *     (or the sugar `ttl` / `until`) and `forever: true`. There is no
+   *     default, because a default is how a marker becomes immortal.
+   *
+   * Lazily initialized, singleton, like `admin`.
+   * @returns {Kv}
+   */
+  get kv() {
+    if (!this.#kv) {
+      this.#kv = new Kv(this.#httpClient)
+    }
+    return this.#kv
+  }
+
+  // ===========================
+  // Timers API Entry Point
+  // ===========================
+
+  /**
+   * Scheduled messages for one queue (PLAN_KV_TIMERS.md §4).
+   *
+   *     await queen.timer('orders').key(orderId).delay('30m')
+   *                .payload({ orderId }).schedule()
+   *     await queen.timer('orders').key(orderId).cancel()
+   *
+   * `deliverAt` is "not before", never "exactly at". A cancel that answers
+   * `absent` means "no longer pending" and MAY MEAN ALREADY DELIVERED -- there
+   * is no tombstone, and the authority is the log.
+   *
+   * @param {string} queueName - destination queue (mandatory)
+   * @returns {TimerBuilder}
+   */
+  timer(queueName) {
+    logger.log('Queen.timer', { queue: queueName })
+    return new TimerBuilder(this.#httpClient, queueName)
+  }
+
   // ===========================
   // Transaction API
   // ===========================

package/client-v2/README.md

@@ -1730,6 +1730,38 @@ await queen
   .commit()
 ```
 
+### Key/Value and Timers
+
+Always present on every broker — no flag, nothing to probe. An operator's runtime kill switch can
+pause them (`503` + `Retry-After`, `error: 'kv_disabled'` / `'timers_disabled'`; `403` on a rider
+inside a transaction), which is a pause and not an absence. Full treatment in the
+[client README](../README.md#keyvalue-state-and-timers).
+
+```javascript
+// Every write states its lifetime: exactly one of ttl/ttlSeconds/until and forever.
+await queen.kv.put('orders', 'order:9f1', { state: 'held' }, { ttl: '60s' })
+const row = await queen.kv.get('orders', 'order:9f1')   // {found, value, version, ...}
+
+// Writes return an OBJECT, always truthy. Read .applied, never the result itself.
+const res = await queen.kv.delete('orders', 'order:9f1')
+if (res.applied) { }
+
+const { won } = await queen.kv.once('dedup', eventId, { ttl: '24h' })
+const hit = await queen.kv.incr('quota', key, 1, { max: 1000, ttl: '1h' })  // applied IS admission
+
+await queen.timer('reminders').key(orderId).delay('30m').payload({ orderId }).schedule()
+await queen.timer('reminders').key(orderId).cancel()    // 'absent' may mean already delivered
+
+// The gate: marker, push and ack commit or roll back together.
+const out = await queen
+  .transaction()
+  .ack(message)
+  .queue('emails').push([{ data: mail }])
+  .once('sent', message.transactionId, { ttl: '24h' })
+  .commit()
+if (out.success === false) return   // returned, not thrown: a redelivery already handled
+```
+
 ### Lease Renewal
 
 ```javascript

package/client-v2/admin/Admin.js

@@ -68,6 +68,24 @@ export class Admin {
     return this.#httpClient.get(`/api/v1/resources/queues/${encodeURIComponent(name)}`)
   }
 
+  /**
+   * Per-partition backlog for a queue — the cheap sibling of getQueue:
+   * watermark arithmetic only, no segments, no timestamps. Shape:
+   * {queue, group, pending, partitions: [{partition, pending}]}.
+   * Omitting group gives queue-level pending under the same worst-cursor
+   * precedence the dashboard publishes; a named group is that group's own
+   * backlog per partition. Requires broker >= 1.0.4 — an older broker
+   * answers 404 no_such_route, so fall back to getQueue there.
+   * @param {string} name - Queue name
+   * @param {string|null} [group] - Consumer group (optional)
+   * @returns {Promise<object>}
+   */
+  async getQueueDepth(name, group = null) {
+    logger.log('Admin.getQueueDepth', { name, group })
+    const queryString = group ? `?group=${encodeURIComponent(group)}` : ''
+    return this.#httpClient.get(`/api/v1/resources/queues/${encodeURIComponent(name)}/depth${queryString}`)
+  }
+
   /**
    * Clear all messages from a queue
    * @param {string} name - Queue name

package/client-v2/builders/QueueBuilder.js

@@ -374,22 +374,14 @@ export class QueueBuilder {
     throw new Error('Must specify queue, namespace, or task for pop operation')
   }
 
-  #buildPopParams() {
-    const params = new URLSearchParams({
-      batch: this.#batch.toString(),
-      wait: this.#wait.toString(),
-      timeout: this.#timeoutMillis.toString()  // Server expects 'timeout', not 'timeoutMillis'
-    })
-
-    if (this.#group) params.append('consumerGroup', this.#group)
-    if (this.#namespace) params.append('namespace', this.#namespace)
-    if (this.#task) params.append('task', this.#task)
-    if (this.#autoAck) params.append('autoAck', 'true')
-    if (this.#subscriptionMode) params.append('subscriptionMode', this.#subscriptionMode)
-    if (this.#subscriptionFrom) params.append('subscriptionFrom', this.#subscriptionFrom)
-
-    return params
-  }
+  // NOTE: a second, DEAD copy of the pop parameter builder lived here and was
+  // deleted with the kv/timers work (PLAN_KV_TIMERS.md §10.4). pop() builds its
+  // own params inline, above, because it has to override autoAck with the POP
+  // defaults; the dead copy did not. Anyone adding a parameter by looking for
+  // the method whose name says "build pop params" would have added it to the
+  // copy nobody calls: the pop would keep working and the parameter would
+  // simply never arrive, which reads as a server-side mystery and not as a
+  // client bug.
 
   // ===========================
   // Buffer Management Methods

package/client-v2/builders/TimerBuilder.js

@@ -0,0 +1,262 @@
+/**
+ * Timers (PLAN_KV_TIMERS.md §4, §8.1, §9.6).
+ *
+ * A timer is a message you promise now and the broker delivers later, into a
+ * real queue, through the real log. Four terminals, all EXPLICIT -- nothing on
+ * this builder does anything until one of them is called:
+ *
+ *     await queen.timer('orders').key('order-9f1').delay('30s')
+ *                .payload({ orderId: '9f1' }).schedule()
+ *     await queen.timer('orders').key('order-9f1').cancel()
+ *     await queen.timer('orders').key('order-9f1').peek()
+ *     await queen.timer('orders').list({ limit: 50 })
+ *
+ * THE FOUR THINGS THIS FILE EXISTS TO GET RIGHT
+ *
+ * 1. CANCEL USES ITS OWN ROUTE, AND THAT IS NOT A DETAIL (§9.6).
+ *    `DELETE /api/v1/timers/:queue/*timerKey` is the one route a proxy is
+ *    forbidden to block; a cancel sent inside `POST /api/v1/timers` inherits
+ *    the schedule's authorization instead. Since the FIRE never switches
+ *    itself off, a tenant that can no longer cancel keeps producing messages it
+ *    cannot stop -- a block there produces the exact opposite of its purpose.
+ *    So `cancel()` on this builder always uses the DELETE route. (Inside a
+ *    transaction it necessarily rides the bundle's array and inherits the
+ *    bundle's fate; see TransactionBuilder, which says so where it happens.)
+ *
+ * 2. ONLY RELATIVE DURATIONS, IN MILLISECONDS (§4.2, §20.6). `delayMs`, never
+ *    `delaySeconds` and never an absolute instant: `deliver_at` is computed in
+ *    Postgres, so there is ONE clock and no broker's skew can enter. The rule
+ *    of the product is "durations that can be sub-second are in milliseconds,
+ *    the ones that cannot are in seconds" -- a 250 ms retry backoff is a real
+ *    and central use of timers, which is why this wire is the millisecond one.
+ *    A delay in the past is LEGAL and fires on the first cycle.
+ *
+ * 3. `deliverAt` IS "NOT BEFORE", NEVER "EXACTLY AT". The floor on this stack
+ *    is a single hop (p50 ~10 ms, fsync ~4 ms) plus one sweep cycle.
+ *
+ * 4. THERE IS NO TOMBSTONE (§4.4). Once a timer has fired its row is gone, so a
+ *    later cancel answers `absent` -- **which MAY mean it was already
+ *    delivered**. `absent` carries `ok:false` for exactly that reason, and the
+ *    response echoes the `txn` so the authority (the log, in the destination
+ *    queue) can be consulted without a second API. Any saga that cancels a
+ *    compensation timer must have the compensating consumer check the saga's
+ *    KV state before compensating: otherwise "the timer went out 5 ms before
+ *    the cancel" unwinds a booking that was already shipped.
+ */
+
+import * as logger from '../utils/logger.js'
+import { generateUUID } from './QueueBuilder.js'
+import { parseDurationMs } from '../kv/expiry.js'
+
+/** JSON payloads are encoded for the caller; raw bytes are passed through. */
+function encodePayload(payload) {
+  if (payload === undefined) return undefined
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(payload)) {
+    return payload.toString('base64')
+  }
+  if (payload instanceof Uint8Array) {
+    return Buffer.from(payload).toString('base64')
+  }
+  return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64')
+}
+
+export class TimerBuilder {
+  #httpClient
+  #queue
+  #sink
+  #timerKey = null
+  #partition = null
+  #delayMs = null
+  #payloadB64 = undefined
+  #txn = null
+
+  /**
+   * `sink`, when present, receives the finished op instead of the network:
+   * that is how the same builder serves `queen.timer(...)` and
+   * `tx.timer(...)`, so the wire shape of a timer op is written once.
+   */
+  constructor(httpClient, queue, sink = null) {
+    if (typeof queue !== 'string' || queue.length === 0) {
+      throw new Error('timer: a queue name is required — a timer without a queue has nowhere to be delivered')
+    }
+    this.#httpClient = httpClient
+    this.#queue = queue
+    this.#sink = sink
+  }
+
+  /** The timer's identity inside its queue. `(queue, timerKey)` is the primary key. */
+  key(timerKey) {
+    if (typeof timerKey !== 'string' || timerKey.length === 0) {
+      throw new Error('timer: timerKey must be a non-empty string')
+    }
+    this.#timerKey = timerKey
+    return this
+  }
+
+  /** Destination partition of the delivered message. Defaults to 'Default'. */
+  partition(name) {
+    this.#partition = name
+    return this
+  }
+
+  /** Fire no earlier than this many milliseconds from now. Negative is legal: it fires on the first cycle. */
+  delayMs(ms) {
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+      throw new Error(`timer: delayMs must be a finite number of milliseconds, got ${JSON.stringify(ms)}`)
+    }
+    this.#delayMs = Math.round(ms)
+    return this
+  }
+
+  /** The same delay as a duration string: '250ms', '30s', '2h'. Converted to delayMs here. */
+  delay(duration) {
+    this.#delayMs = Math.round(parseDurationMs(duration))
+    return this
+  }
+
+  /** The message body. Any JSON value, or a Buffer/Uint8Array for raw bytes. */
+  payload(payload) {
+    this.#payloadB64 = encodePayload(payload)
+    return this
+  }
+
+  /**
+   * The transaction id the delivered message will carry. Minted when absent.
+   *
+   * §20.2: every reschedule overwrites it, because a rescheduled timer is a
+   * NEW message -- and the corollary that must travel with it is that there is
+   * no dedup net on the fire at all, so rescheduling or republishing a timer
+   * that has already gone out produces a second message in the log and nothing
+   * stops it.
+   */
+  txn(transactionId) {
+    this.#txn = transactionId
+    return this
+  }
+
+  // ------------------------------------------------------------ op shapes
+
+  #scheduleOp() {
+    if (!this.#timerKey) throw new Error('timer: key(...) is required to schedule')
+    if (this.#delayMs === null) {
+      throw new Error('timer: delayMs(...) or delay(...) is required — an absolute instant is not expressible on this wire')
+    }
+    if (this.#payloadB64 === undefined) throw new Error('timer: payload(...) is required to schedule')
+    const op = {
+      op: 'schedule',
+      queue: this.#queue,
+      timerKey: this.#timerKey
+    }
+    if (this.#partition !== null && this.#partition !== undefined) op.partition = this.#partition
+    op.delayMs = this.#delayMs
+    op.txn = this.#txn || generateUUID()
+    op.payload = this.#payloadB64
+    return op
+  }
+
+  #cancelOp() {
+    if (!this.#timerKey) throw new Error('timer: key(...) is required to cancel')
+    const op = { op: 'cancel', queue: this.#queue, timerKey: this.#timerKey }
+    if (this.#txn) op.txn = this.#txn
+    return op
+  }
+
+  #path(suffix = '') {
+    return `/api/v1/timers/${encodeURIComponent(this.#queue)}${suffix}`
+  }
+
+  #keyPath() {
+    return this.#path(`/${encodeURIComponent(this.#timerKey)}`)
+  }
+
+  #single(body, what) {
+    if (!body || typeof body !== 'object' || !Array.isArray(body.results)) {
+      throw new Error(`timer: unexpected ${what} response envelope — expected {"results":[...]}`)
+    }
+    if (body.results.length !== 1) {
+      throw new Error(`timer: got ${body.results.length} results for 1 operation`)
+    }
+    return body.results[0]
+  }
+
+  // ------------------------------------------------------------ terminals
+
+  /**
+   * Schedule (or reschedule) this timer. An UPSERT on `(queue, timerKey)`, so
+   * a retry after a client crash is safe by construction; the answer says
+   * which it was, `status: 'scheduled' | 'rescheduled'`.
+   *
+   * A reschedule resets `attempts` and clears `last_error`: a rescheduled
+   * timer is a new timer under an old name, and a freshly corrected payload
+   * must not inherit the budget consumed by the one that was poisoning it.
+   *
+   * `too_late` (with `ok:false`) means the timer is already claimed by a
+   * broker that is about to commit it. Bounded by the sweeper lease. The
+   * remedy is a new key, or waiting for the delivery and acting on the message.
+   */
+  // NOT `async`, deliberately: with a sink this terminal is the transaction's
+  // own chaining call and must hand back the TransactionBuilder itself, not a
+  // promise of it, or `.timer(q)...schedule().commit()` stops being a chain.
+  // The network path returns the promise, so `await ...schedule()` is
+  // unchanged for the standalone caller.
+  schedule() {
+    if (this.#sink) return this.#sink(this.#scheduleOp())
+    return this.#scheduleRemote()
+  }
+
+  // The op is built INSIDE the async function so that a shape error on the
+  // network path is a rejected promise like every other failure of this
+  // client, and not a synchronous throw that `.catch()` would miss. On the
+  // transaction path it necessarily stays synchronous: there is no promise
+  // there to reject.
+  async #scheduleRemote() {
+    const op = this.#scheduleOp()
+    logger.log('TimerBuilder.schedule', { queue: this.#queue, timerKey: op.timerKey, delayMs: op.delayMs })
+    const body = await this.#httpClient.post('/api/v1/timers', { operations: [op] })
+    return this.#single(body, 'schedule')
+  }
+
+  /**
+   * Cancel this timer, through the route that is never blockable (§9.6).
+   *
+   * Idempotent: `absent` answers `ok:false` and MAY MEAN ALREADY DELIVERED --
+   * there is no tombstone. Pass `.txn(...)` and it comes back in the answer,
+   * so the log can settle the question.
+   */
+  cancel() {
+    if (this.#sink) return this.#sink(this.#cancelOp())
+    return this.#cancelRemote()
+  }
+
+  async #cancelRemote() {
+    const op = this.#cancelOp()
+    logger.log('TimerBuilder.cancel', { queue: this.#queue, timerKey: op.timerKey })
+    const query = op.txn ? `?txn=${encodeURIComponent(op.txn)}` : ''
+    return this.#httpClient.delete(`${this.#keyPath()}${query}`)
+  }
+
+  /** Read one pending timer, payload included. A miss is `{found:false}` with HTTP 200, never a 404. */
+  async peek() {
+    if (this.#sink) throw new Error('timer: peek is a read, not a transaction operation — use queen.timer(...).peek()')
+    if (!this.#timerKey) throw new Error('timer: key(...) is required to peek')
+    logger.log('TimerBuilder.peek', { queue: this.#queue, timerKey: this.#timerKey })
+    return this.#httpClient.get(this.#keyPath())
+  }
+
+  /**
+   * List the pending timers of this queue: `{rows, truncated, nextAfter}`.
+   *
+   * The queue is mandatory and that is why it is a path segment rather than a
+   * filter: a tenant-wide list would be a scan that an end user of the
+   * customer could trigger. `after` is an exclusive keyset cursor.
+   */
+  async list(opts = {}) {
+    if (this.#sink) throw new Error('timer: list is a read, not a transaction operation — use queen.timer(...).list()')
+    const params = new URLSearchParams()
+    if (opts.after !== undefined && opts.after !== null && opts.after !== '') params.append('after', opts.after)
+    if (opts.limit !== undefined && opts.limit !== null) params.append('limit', String(opts.limit))
+    const query = params.toString()
+    logger.log('TimerBuilder.list', { queue: this.#queue, after: opts.after, limit: opts.limit })
+    return this.#httpClient.get(this.#path(query ? `?${query}` : ''))
+  }
+}