velocious 1.0.720 → 1.0.722

package/build/sync/sync-websocket-channel.js

@@ -2,10 +2,53 @@
 
 import VelociousWebsocketChannel from "../http-server/websocket-channel.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
+import {cursorFromSyncEntry, isCursorAfter} from "./sync-cursor.js"
+import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
 
 /** Configurations whose framework sync channel has already been registered. */
 const registeredConfigurations = new WeakSet()
 
+/** Default catch-up replay page size when the subscriber sends no `limit` param. */
+const DEFAULT_REPLAY_LIMIT = 1000
+
+/**
+ * Serializes a cursor into the change-feed request params under the given prefix.
+ * @param {"after" | "upTo"} prefix - Request field prefix.
+ * @param {import("./sync-api-client-types.js").SyncCursor} cursor - Cursor to serialize.
+ * @returns {Record<string, string | number | null>} Serialized cursor params.
+ */
+function cursorParams(prefix, cursor) {
+  if (!cursor) return {}
+
+  return {
+    [`${prefix}Id`]: cursor.id,
+    ...(cursor.serverSequence !== null ? {[`${prefix}ServerSequence`]: cursor.serverSequence} : {}),
+    [`${prefix}UpdatedAt`]: cursor.updatedAt
+  }
+}
+
+/**
+ * Reads the after-cursor the subscriber declared in its subscribe params, or null
+ * when it sent none (a fresh subscription replays the whole scope).
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Subscribe params.
+ * @returns {import("./sync-api-client-types.js").SyncCursor} Declared after-cursor, or null.
+ */
+function cursorFromParams(params) {
+  const updatedAt = typeof params.afterUpdatedAt === "string" ? params.afterUpdatedAt : null
+
+  if (!updatedAt) return null
+
+  const serverSequence = params.afterServerSequence === null || params.afterServerSequence === undefined
+    ? null
+    : Number(params.afterServerSequence)
+
+  return {
+    id: params.afterId === null || params.afterId === undefined ? null : String(params.afterId),
+    serverSequence,
+    updatedAt
+  }
+}
+
 /**
  * Framework-owned websocket channel for synced resources
  * ({@link VELOCIOUS_SYNC_CHANNEL}).
@@ -25,6 +68,14 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
    */
   _scope = null
 
