velocious 1.0.720 → 1.0.722

package/build/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/build/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/build/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/build/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/build/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/build/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/build/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.

package/build/routes/basic-route.js

@@ -6,10 +6,11 @@ export default class VelociousBasicRoute extends BaseRoute {
   /**
    * Runs get.
    * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    */
-  get(name) {
+  get(name, options = {}) {
     const GetRoute = VelociousBasicRoute.GetRouteType
-    const route = new GetRoute({name})
+    const route = new GetRoute({name, ...options})
 
     this.routes.push(route)
   }
@@ -51,35 +52,59 @@ export default class VelociousBasicRoute extends BaseRoute {
 
   /**
    * Runs namespace.
-   * @param {string} name - Name.
-   * @param {(arg: import("./namespace-route.js").default) => void} callback - Callback function.
+   * @param {string} name - Route name.
+   * @param {{skipControllerConnections?: boolean} | ((arg: import("./namespace-route.js").default) => void)} [options] - Namespace options (`skipControllerConnections: true` skips the request-scoped controller connection for every route declared inside this namespace; a per-route option still overrides it) 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) {
+  namespace(name, options = {}, callback) {
     const NamespaceRoute = VelociousBasicRoute.NameSpaceRouteType
 
     if (!NamespaceRoute) throw new Error("No NamespaceRoute registered")
 
+    // Backward compatible: the second argument may be the draw callback.
+    if (typeof options === "function") {
+      callback = options
+      options = {}
+    }
+
+    const namespaceOptions = /** @type {{skipControllerConnections?: boolean}} */ (options)
+    const skipControllerConnections = namespaceOptions.skipControllerConnections === true
+
     const route = new NamespaceRoute({name})
 
     this.routes.push(route)
 
     if (callback) {
+      const originalGet = route.get.bind(route)
+      const originalPost = route.post.bind(route)
+
+      route.get = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalGet(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
+      route.post = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalPost(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
       callback(route)
     }
   }
 
   /**
    * Runs post.
-   * @param {string} name - Name.
+   * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    * @returns {void} - No return value.
    */
-  post(name) {
+  post(name, options = {}) {
     const PostRoute = VelociousBasicRoute.PostRouteType
 
     if (!PostRoute) throw new Error("No PostRoute registered")
 
-    const route = new PostRoute({name})
+    const route = new PostRoute({name, ...options})
 
     this.routes.push(route)
   }

package/build/routes/get-route.js

@@ -28,16 +28,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRouteGetRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected get route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {

package/build/routes/post-route.js

@@ -27,16 +27,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRoutePostRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected post route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {

package/build/routes/resolver.js

@@ -92,10 +92,12 @@ export default class VelociousRoutesResolver {
     }
 
     const routeResolverHookMatch = await this.resolveRouteResolverHooks(currentPath, {hasMatchingCustomRoute})
-    let skipControllerConnections = this.configuration.database === false || routeResolverHookMatch?.skipControllerConnections === true
+    const matchResult = routeResolverHookMatch || !currentRoute ? undefined : this.matchPathWithRoutes(currentRoute, currentPath)
+    let skipControllerConnections = this.configuration.database === false
+      || routeResolverHookMatch?.skipControllerConnections === true
+      || matchResult?.skipControllerConnections === true
     let skipAbilityResolution = routeResolverHookMatch?.skipAbilityResolution === true
     let skipTenantResolution = routeResolverHookMatch?.skipTenantResolution === true
-    const matchResult = routeResolverHookMatch || !currentRoute ? undefined : this.matchPathWithRoutes(currentRoute, currentPath)
     const actionParam = this.params.action
     const controllerParam = this.params.controller
     const actionValue = typeof actionParam == "string" ? actionParam : (Array.isArray(actionParam) ? actionParam[0] : undefined)
@@ -272,7 +274,7 @@ export default class VelociousRoutesResolver {
    * Runs match path with routes.
    * @param {import("./base-route.js").default} route - Route.
    * @param {string} path - Path.
-   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   * @returns {{restPath: string, skipControllerConnections?: boolean} | undefined} - REST path metadata for this route, including the matched leaf route's options.
    */
   matchPathWithRoutes(route, path) {
     const pathWithoutSlash = path.replace(/^\//, "").split("?")[0]