queen-mq 2.0.3 → 2.1.0

package/README.md

@@ -636,6 +636,49 @@ 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.
+`queen.lock()` below is that, done for you.
+
+**`check` asserts a version and writes nothing.** `kv.check(ns, key, { expect })` holds while the
+key is at that version (`expect: 0`: while it is absent). With `required: true` in a transaction
+it gates the commit on a key the transaction does not write.
+
+### Locks and semaphores
+
+A lock is a lease: one holder at a time, for a lifetime the holder renews, with a token that
+fences a holder that outlived it. `queen.semaphore(name, n, opts)` is the same with `n` permits.
+
+```javascript
+const lock = queen.lock('daily-report', { ttl: '30s' })
+if (!(await lock.acquire({ wait: '5s' }))) return   // somebody else holds it
+
+try {
+  await queen.transaction()
+    .guard(lock)                                    // commits only while the lock is ours
+    .queue('reports').push([{ data: report }])
+    .commit()
+} finally {
+  await lock.release()
+}
+
+// Or: acquire, run, release.
+const { acquired, value } = await queen.lock('sync:crm', { ttl: '1m' }).run(() => sync())
+```
+
+**It expires, and nobody tells the holder.** A paused or partitioned process carries on past its
+lifetime while somebody else acquires. `.guard(lock)` is what keeps its work out: the transaction
+rolls back with `reason: 'kv_precondition'` (returned from `commit()`, not thrown) when the lock is
+no longer this handle's. Outside Queen, fence with `lock.token`, which only rises on a lock.
+
+**The handle renews in the background**, every third of the lifetime (`autoRenew: false` to do it
+yourself with `lock.renew()`), and says when the lock is gone: `lock.signal` aborts and
+`lock.onLost(fn)` runs. Nothing stops your code: pass `lock.signal` to what the work awaits.
+
+**The token changes at every renew.** Read `lock.token` and `lock.guard()` when you use them; do
+not keep a copy across an `await`.
+
+`queen.locks` is the wire, with no state kept: `acquire`, `renew`, `release`, `get(name)` (who
+holds it, since when, until when) and `batch` for several locks in one call. `queen.close()`
+releases the locks its handles still hold.
 
 ### Timers
 
@@ -1079,3 +1122,60 @@ const messages: Message<OrderData>[] = await queen.queue('orders').pop()
 ## License
 
 Apache 2.0 - See [LICENSE.md](../LICENSE.md)