+  /**
+   * Cursor of the last sync entry delivered to this subscription, advanced by
+   * live broadcasts and catch-up replay so a resume replays only the rows missed
+   * while the socket was down.
+   * @type {import("./sync-api-client-types.js").SyncCursor}
+   */
+  _deliveredCursor = null
+
   /**
    * Registers the framework sync channel on a configuration declaring a
    * `sync.api` block (guarded so repeated server boots with the same
@@ -169,13 +220,17 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
   async deliverBroadcast(body, meta) {
     if (!this._isUserScope()) {
       this.sendMessage(body, meta)
+      this._trackDeliveredCursor(body)
 
       return
     }
 
     const deliverableBody = await this._userScopeDeliverableBody(body)
 
-    if (deliverableBody !== null) this.sendMessage(deliverableBody, meta)
+    if (deliverableBody !== null) {
+      this.sendMessage(deliverableBody, meta)
+      this._trackDeliveredCursor(deliverableBody)
+    }
   }
 
   /**
@@ -245,6 +300,103 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
     return deliverableSyncs[0]
   }
 
+  /**
+   * Replays the catch-up backlog to this subscriber once its subscription is
+   * authorized: pages the scoped change feed from the cursor the client declared
+   * in its subscribe params and sends each page as a standard sync envelope, then
+   * live broadcasts continue from there. A fresh subscription with no cursor
+   * replays the whole authorized scope.
+   * @returns {Promise<void>}
+   */
+  async subscribed() {
+    if (!this._scope) return
+
+    await this._replayFrom(cursorFromParams(this.params))
+  }
+
+  /**
+   * Replays rows missed while the socket was down, resuming from the cursor of
+   * the last entry this subscription delivered instead of re-reading the whole
+   * scope from the subscribe-time cursor.
+   * @returns {Promise<void>}
+   */
+  async onResume() {
+    if (!this._scope) return
+
+    await this._replayFrom(this._deliveredCursor ?? cursorFromParams(this.params))
+  }
+
+  /**
+   * Pages the scoped change feed from a cursor and delivers each page to this
+   * subscriber as a `{echoOrigin, syncs}` envelope. The snapshot high-water is
+   * resolved once and pinned across pages so rows arriving mid-replay are left to
+   * the live broadcast path instead of looping the replay. The delivered cursor
+   * advances so a later resume resumes from here.
+   * @param {import("./sync-api-client-types.js").SyncCursor} afterCursor - Cursor to replay after.
+   * @returns {Promise<void>}
+   */
+  async _replayFrom(afterCursor) {
+    const configuration = this.session.configuration
+    const scope = this._scope
+
+    await configuration.ensureConnections({name: `${VELOCIOUS_SYNC_CHANNEL} catch-up replay`}, async () => {
+      const resource = await this.buildSyncResource()
+      const limit = this._replayLimit(resource)
+      /** @type {import("./sync-api-client-types.js").SyncCursor} */
+      let upToCursor = null
+
+      while (true) {
+        const page = await resource.changeFeedService({
+          params: {...this.params, ...cursorParams("after", afterCursor), ...(upToCursor ? cursorParams("upTo", upToCursor) : {})},
+          scope
+        }).changes()
+
+        if (!upToCursor) upToCursor = page.upToCursor
+
+        if (page.syncs.length === 0) break
+
+        await this.deliverBroadcast({echoOrigin: null, syncs: page.syncs})
+
+        afterCursor = page.nextCursor
+        if (afterCursor) this._deliveredCursor = afterCursor
+
+        if (page.syncs.length < limit) break
+      }
+    })
+  }
+
+  /**
+   * Resolves the catch-up replay page size from the subscriber's `limit` param
+   * (defaulting to {@link DEFAULT_REPLAY_LIMIT}).
+   * @param {import("./sync-resource-base.js").default} resource - Authorizing sync resource.
+   * @returns {number} Replay page size.
+   */
+  _replayLimit(resource) {
+    return new SyncModelChangeFeedService({modelClass: resource.syncModelClass(), params: this.params}).normalizedLimit(this.params.limit)
+  }
+
+  /**
+   * Advances the delivered-cursor watermark from a delivered envelope so a resume
+   * resumes after the newest row actually sent to this subscriber. Broadcasts may
+   * arrive out of order across resources, so each entry only advances the
+   * watermark when it is later than the current one.
+   * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} body - Delivered envelope.
+   * @returns {void}
+   */
+  _trackDeliveredCursor(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) return
+
+    const envelope = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (body)
+    const syncs = Array.isArray(envelope.syncs) ? envelope.syncs : [envelope]
+
+    for (const entry of syncs) {
+      const syncEntry = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (entry)
+      const cursor = cursorFromSyncEntry(syncEntry)
+
+      if (cursor && isCursorAfter(cursor, this._deliveredCursor)) this._deliveredCursor = cursor
+    }
+  }
+
   /**
    * Returns the authorized scope for debug snapshots.
    * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.720",
+  "version": "1.0.722",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/main.js

@@ -9,7 +9,7 @@ import Logger from "../logger.js"
 import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jobs.js"
 import VelociousError from "../velocious-error.js"
 import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
-import { validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
+import { parseGenerationWorkerId, validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
 import BackgroundJobsLifecycleControlServer from "./lifecycle-control-server.js"
 
 /**
@@ -40,6 +40,8 @@ const WORKER_LIVENESS_SWEEP_MS = 15000
 /** Grace for workers from the previous main generation to reconnect and adopt leases. */
 const WORKER_RECONNECT_GRACE_MS = 30000
 const GENERATION_ORPHANED_AFTER_MS = 60 * 60 * 1000
