queen-mq 2.0.4 → 2.3.0

package/README.md

@@ -229,7 +229,11 @@ const queen = new Queen({
   timeoutMillis: 30000,
   retryAttempts: 3,
   loadBalancingStrategy: 'affinity',  // or 'round-robin', 'session'
-  enableFailover: true
+  enableFailover: true,
+  // Opt-in wire forms, off by default (see Binary Push, Push Compression and Framed Pop)
+  binaryPush: false,
+  pushCompression: false,
+  framedPop: false
 })
 ```
 
@@ -515,6 +519,54 @@ rate, and a broker outage shows up as slow pushes with bounded memory rather
 than as messages that quietly disappeared. `close()` flushes with a 30 second
 deadline and logs how many messages were left unsent if it expires.
 
+### Binary Push, Push Compression and Framed Pop
+
+Three opt-in forms of the push, pop and transaction requests. They change how
+the messages travel between the client and the broker and nothing else: the
+calls, their results, deduplication and the delivery guarantees stay the same.
+All three are off by default, and with them off the client sends and reads the
+JSON every broker knows.
+
+```javascript
+const queen = new Queen({
+  url: 'http://localhost:6632',
+  binaryPush: true,       // a push travels as a binary body
+  pushCompression: true,  // with binaryPush: framed and compressed here
+  framedPop: true         // a pop returns the stored records, unpacked here
+})
+```
+
+| Option | What it does |
+| --- | --- |
+| `binaryPush` | A push, direct or buffered, sends its items as one length-prefixed binary body instead of a JSON document. The answer is the same list, one entry per item. |
+| `pushCompression` | Needs `binaryPush`. The client frames each partition's batch the way the broker stores it, mints the message ids (UUIDv7) and compresses the batch with zstd, once. The broker checks the frames and, when it has nothing to add to them, stores those bytes without compressing them again. A transaction that pushes sends its pushes the same way, with the rest of the bundle as JSON in front of them. |
+| `framedPop` | `pop()` and `consume()` ask for the stored records (`frames=true`) and unpack them here into the same message objects, instead of a JSON answer that the broker renders message by message. |
+
+Turn them on when the broker's CPU or the network limits a high message rate:
+the framing, the compression and the unpacking then run in the clients, and the
+batches cross the network compressed. zstd is the one of Node.js (`node:zlib`),
+so there is nothing to install.
+
+**What stays JSON**, with no action from you:
+
+- A push with a `traceId` on one of its items.
+- A transaction with no push, or with a `traceId` on one of its pushes.
+- A pop the broker cannot answer in frames: a pop of a conflating group, and
+  every pop on a broker that runs with an encryption key
+  (`QUEEN_ENCRYPTION_KEY`). The client reads the JSON answer as always.
+- Acks, KV, timers, locks and the admin calls. Ephemeral queues have their own
+  routes and do not change either.
+
+A transaction's `results` come back in the order you added the operations, as
+with JSON. The broker answers a binary transaction with the acks first and the
+pushes after them, and the client puts them back.
+
+**Requires broker 2.3.0 or later** for `binaryPush` and `pushCompression`.
+A broker up to 2.2.0 answers 400 to the binary bodies and the client does not
+fall back to JSON, so turn the two on after every broker of the cluster is
+upgraded. `framedPop` is safe against any broker: an older one ignores the
+parameter and answers JSON.
+
 ### Dead Letter Queue
 
 ```javascript
@@ -636,6 +688,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
 
@@ -954,7 +1049,10 @@ await queen.close()  // Flush buffers and close connections
   loadBalancingStrategy: 'affinity',   // 'affinity' | 'round-robin' | 'session'
   affinityHashRing: 128,
   enableFailover: true,