+
+### Optional consumer supervision
+
+```js
+await queen.queue('orders').group('billing')
+  .supervision({ group: 'billing-production' })
+  .concurrency(4).each().consume(async message => { /* process message */ })
+```
+
+Supervision defaults to off; `.supervision(false)` disables it. The group names
+an application/deployment in the dashboard, independently of the consumer group.
+Each consume invocation publishes its own instance into the broker's
+`queen-supervisor` KV namespace every 10 seconds (30-second heartbeat timeout,
+60-second TTL), plus a final stopped observation. The credential needs KV write
+access. Publication is serialized and best effort with a two-second deadline.
+
+#### Match supervision to the consumer lifetime
+
+The instance belongs to one **`consume()` invocation**, not to the `Queen`
+client, queue, hostname, process or publication group. Reusing the same client,
+builder and group does not reuse the instance ID. Each invocation starts new
+counters, publishes its initial state, then reports `stopped` when all its
+workers exit, including a normal exit caused by `.limit(...)`, `.idleMillis(...)`
+or cancellation.
+
+| Application pattern | Supervision setup |
+| --- | --- |
+| One persistent `consume()` with several concurrent workers | Enable `.supervision({ group })` on that invocation. |
+| Several persistent `consume()` calls in one process | Enable reporting on each; expect several instances with the same hostname. Budget their combined concurrency. |
+| An outer scheduler repeatedly calling `.limit(1).consume(...)` or rotating queues | Leave per-call supervision off when you need the scheduler's lifetime status; publish one observation for the persistent scheduler instead. |
+
+For a persistent consumer, omit limits that deliberately end the invocation.
+Pass an `AbortSignal` to `consume(handler, { signal })`; on shutdown, abort it,
+await the consume promise so active handlers drain, then close the client.
+Do not remove an existing scheduler's limits just to change the dashboard:
+those limits may enforce queue fairness and the application's worker budget.
+
+Supervising short calls is valid when you want to observe those calls. A loop
+that starts a new call after every message or idle poll will produce many
+recent `stopped` instances, with `running: 0`, until their 60-second TTL expires.
+Expired records can remain visible until the broker sweeps them.
+That is the last state of each finished invocation, not evidence that its
+process or pod has stopped. Compare instance IDs and application logs.
+
+The JavaScript API has no option to attach several consume invocations to one
+persistent reporter or supply their instance ID. A custom scheduler can publish
+the [consumer status contract](https://queenmq.com/reference/supervisor-status/#reporting-an-application-owned-scheduler)
+with one ID per scheduler lifetime, stable worker pool names and counters
+across turns. Keep SDK supervision disabled on its short calls and preserve
+their ACK/NACK, lease renewal, cancellation and scheduling behavior.
+
+The Supervisors page supporting `queen.consumer.status/v1` shows live async
+consumer loops, busy handlers, successful/failed handler calls and progress times.
+A batch is one handler call; completion does not imply ACK success. No payloads or
+error text are published. Event-loop starvation can stop heartbeats. Reporting
+does not restart processes or tasks, change ACK/lease policies, or enable remote
+control. With reporting off there is no additional timer or network traffic.

package/client-v2/Queen.js

@@ -10,6 +10,7 @@ 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 { Locks, Lock } from './locks/Locks.js'
 import { Ephemeral } from './ephemeral/Ephemeral.js'
 import { StreamBuilder } from './stream/StreamBuilder.js'
 import { StreamConsumer } from './stream/StreamConsumer.js'
@@ -93,6 +94,7 @@ export class Queen {
   #shutdownHandlers = []
   #admin = null
   #kv = null
+  #locks = null
   #ephemeral = null
   // Process-wide kill switch for pop autopilot, read from
   // QUEEN_SDK_POP_AUTOPILOT once here rather than on every pop: it is a
@@ -298,6 +300,76 @@ export class Queen {
     return this.#kv
   }
 
+  // ===========================
+  // Locks API Entry Point
+  // ===========================
+
+  /**
+   * A lock: one holder at a time, held as a lease, with a fencing token.
+   *
+   *     const lock = queen.lock('daily-report', { ttl: '30s' })
+   *     if (!(await lock.acquire())) return            // somebody else has it
+   *     try {
+   *       await queen.transaction().guard(lock)
+   *         .queue('reports').push([{ data: report }]).commit()
+   *     } finally {
+   *       await lock.release()
+   *     }
+   *
+   * Creating the handle sends nothing. `acquire()` resolves a boolean,
+   * `acquire({ wait: '10s' })` keeps trying, and while it is held the handle
+   * renews it in the background and aborts `lock.signal` if it is lost.
+   *
+   * It is a lease, not a mutex: it expires, and a holder that outlived it
+   * keeps running. `.guard(lock)` on a transaction is what makes the WORK
+   * exclusive; see `locks/Locks.js` for the whole argument.
+   *
+   * @param {string} name - no '#', no control characters, at most 256 bytes
+   * @param {{ttl?: string, ttlSeconds?: number, owner?: string, autoRenew?: boolean, renewEvery?: string}} opts
+   *   a lifetime is mandatory: `ttl: '30s'` or `ttlSeconds: 30`
+   * @returns {Lock}
+   */
+  lock(name, opts = {}) {
+    if (opts.limit !== undefined && opts.limit !== 1) {
+      throw new Error('lock: a lock has one permit — queen.semaphore(name, limit, opts) is the one with more')
+    }
+    return new Lock(this.locks, name, opts)
+  }
+
+  /**
+   * A semaphore: at most `limit` holders at a time. One handle is ONE permit;
+   * make a handle per holder.
+   *
+   *     const gpu = queen.semaphore('gpu', 4, { ttl: '2m' })
+   *     const { acquired } = await gpu.run(() => train(job), { wait: '30s' })
+   *
+   * Everything a lock's handle does, this one does (it is the same class: a
+   * lock is the semaphore of one). Every holder of one name passes the same
+   * limit — it is the caller's and is stored nowhere, so while a limit is
+   * being changed the larger one rules.
+   *
+   * @returns {Lock}
+   */
+  semaphore(name, limit, opts = {}) {
+    return new Lock(this.locks, name, { ...opts, limit })
+  }
+
+  /**
+   * The four lock operations as the broker speaks them — `acquire`, `renew`,
+   * `release`, `get`, and `batch` for several locks in one call — with no
+   * state kept: you carry the token. `queen.lock()` is what most code wants;
+   * this is for `get` (who holds it?) and for a caller with its own loop.
+   *
+   * Lazily initialized, singleton, like `kv`.
+   * @returns {Locks}
+   */
+  get locks() {
+    if (!this.#locks) {
+      this.#locks = new Locks(this.#httpClient)
+    }
+    return this.#locks
+  }
+
   // ===========================
   // Ephemeral API Entry Point
   // ===========================
@@ -717,6 +789,18 @@ export class Queen {
     // Cleanup buffer manager
     this.#bufferManager.cleanup()
 
+    // Give back the locks this client's handles still hold, so the next
+    // holder does not wait out their lifetime. Best effort: one that cannot
+    // be released expires by itself.
+    if (this.#locks) {
+      try {
+        const released = await this.#locks.releaseAll()
+        if (released > 0) logger.log('Queen.close', { locksReleased: released })
+      } catch (error) {
+        logger.warn('Queen.close', { error: error.message, phase: 'lock-release' })
+      }
+    }
+
     // Remove shutdown handlers
     for (const cleanup of this.#shutdownHandlers) {
       cleanup()

package/client-v2/builders/QueueBuilder.js

@@ -42,6 +42,7 @@ export class QueueBuilder {
   #config = {}
 
   // Consume options
+  #supervision = false
   #concurrency = CONSUME_DEFAULTS.concurrency
   // batch / maxPartitions hold the USER's value, and null means the setter was
   // never called -- which is the dimension pop autopilot gets to choose. The
@@ -238,6 +239,12 @@ export class QueueBuilder {
     return this
   }
 
+  /** Opt-in consumer observations in the broker dashboard; false by default. */
+  supervision(config = false) {
+    this.#supervision = config
+    return this
+  }
+
   concurrency(count) {
     this.#concurrency = Math.max(1, count)
     return this
@@ -410,6 +417,7 @@ export class QueueBuilder {
       // has to survive all the way to #buildParams: it is the ONLY record that
       // the user said nothing about that dimension.
       autopilot: this.#autopilotEnabled(),
+      supervision: options.supervision ?? this.#supervision,
       signal: options.signal
     }
 

package/client-v2/builders/TransactionBuilder.js

@@ -40,6 +40,10 @@ export class TransactionBuilder {
   // was queued would ship a TTL already stale by however long the bundle took
   // to assemble. Materialized in commit(), which is send time.
   #kvEntries = []
+  // Lock handles whose permit this bundle commits under (`.guard(lock)`).
+  // Kept as handles, not as ops: the token is read at SEND time, because a
+  // lock's own renewal changes it.
+  #guards = []
   #timerOps = []
   #kvApi = null
 
@@ -202,6 +206,9 @@ export class TransactionBuilder {
       putIfAbsent: (ns, key, value, opts = {}) => add(kvOp.putIfAbsent(ns, key, value, opts)),
       delete: (ns, key, opts = {}) => add(kvOp.delete(ns, key, opts)),
       incr: (ns, key, delta = 1, opts = {}) => add(kvOp.incr(ns, key, delta, opts)),
+      // A precondition on a key the bundle does not write. With
+      // `required: true` it is the bundle's gate; without, only a look.
+      check: (ns, key, opts = {}) => add(kvOp.check(ns, key, opts)),
       getPrefix: () => {
         throw new Error(
           'kv: getPrefix is not available inside a transaction — unbounded read work under the outermost ' +
@@ -236,6 +243,40 @@ export class TransactionBuilder {
     return this.kv.putIfAbsent(ns, key, value, { ...opts, ...required })
   }
 
+  /**
+   * Commit this bundle only while a lock is held.
+   *
+   *     const lock = queen.lock('daily-report', { ttl: '30s' })
+   *     if (!(await lock.acquire())) return
+   *     const res = await queen.transaction()
+   *       .guard(lock)
+   *       .queue('reports').push([{ data: report }])
+   *       .commit()
+   *     if (res.success === false) return    // the lock is somebody else's now
+   *
+   * The guard is a `check` of the permit's row at the lock's token, with
+   * `required: true`: the broker judges it in the same log entry as the acks,
+   * pushes, keys and timers beside it. A holder that was paused past its
+   * lifetime and replaced commits NOTHING — which the lock by itself cannot
+   * promise, since nobody stops an expired holder from running.
+   *
+   * The token is read when `commit()` sends, and a lock's own background
+   * renewal moves it. A guard that lost to this handle's own renewal is sent
+   * again with the new token; one that lost to another holder is the verdict,
+   * returned like `once`'s (`success: false, reason: 'kv_precondition'`), and
+   * the handle then reports the lock lost.
+   *
+   * Throws at `commit()`, with `.code === 'LOCK_NOT_HELD'`, when the handle
+   * holds nothing: a step that asked for a guard must not go out without one.
+   */
+  guard(lock) {
+    if (!lock || typeof lock.guard !== 'function' || typeof lock._settled !== 'function') {
+      throw new Error('transaction: guard() takes a lock from queen.lock() or queen.semaphore()')
+    }
+    this.#guards.push(lock)
+    return this
+  }
+
   // ===========================
   // Timer rider (§4, §9.6)
   // ===========================
@@ -266,20 +307,11 @@ export class TransactionBuilder {
     })
   }
 
-  async commit() {
-    const riderCount = this.#kvEntries.length + this.#timerOps.length
-    if (this.#operations.length === 0 && riderCount === 0) {
-      logger.error('TransactionBuilder.commit', 'No operations to commit')
-      throw new Error('Transaction has no operations to commit')
-    }
-
-    logger.log('TransactionBuilder.commit', {
-      operationCount: this.#operations.length,
-      requiredLeases: this.#requiredLeases.length,
-      kv: this.#kvEntries.length,
-      timers: this.#timerOps.length
-    })
-
+  /**
+   * The request body, built at send time. The guards go first in `kv`, so
+   * guard `i` is op `i` of the rider.
+   */
+  #body() {
     // Byte-identity when the riders are absent (§6.3): the keys are added only
     // when there is something in them, so a bundle that uses neither feature
     // produces exactly the body it produced before this feature existed.
@@ -287,16 +319,72 @@ export class TransactionBuilder {
       operations: this.#operations,
       requiredLeases: [...new Set(this.#requiredLeases)] // Unique leases
     }
-    if (this.#kvEntries.length > 0) {
+    if (this.#guards.length + this.#kvEntries.length > 0) {
       const now = Date.now()
-      body.kv = this.#kvEntries.map(e => materializeKvOp(e, now))
+      body.kv = [
+        ...this.#guards.map(lock => lock.guard()),
+        ...this.#kvEntries.map(e => materializeKvOp(e, now))
+      ]
     }
     if (this.#timerOps.length > 0) {
       body.timers = this.#timerOps
     }
+    return body
+  }
+
+  /**
+   * The lock whose guard is the precondition a rolled-back bundle names, if
+   * it is one of this bundle's. `failedIndex` is in the FLAT space of
+   * `results[]`: every pushed item and every ack first, then the `kv` rider.
+   */
+  #failedGuard(result) {
+    if (this.#guards.length === 0 || !Number.isInteger(result.failedIndex)) return null
+    const flatOperations = this.#operations.reduce(
+      (n, op) => n + (op.type === 'push' ? op.items.length : 1), 0
+    )
+    return this.#guards[result.failedIndex - flatOperations] ?? null
+  }
+
+  async commit() {
+    const riderCount = this.#guards.length + this.#kvEntries.length + this.#timerOps.length
+    if (this.#operations.length === 0 && riderCount === 0) {
+      logger.error('TransactionBuilder.commit', 'No operations to commit')
+      throw new Error('Transaction has no operations to commit')
+    }
+
+    logger.log('TransactionBuilder.commit', {
+      operationCount: this.#operations.length,
+      requiredLeases: this.#requiredLeases.length,
+      kv: this.#kvEntries.length,
+      guards: this.#guards.length,
+      timers: this.#timerOps.length
+    })
 
     try {
-      const result = await this.#httpClient.post('/api/v1/transaction', body)
+      // A bundle is sent again in ONE case: its guard lost to the lock's own
+      // background renewal, which moved the token between the moment the body
+      // was built and the moment the broker judged it. The row still names
+      // this owner, so the lock is held; nothing committed (a lost required
+      // precondition rolls the whole bundle back), so sending it again with
+      // the new token is the same step, not a second one.
+      let result
+      for (let attempt = 0; ; attempt++) {
+        await Promise.all(this.#guards.map(lock => lock._settled()))
+        result = await this.#httpClient.post('/api/v1/transaction', this.#body())
+        if (result.success || result.reason !== 'kv_precondition') break
+        const lock = this.#failedGuard(result)
+        if (!lock) break
+        const ownRenewal = result.kvReason === 'version' && result.value?.owner === lock.owner
+        if (!ownRenewal) {
+          // Expired, released, or another holder's: the lock is gone.
+          lock._lost('guard')
+          break
+        }
+        if (attempt >= 3) break
+        await lock._settled()
+        if (!lock.held) break
+        logger.log('TransactionBuilder.commit', { status: 'guard_renewed', lock: lock.name, attempt })
+      }
 
       if (!result.success) {
         // THE ONE OUTCOME THAT RETURNS INSTEAD OF THROWING (§8.3).

package/client-v2/consumer/ConsumerManager.js

@@ -3,6 +3,7 @@
  */
 
 import * as logger from '../utils/logger.js'
+import { Supervision } from './Supervision.js'
 import { checkConflationResponse, CONFLATION_UNSUPPORTED } from '../utils/conflation.js'
 import { popSizing, parseAutopilotDecision, emptyPollDelayMillis } from '../utils/autopilot.js'
 import { CONSUME_DEFAULTS } from '../utils/defaults.js'
@@ -92,9 +93,13 @@ export class ConsumerManager {
     // Generate affinity key for consistent routing to same backend
     const affinityKey = this.#getAffinityKey(queue, partition, namespace, task, group)
 
+    const supervision = options.supervision ? new Supervision(this.#httpClient, options.supervision, options) : null
+    if (supervision) handler = supervision.wrap(handler)
+
     // Start workers
     const workers = []
     for (let i = 0; i < concurrency; i++) {
+      if (supervision) supervision.running++
       workers.push(this.#worker(i, handler, path, baseParams, {
         batch,
         limit,
@@ -113,9 +118,12 @@ export class ConsumerManager {
         // the pop target to key the once-per-(queue,group) conflict warning.
         conflation,
         conflationCtx: { queue, namespace, task, group }
+      }).finally(async () => {
+        if (supervision && --supervision.running === 0) await supervision.stop()
       }))
     }
 
+    supervision?.start()
     logger.log('ConsumerManager.start', { status: 'workers-started', count: concurrency })
 
     // Wait for all workers to complete

package/client-v2/consumer/Supervision.js

@@ -0,0 +1,78 @@
+import { randomBytes } from 'node:crypto'
+import { hostname } from 'node:os'
+import * as logger from '../utils/logger.js'
+
+// One opt-in reporter per consume invocation. Handler calls are not ACKs.
+export class Supervision {
+  constructor(http, config, options) {
+    if (!config || typeof config !== 'object' || typeof config.group !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/.test(config.group) || config.group === 'coordination' || /[\r\n]/.test(config.group)) throw new Error('supervision.group must be a valid application/deployment name')
+    if (!Number.isInteger(options.concurrency) || options.concurrency < 1 || options.concurrency > 4096) throw new Error('supervision requires concurrency between 1 and 4096')
+    this.http = http
+    this.options = options
+    this.group = config.group
+    this.id = randomBytes(16).toString('hex')
+    this.started = Date.now()
+    this.monotonic = performance.now()
+    this.running = this.completed = this.failed = this.sequence = 0
+    this.last = this.pending = this.timer = null
+    this.active = new Map()
+    this.state = 'running'
+    this.warned = false
+  }
+  wrap(handler) {
+    return async (...args) => {
+      const id = this.sequence++
+      this.active.set(id, performance.now())
+      try { const result = await handler(...args); this.completed++; return result }
+      catch (error) { this.failed++; throw error }
+      finally { this.active.delete(id); this.last = Math.floor(Date.now() / 1000) }
+    }
+  }
+  start() {
+    this.publish()
+    this.timer = setInterval(() => this.publish(), 10_000)
+    this.timer.unref()
+  }
+  document() {
+    const now = performance.now()
+    return {
+      schema: 'queen.consumer.status/v1', instance_id: this.id, engine: 'js', execution_model: 'async-tasks',
+      hostname: hostname(), pid: process.pid, state: this.state, updated_at_epoch: Math.floor(Date.now() / 1000),
+      started_at_epoch: Math.floor(this.started / 1000), uptime_seconds: Math.floor((now - this.monotonic) / 1000),
+      configuration: { heartbeat_timeout: 30 },
+      pool_status: [{ name: 'consumer', queue: this.options.queue || null, namespace: this.options.namespace || null,
+        task: this.options.task || null, consumer_group: this.options.group || '__QUEUE_MODE__',
+        desired: this.options.concurrency, running: this.running, busy: this.active.size,
+        completed: this.completed, failed: this.failed, last_completed_at_epoch: this.last,
+        oldest_inflight_seconds: this.active.size ? Math.floor((now - Math.min(...this.active.values())) / 1000) : null }],
+    }
+  }
+  publish() {
+    if (this.pending) return this.pending
+    this.pending = this.send().finally(() => { this.pending = null })
+    return this.pending
+  }
+  async send() {
+    try {
+      const bytes = Buffer.from(JSON.stringify(this.document()))
+      if (bytes.length > 45_000) throw new Error('Consumer status exceeds one chunk')
+      const write = randomBytes(16).toString('hex'), slot = `${this.group}/${this.id}`
+      const ops = [
+        { op: 'put', ns: 'queen-supervisor', key: `${slot}/head`, value: { format: 'queen.supervisor.remote-status/v1', write, chunks: 1, bytes: bytes.length }, ttlSeconds: 60 },
+        { op: 'put', ns: 'queen-supervisor', key: `${slot}/chunk/0000`, value: { write, index: 0, data: bytes.toString('base64') }, ttlSeconds: 60 },
+      ]
+      const result = await this.http.post('/api/v1/kv', { operations: ops }, 2000, null, null, AbortSignal.timeout(2000))
+      if (!Array.isArray(result?.results) || result.results.length !== 2 || result.results.some(r => r.applied !== true)) throw new Error('Consumer status publication was not applied')
+      this.warned = false
+    } catch {
+      if (!this.warned) logger.warn('Consumer.supervision', 'Status publication failed; consumption continues')
+      this.warned = true
+    }
+  }
+  async stop() {
+    clearInterval(this.timer)
+    if (this.pending) await this.pending
+    this.state = 'stopped'
+    await this.publish()
+  }
+}

package/client-v2/http/HttpClient.js

@@ -611,8 +611,8 @@ export class HttpClient {
     return this.#requestWithFailover('GET', path, null, requestTimeoutMillis, affinityKey, retryKind, signal)
   }
 
-  async post(path, body = null, requestTimeoutMillis = null, affinityKey = null, retryKind = null) {
-    return this.#requestWithFailover('POST', path, body, requestTimeoutMillis, affinityKey, retryKind)
+  async post(path, body = null, requestTimeoutMillis = null, affinityKey = null, retryKind = null, signal = null) {
+    return this.#requestWithFailover('POST', path, body, requestTimeoutMillis, affinityKey, retryKind, signal)
   }
 
   async put(path, body = null, requestTimeoutMillis = null, affinityKey = null, retryKind = null) {

package/client-v2/index.js

@@ -16,6 +16,11 @@
 
 export { Queen } from './Queen.js'
 export { Admin } from './admin/Admin.js'
+// Locks and semaphores. Reached as `queen.lock()`, `queen.semaphore()` and
+// `queen.locks`; the classes are exported for typing. `LOCK_NOT_HELD` is the
+// `.code` of the error a guard throws for a handle that holds nothing, and of
+// the reason `lock.signal` aborts with.
+export { Lock, Locks, LOCK_NOT_HELD } from './locks/Locks.js'
 // RAM-class queues (EPHEMERAL_QUEUES.md §4). Reached as `queen.ephemeral`; the
 // class is exported for typing and for embedding it on a client of your own.
 // The two `.code`s the family's 404s carry, which are NOT the same fact:

package/client-v2/kv/Kv.js

@@ -152,6 +152,21 @@ export const kvOp = {
     if (opts.min !== undefined) base.min = opts.min
     if (opts.max !== undefined) base.max = opts.max
     return { base: withRequired(base, opts), expiry: opts }
+  },
+
+  check(ns, key, opts = {}) {
+    requireName(ns, 'ns')
+    requireName(key, 'key')
+    // A check IS its expect. One without says nothing, and the broker's
+    // `applied:true` to it would read as a guard that held.
+    if (!('expect' in opts)) {
+      throw new Error(
+        'kv: check needs `expect` — the version the key must be at, or 0 for a key that must not exist'
+      )
+    }
+    const base = { op: 'check', ns, key }
+    // No expiry: it writes nothing.
+    return { base: withRequired(withExpect(base, opts), opts), expiry: null }
   }
 }
 
@@ -408,6 +423,32 @@ export class Kv {
     return res
   }
 
+  /**
+   * Is the key still at this version? Writes nothing.
+   *
+   *     const r = await kv.check('orders', '9137', { expect: row.version })
+   *     if (!r.applied) console.log(r.reason, r.value)   // somebody wrote since
+   *
+   * `expect: 0` asks the opposite: the key must not exist. A WriteResult like
+   * every write's, `applied` being "the precondition held"; when it did not,
+   * `reason` (`version`, `absent` or `exists`), `value` and `version` are what
+   * a reader would see.
+   *
+   * On its own it is a linearizable look. Where it earns its place is beside
+   * writes, with `required: true`: in a batch, or in a transaction's
+   * `.kv.check(...)`, it makes everything else commit only if a key the call
+   * does not write is unchanged — which is how a step is tied to a lock
+   * (`queen.lock`).
+   *
+   * Needs a broker at cluster version 5, the first with this operation. While
+   * a cluster is being upgraded to it the call answers 503
+   * `kv_check_needs_cluster_version_5`; an older broker answers 400
+   * `kv_unknown_op`.
+   */
+  async check(ns, key, opts = {}) {
+    return this.#write(kvOp.check(ns, key, opts))
+  }
+
   /**
    * The idempotency marker, written the way it is actually used:
    *