+/** Prefix of the per-generation liveness advisory lock one live main holds for its whole generation. */
+const GENERATION_LIVENESS_LOCK_PREFIX = "background-jobs:generation-liveness"
 const WORKER_RECONNECT_GRACE_VALIDATION_MESSAGE = `workerReconnectGraceMs must be an integer between 0 and ${MAX_TIMER_MS}`
 
 /**
@@ -246,6 +248,11 @@ export default class BackgroundJobsMain {
     this._beaconClient = undefined
     /** @type {BackgroundJobsLifecycleControlServer | undefined} */
     this.lifecycleControlServer = undefined
+    /**
+     * Dedicated advisory-lock connection holding this main's generation liveness
+     * lock for the whole lifetime of the main (generation mode only).
+     * @type {import("../database/drivers/base.js").default | undefined} */
+    this._livenessLockConnection = undefined
   }
 
   /**
@@ -296,6 +303,7 @@ export default class BackgroundJobsMain {
       if (this.generationId && !this.adapter.supportsOwnedEnqueueFromHandoff()) {
         throw new Error("The configured background jobs adapter does not support atomic owned-handoff enqueue")
       }
+      if (this.generationId) await this._acquireGenerationLivenessLock()
 
       if (!this.generationId || this.initialGenerationState !== "candidate") {
         this.startupHandoffSnapshot = await this._generationOwnedHandoffSnapshot()
@@ -389,7 +397,11 @@ export default class BackgroundJobsMain {
               try {
                 await this._drainStartupHandoffReclaim()
               } finally {
-                await this._stopBeaconAndServer()
+                try {
+                  await this._releaseGenerationLivenessLock()
+                } finally {
+                  await this._stopBeaconAndServer()
+                }
               }
             }
           }
@@ -624,6 +636,7 @@ export default class BackgroundJobsMain {
     }
     this.lifecycleState = "active"
     this._creditReadyWorkers()
+    await this._settleForeignGenerationHandoffs()
     this.logger.info(() => ["Background jobs generation activation acknowledged", {generationId: this.generationId}])
     void this._drain().catch((error) => {
       this.logger.error(() => ["Background jobs generation post-activation drain failed", {error, generationId: this.generationId}])
@@ -751,6 +764,154 @@ export default class BackgroundJobsMain {
    * retained solely to perform this cleanup.
    * @returns {void}
    */