-  healthRetryAfterMillis: 5000
+  healthRetryAfterMillis: 5000,
+  binaryPush: false,                   // a push as a binary body
+  pushCompression: false,              // with binaryPush: frames compressed in the client
+  framedPop: false                     // a pop as the stored records
 }
 ```
 
@@ -1095,6 +1193,41 @@ Each consume invocation publishes its own instance into the broker's
 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

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
@@ -177,7 +179,7 @@ export class Queen {
   }
 
   #createHttpClient() {
-    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, affinityHashRing, healthRetryAfterMillis, enableFailover, bearerToken, headers, hostHeader, retry429 } = this.#config
+    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, affinityHashRing, healthRetryAfterMillis, enableFailover, bearerToken, headers, hostHeader, retry429, binaryPush, pushCompression, framedPop } = this.#config
 
     if (urls.length === 1) {
       // Single server
@@ -189,7 +191,10 @@ export class Queen {
         bearerToken,
         headers,
         hostHeader,
-        retry429
+        retry429,
+        binaryPush,
+        pushCompression,
+        framedPop
       })
     }
 
@@ -207,7 +212,10 @@ export class Queen {
       bearerToken,
       headers,
       hostHeader,
-      retry429
+      retry429,
+      binaryPush,
+      pushCompression,
+      framedPop
     })
   }
 
@@ -298,6 +306,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 +795,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/README.md

@@ -20,6 +20,7 @@ Welcome to Queen client! This is your friendly guide to mastering message queues
 - [Part 12: Message Tracing - Debug Your Workflows](#part-12-message-tracing---debug-your-workflows)
 - [Part 13: Callbacks & Error Handling](#part-13-callbacks--error-handling)
 - [Part 14: Graceful Shutdown](#part-14-graceful-shutdown)
+- [Part 15: Binary Push, Compression & Framed Pop](#part-15-binary-push-compression--framed-pop)
 - [Cheat Sheet](#cheat-sheet)
 
 ---
@@ -1607,6 +1608,67 @@ await queen.close()
 
 ---
 
+## Part 15: Binary Push, Compression & Framed Pop
+
+Everything so far travels as JSON. For a high message rate, the client has three
+opt-in forms of the push, pop and transaction requests. They change how the
+messages travel and nothing else: your calls, their results, deduplication and
+the delivery guarantees stay the same. All three are off by default.
+
+```javascript
+const queen = new Queen({
+  url: 'http://localhost:6632',
+  binaryPush: true,       // a push travels as a binary body
+  pushCompression: true,  // with binaryPush: framed and compressed here
+  framedPop: true         // a pop returns the stored records, unpacked here
+})
+
+// The rest of your code does not change.
+await queen.queue('events').partition('device-7').push([{ data: { n: 1 } }])
+await queen.queue('events').group('workers').consume(async (message) => {
+  console.log(message.data)
+})
+```
+
+### What Each Option Does
+
+| Option | What it does |
+| --- | --- |
+| `binaryPush` | A push, direct or buffered, sends its items as one length-prefixed binary body instead of a JSON document. The answer is the same list, one entry per item. |
+| `pushCompression` | Needs `binaryPush`. The client frames each partition's batch the way the broker stores it, mints the message ids (UUIDv7) and compresses the batch with zstd, once. The broker checks the frames and, when it has nothing to add to them, stores those bytes without compressing them again. A transaction that pushes sends its pushes the same way, with the rest of the bundle as JSON in front of them. |
+| `framedPop` | `pop()` and `consume()` ask for the stored records (`frames=true`) and unpack them here into the same message objects, instead of a JSON answer that the broker renders message by message. |
+
+Turn them on when the broker's CPU or the network limits a high message rate:
+the framing, the compression and the unpacking then run in the clients, and the
+batches cross the network compressed. zstd is the one of Node.js (`node:zlib`),
+so there is nothing to install.
+
+### What Stays JSON
+
+The client falls back by itself in these cases:
+
+- A push with a `traceId` on one of its items.
+- A transaction with no push, or with a `traceId` on one of its pushes.
+- A pop the broker cannot answer in frames: a pop of a conflating group, and
+  every pop on a broker that runs with an encryption key
+  (`QUEEN_ENCRYPTION_KEY`). The client reads the JSON answer as always.
+- Acks, KV, timers, locks and the admin calls. Ephemeral queues have their own
+  routes and do not change either.
+
+A transaction's `results` come back in the order you added the operations, as
+with JSON. The broker answers a binary transaction with the acks first and the
+pushes after them, and the client puts them back.
+
+### Which Broker
+
+`binaryPush` and `pushCompression` need broker 2.3.0 or later. A broker up
+to 2.2.0 answers 400 to the binary bodies and the client does not fall back to
+JSON, so turn the two on after every broker of the cluster is upgraded.
+`framedPop` is safe against any broker: an older one ignores the parameter and
+answers JSON.
+
+---
+
 ## Cheat Sheet
 
 ### Connection
@@ -1883,7 +1945,10 @@ await queen.close()
   loadBalancingStrategy: 'affinity',     // 'affinity' | 'round-robin' | 'session'
   affinityHashRing: 128,
   enableFailover: true,
-  healthRetryAfterMillis: 5000
+  healthRetryAfterMillis: 5000,
+  binaryPush: false,                     // a push as a binary body
+  pushCompression: false,                // with binaryPush: frames compressed in the client
+  framedPop: false                       // a pop as the stored records
 }
 ```
 

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).