+  /**
+   * Builds the per-generation liveness advisory-lock name for one generation on
+   * this main's background-jobs database. A live main holds this lock for its
+   * whole lifetime; a foreign generation whose lock is free (or stale) has no
+   * live main supervising its durable handoffs.
+   * @param {string} generationId - Generation to name.
+   * @returns {string} - Lock name.
+   */
+  _generationLivenessLockName(generationId) {
+    const databaseIdentifier = this.configuration.getBackgroundJobsConfig().databaseIdentifier || "default"
+
+    return `${GENERATION_LIVENESS_LOCK_PREFIX}:${databaseIdentifier}:${generationId}`
+  }
+
+  /**
+   * Acquires this main's own generation liveness lock on a dedicated connection
+   * it holds until stop. Contention means a still-live main of the same
+   * generation exists (a deploy anomaly); the main keeps running without the
+   * marker and cross-generation settlement conservatively leaves its rows to it.
+   * @returns {Promise<void>} - Resolves after the marker is held or degraded.
+   */
+  async _acquireGenerationLivenessLock() {
+    if (!this.generationId || this._livenessLockConnection) return
+    const lockName = this._generationLivenessLockName(this.generationId)
+
+    try {
+      const connection = await this.configuration.getDatabasePool(this._livenessLockDatabaseIdentifier()).spawnConnection()
+      const acquired = await connection.tryAcquireAdvisoryLock(lockName)
+
+      if (!acquired) {
+        await connection.close()
+        this.logger.warn(() => ["Background jobs generation liveness lock is already held by another live main of this generation", {generationId: this.generationId}])
+
+        return
+      }
+
+      this.configuration.registerAdvisoryLockConnection(connection)
+      this._livenessLockConnection = connection
+    } catch (error) {
+      this.logger.warn(() => ["Failed to acquire background jobs generation liveness lock", {error, generationId: this.generationId}])
+    }
+  }
+
+  /**
+   * Releases this main's generation liveness marker during stop so a later
+   * generation activation can prove this generation is gone. Closing the
+   * dedicated connection releases the advisory lock on every tier.
+   * @returns {Promise<void>} - Resolves after the marker is released.
+   */
+  async _releaseGenerationLivenessLock() {
+    const connection = this._livenessLockConnection
+
+    this._livenessLockConnection = undefined
+    if (!connection) return
+
+    this.configuration.unregisterAdvisoryLockConnection(connection)
+
+    try {
+      await connection.releaseHeldAdvisoryLocks()
+    } finally {
+      await connection.close()
+    }
+  }
+
+  /**
+   * Database identifier whose pools carry the generation liveness locks. This
+   * matches the built-in store's own resolution of the background-jobs config.
+   * @returns {string} - Database identifier.
+   */
+  _livenessLockDatabaseIdentifier() {
+    return this.configuration.getBackgroundJobsConfig().databaseIdentifier || "default"
+  }
+
+  /**
+   * One activation event: snapshot all durable handoffs, group the rows whose
+   * worker identity belongs to a foreign generation, and settle each group only
+   * after proving that generation has no live main (its liveness lock is free).
+   * Own-generation rows, identity-free legacy rows, and rows of live foreign
+   * generations stay owned by their existing recovery paths. Failures are
+   * reported as framework errors and never fail activation.
+   * @returns {Promise<void>} - Resolves after settlement or its reported failure.
+   */
+  async _settleForeignGenerationHandoffs() {
+    if (!this.generationId) return
+
+    try {
+      const handoffs = await this.store.snapshotHandedOffJobs()
+      /** @type {Map<string, import("./types.js").BackgroundJobHandoffSnapshot[]>} */
+      const handoffsByForeignGeneration = new Map()
+
+      for (const handoff of handoffs) {
+        const parsed = parseGenerationWorkerId(handoff.workerId)
+        if (!parsed || parsed.generationId === this.generationId) continue
+
+        const group = handoffsByForeignGeneration.get(parsed.generationId) || []
+        group.push(handoff)
+        handoffsByForeignGeneration.set(parsed.generationId, group)
+      }
+
+      for (const [foreignGenerationId, foreignHandoffs] of handoffsByForeignGeneration) {
+        const settledJobs = await this._settleForeignGenerationHandoffGroup({foreignGenerationId, handoffs: foreignHandoffs})
+
+        if (settledJobs.length > 0) await this._handleOrphanedJobs({jobs: settledJobs, warning: "Marked orphaned background jobs whose generation was retired before this generation activated"})
+      }
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      const payload = {context: {generationId: this.generationId, stage: "background-job-activation-cross-generation-settlement"}, error: normalizedError}
+      const errorEvents = this.configuration.getErrorEvents()
+
+      this.logger.error(() => ["Failed to settle foreign-generation handoffs at activation:", normalizedError])
+      errorEvents.emit("framework-error", payload)
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    }
+  }
+
+  /**
+   * Settles one foreign generation's exact handoffs under a proof of absence:
+   * acquire that generation's liveness lock on a dedicated connection and hold
+   * it across the fenced store transition. A busy lock means a live main of
+   * that generation still supervises its rows (retired-and-draining included),
+   * so nothing here may touch them.
+   * @param {object} args - Options.
+   * @param {string} args.foreignGenerationId - Generation whose rows are candidates.
+   * @param {import("./types.js").BackgroundJobHandoffSnapshot[]} args.handoffs - Exact snapshot rows.
+   * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - Accepted orphan transitions.
+   */
+  async _settleForeignGenerationHandoffGroup({foreignGenerationId, handoffs}) {
+    const lockName = this._generationLivenessLockName(foreignGenerationId)
+    const connection = await this.configuration.getDatabasePool(this._livenessLockDatabaseIdentifier()).spawnConnection()
+
+    try {
+      const acquired = await connection.tryAcquireAdvisoryLock(lockName)
+
+      if (!acquired) return []
+
+      return await this.store.markOrphanedHandoffs({
+        error: "Job orphaned when a new generation activated while its owning generation was not live",
+        handoffs
+      })
+    } finally {
+      try {
+        await connection.releaseHeldAdvisoryLocks()
+      } finally {
+        await connection.close()
+      }
+    }
+  }
+
   _setupStartupHandoffReclaim() {
     if (this.startupHandoffSnapshot.length === 0) return
     if (this._startupHandoffReclaimTimer || this._startupHandoffReclaimPromise || this._startupHandoffGraceElapsed) return
@@ -1156,12 +1317,20 @@ export default class BackgroundJobsMain {
    */
   async _handleClientSocketMessage({jsonSocket, message}) {
     if (this.generationId && (this.lifecycleState === "retiring" || this.lifecycleState === "retired")) {
-      if (message?.type === "enqueue" && !message.producerProof) jsonSocket.send({type: "enqueue-error", error: "Background jobs generation is retired"})
+      // A retiring generation stays a durable enqueue target. Queued rows are
+      // generation-neutral in the shared store and a retiring main never
+      // dispatches them (`_handleEnqueue` only drains while active), so accepted
+      // work stays queued for the active generation - the release lifecycle
+      // contract holds that returned/retried queue work is eligible for the
+      // active generation. Refusing these enqueues strands producers with no
+      // successor endpoint to retry against, such as this main's own recovery
+      // listeners. Schedule ownership is not generation-neutral, so those
+      // operations stay fenced here.
       if (message?.type === "replace-scheduled") jsonSocket.send({type: "replace-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "cancel-scheduled") jsonSocket.send({type: "cancel-scheduled-error", error: "Background jobs generation is retired"})
       if (message?.type === "get-scheduled-job") jsonSocket.send({type: "get-scheduled-job-error", error: "Background jobs generation is retired"})
       if (message?.type === "wake-scheduled") jsonSocket.send({type: "wake-scheduled-error", error: "Background jobs generation is retired"})
-      if (message?.type !== "enqueue" || !message.producerProof) return
+      if (message?.type !== "enqueue") return
     }
 
     if (message?.type === "enqueue") {

package/src/configuration-types.js

@@ -602,7 +602,7 @@
  * @property {() => VelociousSyncRealtimeWebsocketClient | Promise<VelociousSyncRealtimeWebsocketClient>} createClient - Builds the (unconnected) websocket client; the framework owns connect/disconnect.
  * @property {(context: ReturnType<typeof JSON.parse>) => Array<VelociousSyncRealtimeChannelDescriptor> | Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} [channels] - Deprecated legacy escape hatch: resolves extra app-channel descriptors from the `subscribeRealtime(context)` context. Declared pull scopes subscribe the framework sync channel automatically.
  * @property {() => string | Promise<string>} [localOrigin] - Resolves this device's echo origin; pushed messages with a matching `echoOrigin` are dropped.
- * @property {boolean} [pullOnReconnect] - Fire a coalesced `pull()` when subscriptions become ready or resume after a drop, closing offline gaps. Defaults to true.
+ * @property {boolean} [pullOnReconnect] - Deprecated no-op: realtime catch-up now replays the server-side sync cursor on subscribe and resume, so the former pull-on-reconnect no longer fires. Kept so existing app configs still typecheck.
  */
 
 /**

package/src/database/advisory-lock-reentrancy-node.js

@@ -0,0 +1,9 @@
+// @ts-check
+
+import {AsyncLocalStorage} from "node:async_hooks"
+
+import {installAdvisoryLockReentrancyStorage} from "./advisory-lock-reentrancy.js"
+
+// Imported for its side effect by the Node environment handler: only Node has
+// async-context storage, and browser/Expo bundles must never reach this module.
+installAdvisoryLockReentrancyStorage(new AsyncLocalStorage())

package/src/database/advisory-lock-reentrancy.js

@@ -0,0 +1,66 @@
+// @ts-check
+
+/**
+ * Backend provenance of one advisory-lock hold (STC-210 design §3).
+ * @typedef {object} AdvisoryLockBackendProvenance
+ * @property {import("./advisory-lock-backend-policy.js").AdvisoryLockTier} backend - Tier that served the acquisition.
+ * @property {string} [driverType] - Database driver type when the driver tier served it.
+ * @property {number} [epoch] - Fencing epoch when the serving tier issues one.
+ * @property {boolean} fencingSupported - Whether this tier carries fencing tokens (design §8); the file tier reports false rather than pretending.
+ * @property {string} [holderId] - Backend holder id for the file tier.
+ * @property {string} [lockName] - Lock name this provenance belongs to.
+ */
+
+/**
+ * One advisory-lock hold tracked in the current async context.
+ * @typedef {object} HeldAdvisoryLock
+ * @property {number} depth - Nesting depth of the hold.
+ * @property {AdvisoryLockBackendProvenance} lockBackend - Backend that served the outer hold.
+ */
+
+/**
+ * Async-context storage contract for advisory-lock re-entrancy.
+ * @typedef {object} AdvisoryLockReentrancyStorage
+ * @property {() => Map<string, HeldAdvisoryLock> | undefined} getStore - Store for the current async context.
+ * @property {(store: Map<string, HeldAdvisoryLock>, callback: () => ReturnType<typeof JSON.parse>) => ReturnType<typeof JSON.parse>} run - Runs the callback with the store installed.
+ */
+
+/**
+ * This module is imported by browser and Expo bundles, so it must stay free of
+ * Node-only imports. The Node handler installs the real AsyncLocalStorage through
+ * `advisory-lock-reentrancy-node.js`; other runtimes leave it uninstalled and
+ * holds then run without re-entry tracking.
+ * @type {AdvisoryLockReentrancyStorage | undefined}
+ */
+let installedStorage
+
+/**
+ * Installs the runtime's async-context storage. Called once by the Node handler.
+ * @param {AdvisoryLockReentrancyStorage} storage - Storage owned by the runtime.
+ * @returns {void}
+ */
+export function installAdvisoryLockReentrancyStorage(storage) {
+  installedStorage = storage
+}
+
+/**
+ * Returns the locks the current async context holds, when this runtime has
+ * async-context storage.
+ * @returns {Map<string, HeldAdvisoryLock> | undefined} - Current context store.
+ */
+export function advisoryLockReentrancyStore() {
+  return installedStorage?.getStore()
+}
+
+/**
+ * Runs a callback with the store installed as the current context. Runtimes
+ * without async-context storage run the callback directly.
+ * @param {Map<string, HeldAdvisoryLock>} store - Store for the hold being executed.
+ * @param {() => ReturnType<typeof JSON.parse>} callback - Hold work.
+ * @returns {ReturnType<typeof JSON.parse>} - Callback result.
+ */
+export function runWithAdvisoryLockReentrancyStore(store, callback) {
+  if (!installedStorage) return callback()
+
+  return installedStorage.run(store, callback)
+}

package/src/database/advisory-lock-runner.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import {AsyncLocalStorage} from "node:async_hooks"
 import timeout, {TimeoutError} from "awaitery/build/timeout.js"
 import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "./advisory-lock-bound.js"
 import {
@@ -13,19 +12,14 @@ import {
   AdvisoryLockServiceUnavailableError,
   advisoryLockBackendUnavailable
 } from "./advisory-lock-errors.js"
+import {advisoryLockReentrancyStore, runWithAdvisoryLockReentrancyStore} from "./advisory-lock-reentrancy.js"
 import {emitAdvisoryLockFallbackReport} from "./advisory-lock-telemetry.js"
 
 /**
  * Provenance of one advisory-lock acquisition (STC-210 design §3): every
  * held lock reports the tier that actually served it, so a fallback is
  * visible to the callback, in logs, and in `getAdvisoryLockBackendStatus()`.
- * @typedef {object} AdvisoryLockBackendProvenance
- * @property {import("./advisory-lock-backend-policy.js").AdvisoryLockTier} backend - Tier that served the acquisition.
- * @property {string} [driverType] - Database driver type when the driver tier served it.
- * @property {number} [epoch] - Fencing epoch when the serving tier issues one.
- * @property {boolean} fencingSupported - Whether this tier carries fencing tokens (design §8); the file tier reports false rather than pretending.
- * @property {string} [holderId] - Backend holder id for the file tier.
- * @property {string} [lockName] - Lock name this provenance belongs to.
+ * @typedef {import("./advisory-lock-reentrancy.js").AdvisoryLockBackendProvenance} AdvisoryLockBackendProvenance
  */
 
 /**
@@ -78,8 +72,11 @@ class AdvisoryLockBusyError extends Error {
  * `already-held` and treated it as contention. Applications worked around it
  * with hand-passed `*LockHeld` booleans, which is exactly the parameter a
  * monitor makes redundant.
+ *
+ * The storage itself belongs to the environment handler: Node owns async-context
+ * storage, while browser and Expo runtimes have none and therefore hold without
+ * re-entry tracking instead of pulling `node:async_hooks` into their bundles.
  */
-const heldAdvisoryLocks = new AsyncLocalStorage()
 
 /**
  * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
@@ -300,7 +297,7 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async runLockedCallback({callback, holdTimeoutMs, lockBackend, name, release}) {
-    const store = new Map(heldAdvisoryLocks.getStore() ?? [])
+    const store = new Map(advisoryLockReentrancyStore() ?? [])
 
     store.set(this.lockStorageKey(name), {depth: 1, lockBackend})
 
@@ -308,7 +305,7 @@ export default class AdvisoryLockRunner {
       // The lock is released outside the context scope: a release path that
       // touches the same name (a cleanup hook, an error reporter) must not look
       // like a re-entry of a hold that is already over.
-      return await heldAdvisoryLocks.run(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
+      return await runWithAdvisoryLockReentrancyStore(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
     } finally {
       await release()
     }
@@ -320,7 +317,7 @@ export default class AdvisoryLockRunner {
    * @returns {{depth: number, lockBackend: AdvisoryLockBackendProvenance} | null} - The held entry, or null when this context does not hold the lock.
    */
   heldEntryFor(name) {
-    const store = heldAdvisoryLocks.getStore()
+    const store = advisoryLockReentrancyStore()
 
     if (!store) return null
 

package/src/environment-handlers/node.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import "../database/annotations-async-hooks.js"
+import "../database/advisory-lock-reentrancy-node.js"
 import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
 import AdvisoryLockLockServerBackend from "../database/advisory-lock-lock-server-backend.js"
 import Base from "./base.js"

package/src/routes/base-route.js

@@ -109,10 +109,11 @@ export default class VelociousBaseRoute {
    * Runs namespace.
    * @abstract
    * @param {string} name - Name.
-   * @param {(arg: import("./namespace-route.js").default) => void} callback - Callback function.
+   * @param {object | ((arg: import("./namespace-route.js").default) => void)} options - Namespace options or the draw callback (legacy form).
+   * @param {((arg: import("./namespace-route.js").default) => void) | undefined} [callback] - Callback function.
    * @returns {void} - No return value.
    */
-  namespace(name, callback) { throw new Error("'namespace' not implemented") } // eslint-disable-line no-unused-vars
+  namespace(name, options, callback) { throw new Error("'namespace' not implemented") } // eslint-disable-line no-unused-vars
 
   /**
    * Runs post.