velocious 1.0.692 → 1.0.694

package/README.md

@@ -50,6 +50,7 @@
 * AbortSignal-driven MySQL/MariaDB query cancellation for raw, model, and cross-tenant aggregate queries (see [docs/database-query-cancellation.md](docs/database-query-cancellation.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 * Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
+* Built-in MCP server command `velocious mcp` exposing every registered frontend-model command as MCP tools for AI clients, dispatched through the frontend-model controller with the app's own ability resolver (see [docs/mcp-server.md](docs/mcp-server.md))
 * Backend record attachments with filesystem, S3, native callback, bounded Node path-input persistence, and model-declared client sync policy (see [docs/attachments.md](docs/attachments.md))
 
 # Setup
@@ -975,6 +976,10 @@ Frontend-model command transport preserves `Date` and `undefined` by encoding th
 
 Frontend-model commands raise an `Error` when the backend responds with `{status: "error"}` (using `errorMessage` when present), so unauthorized or missing-record update/find/destroy responses fail fast in frontend code.
 
+## Route catch-all
+
+Applications can declare their own 404 response in the routes file with `route.catchAll({action: "notFound", controller: "errors"})` instead of hand-wiring a route resolver hook. Unmatched requests then resolve to the given controller/action through the standard controller lookup, without tenant/ability/connection resolution. See [docs/route-catch-all.md](docs/route-catch-all.md).
+
 ## Route resolver hooks
 
 Libraries can hook unresolved routes and hijack them before Velocious falls back to the built-in 404 controller.

package/build/background-jobs/scheduled-enqueue-bound.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "../database/advisory-lock-bound.js"
+
+/**
+ * Default bound for one scheduled background-job enqueue attempt.
+ *
+ * A durable enqueue that never settles (wedged DB connection, advisory lock held by a dead process)
+ * used to poison its schedule key forever: `BackgroundJobsScheduler` kept the in-flight promise in
+ * `pendingEnqueuesByJobKey`, every later tick returned early, and shutdown could never drain. The
+ * bound makes that stall observable and self-healing instead of silent.
+ *
+ * It is deliberately larger than the advisory-lock acquisition bound, because a scheduled enqueue
+ * waits for a lock *and then* inserts. Keeping the enqueue watchdog outside the lock bound lets the
+ * precise `AdvisoryLockTimeoutError` surface first — naming the lock that is actually stuck —
+ * instead of a generic enqueue timeout that hides which lock caused the stall.
+ * @type {number} */
+export const DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS = DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS + 5 * 60 * 1000

package/build/background-jobs/scheduled-enqueue-timeout-error.js

@@ -0,0 +1,25 @@
+// @ts-check
+
+import {TimeoutError} from "awaitery/build/timeout.js"
+
+/** Typed failure for a scheduled background-job enqueue that never settled within its bound. */
+export default class ScheduledBackgroundJobEnqueueTimeoutError extends TimeoutError {
+  /**
+   * Builds a scheduled-enqueue timeout error without job arguments or connection details.
+   * @param {object} args - Safe timeout context.
+   * @param {string} args.jobKey - Schedule key whose enqueue stalled.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {number} args.scheduledEnqueueTimeoutMs - Configured bound that expired.
+   * @param {TimeoutError} [args.cause] - Original watchdog timeout.
+   */
+  constructor({jobKey, jobName, scheduledEnqueueTimeoutMs, cause}) {
+    super(`Scheduled background job enqueue did not settle within ${scheduledEnqueueTimeoutMs}ms`, cause ? {cause} : undefined)
+
+    this.name = "ScheduledBackgroundJobEnqueueTimeoutError"
+    /** @type {"BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"} */
+    this.code = "BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"
+    this.jobKey = jobKey
+    this.jobName = jobName
+    this.scheduledEnqueueTimeoutMs = scheduledEnqueueTimeoutMs
+  }
+}

package/build/background-jobs/scheduler.js

@@ -1,5 +1,8 @@
 // @ts-check
 
+import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./scheduled-enqueue-bound.js"
+import ScheduledBackgroundJobEnqueueTimeoutError from "./scheduled-enqueue-timeout-error.js"
+
 import Logger from "../logger.js"
 import {nextCronFireDate, parseCronExpression} from "./cron-expression.js"
 
@@ -25,6 +28,12 @@ const DURATION_MULTIPLIERS = {
   weeks: 7 * 24 * 60 * 60 * 1000
 }
 
+// The watchdog below is internal machinery, not a schedule timer. Capturing the
+// platform timers at module load keeps them out of a caller's schedule-timer
+// observation, so bounding an enqueue never appears as an extra scheduled job.
+const armWatchdogTimer = globalThis.setTimeout
+const cancelWatchdogTimer = globalThis.clearTimeout
+
 /**
  * Runs the parseScheduledDuration helper.
  * @param {number | string} value - Duration value.
@@ -73,6 +82,8 @@ export default class BackgroundJobsScheduler {
     this.configuration = configuration
     this.enqueueJob = enqueueJob
     this.logger = new Logger(this)
+    /** @type {number | null} - Bound (ms) for one scheduled enqueue attempt; `null` disables the bound. */
+    this.scheduledEnqueueTimeoutMs = this._resolveScheduledEnqueueTimeoutMs()
     /**
      * Narrows the runtime value to the documented type.
      * @type {Array<ReturnType<typeof setInterval>>} */
@@ -270,17 +281,123 @@ export default class BackgroundJobsScheduler {
       // of identical scheduled jobs when the queue backed up. Dedup is by job identity (see the
       // store), so the job keeps its queue-derived concurrency cap. A schedule can opt out with
       // `deduplicateWhileQueued: false`.
-      await this.enqueueJob({
-        args: Array.isArray(jobConfiguration.args) ? jobConfiguration.args : [],
-        jobClass: jobConfiguration.class,
+      await this._withScheduledEnqueueTimeout({
         jobKey,
-        options: {deduplicateWhileQueued: true, ...(jobConfiguration.options || {})}
+        jobName: jobConfiguration.class.jobName(),
+        run: async () => {
+          await this.enqueueJob({
+            args: Array.isArray(jobConfiguration.args) ? jobConfiguration.args : [],
+            jobClass: jobConfiguration.class,
+            jobKey,
+            options: {deduplicateWhileQueued: true, ...(jobConfiguration.options || {})}
+          })
+        }
       })
     } catch (error) {
+      if (error instanceof ScheduledBackgroundJobEnqueueTimeoutError) {
+        this._reportScheduledEnqueueStall({error, jobKey})
+
+        return
+      }
+
       await this.logger.error(() => ["Failed to enqueue scheduled background job", {jobKey, jobName: jobConfiguration.class.jobName()}, error])
     }
   }
 
+  /**
+   * Runs one durable enqueue attempt under the scheduled-enqueue bound.
+   *
+   * The bound is applied with a local race rather than `awaitery`'s `timeout()`:
+   * that helper starts its callback through `Promise.resolve().then(...)`, which
+   * would defer every scheduled enqueue by a microtask and change the tick
+   * semantics callers rely on. Here the attempt starts synchronously, and the
+   * watchdog uses the module-captured timers so it is never observable as a
+   * schedule timer. Only the watchdog raises the typed timeout error, so a
+   * timeout raised inside the enqueue itself keeps its own error path.
+   * @param {object} args - Options.
+   * @param {string} args.jobKey - Schedule key.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {() => Promise<void>} args.run - Enqueue attempt.
+   * @returns {Promise<void>} - Resolves when the attempt settles within the bound.
+   */
+  async _withScheduledEnqueueTimeout({jobKey, jobName, run}) {
+    const timeoutMs = this.scheduledEnqueueTimeoutMs
+    /** @type {Promise<void>} */
+    let attempt
+
+    try {
+      attempt = Promise.resolve(run())
+    } catch (error) {
+      attempt = Promise.reject(/** @type {Error} */ (error))
+    }
+
+    if (timeoutMs === null) return await attempt
+
+    /**
+     * Rejects the watchdog promise when the bound expires.
+     * @type {(error: Error) => void} */
+    let rejectScheduledEnqueueTimeout = () => {}
+    const watchdog = new Promise((_, reject) => { rejectScheduledEnqueueTimeout = reject })
+    /**
+     * Watchdog timer handle.
+     * @type {ReturnType<typeof armWatchdogTimer>} */
+    const watchdogId = armWatchdogTimer(() => {
+      rejectScheduledEnqueueTimeout(new ScheduledBackgroundJobEnqueueTimeoutError({
+        jobKey,
+        jobName,
+        scheduledEnqueueTimeoutMs: timeoutMs
+      }))
+    }, timeoutMs)
+
+    try {
+      return await Promise.race([attempt, watchdog])
+    } finally {
+      cancelWatchdogTimer(watchdogId)
+    }
+  }
+
+  /**
+   * Surfaces a scheduled enqueue whose store call never settled. Without this report the only
+   * symptom is a schedule that silently stops enqueueing after one wedged call.
+   * @param {object} args - Options.
+   * @param {Error} args.error - Timeout error.
+   * @param {string} args.jobKey - Schedule key.
+   * @returns {void}
+   */
+  _reportScheduledEnqueueStall({error, jobKey}) {
+    const payload = {
+      context: {
+        jobKey,
+        scheduledEnqueueTimeoutMs: this.scheduledEnqueueTimeoutMs,
+        stage: "background-jobs-scheduled-enqueue-stall"
+      },
+      error
+    }
+
+    void this.logger.error(() => ["Scheduled background job enqueue stalled", payload.context, error])
+
+    const errorEvents = typeof this.configuration?.getErrorEvents === "function" ? this.configuration.getErrorEvents() : undefined
+
+    if (!errorEvents) return
+
+    errorEvents.emit("framework-error", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+  }
+
+  /**
+   * Resolves the scheduled-enqueue bound from configuration.
+   * @returns {number | null} - Bound in milliseconds, or `null` for an unbounded wait.
+   */
+  _resolveScheduledEnqueueTimeoutMs() {
+    const backgroundJobsConfig = typeof this.configuration?.getBackgroundJobsConfig === "function" ? this.configuration.getBackgroundJobsConfig() : undefined
+    const configured = backgroundJobsConfig?.scheduledEnqueueTimeoutMs
+
+    if (configured === null) return null
+    if (typeof configured === "number" && configured > 0) return configured
+
+    return DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
+  }
+
   /**
    * Runs normalize every.
    * @param {NonNullable<import("../configuration-types.js").ScheduledBackgroundJobConfiguration["every"]>} every - Every config (caller must guarantee not undefined).

package/build/cli/commands/mcp.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class VelociousCliCommandsMcp extends BaseCommand{
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsMcp(this)
+  }
+}

package/build/cli/index.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--socket", "--tenant"])
+const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--request-context", "--socket", "--tenant"])
 
 export default class VelociousCli {
   /**

package/build/configuration-types.js

@@ -68,6 +68,7 @@
 
 /**
  * @typedef {object} DatabaseConfigurationType
+ * @property {number | null} [advisoryLockAcquireTimeoutMs] - Bound (ms) a blocking advisory-lock acquisition waits for a contended lock before reporting failure. Default: `900000` (15 minutes). `null` opts out and restores the driver's indefinite wait. A per-call `timeoutMs` argument always overrides this.
  * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
  * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
  * @property {string} [database] - Database name for this connection.
@@ -222,6 +223,7 @@
  *   Priorities may be any number, including negative to sink a queue below the
  *   default. Jobs within the same priority keep FIFO (`scheduled_at`, then
  *   `created_at`) order. Default: `{}` (no queue caps, all queues priority `0`).
+ * @property {number | null} [scheduledEnqueueTimeoutMs] - Bounds one scheduled enqueue attempt in the main process. A durable enqueue that never settles (wedged DB connection, contended advisory lock) would otherwise keep its schedule key permanently in flight, so every later tick skipped itself and shutdown could never drain. On timeout the attempt is reported as `background-jobs-scheduled-enqueue-stall` and the key clears for the next tick. Default: 20 minutes — deliberately 5 minutes above `advisoryLockAcquireTimeoutMs` so the precise lock error surfaces first. `null` opts out.
  * @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
  *   detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
  *   to restore the legacy fixed-interval poll.
@@ -742,6 +744,12 @@
  * @property {string} [path] - HTTP path for the built-in API manifest endpoint. Defaults to `/api/manifest`.
  * @property {string} [token] - Bearer token required in the `Authorization: Bearer <token>` header. When set, requests without a matching token are not routed (404), so the endpoint stays hidden.
  */
+/**
+ * @typedef {object} McpConfiguration
+ * @property {string} [path] - HTTP path for the built-in MCP endpoint. Defaults to `/mcp`.
+ * @property {string} [token] - Bearer token required in the `Authorization` header. When set, requests without a matching token are not routed (404), so the endpoint stays hidden.
+ */
+
 
 /**
  * @typedef {object} DebugEndpointConfiguration
@@ -774,6 +782,7 @@
  * @property {boolean} [debug] - Enable debug logging.
  * @property {boolean | DebugEndpointConfiguration} [debugEndpoint] - Enable the built-in debug endpoint. Defaults to false.
  * @property {boolean | ApiManifestConfiguration} [apiManifest] - Enable the built-in API manifest endpoint. Defaults to false.
+ * @property {boolean | McpConfiguration} [mcp] - Enable the built-in MCP endpoint on the HTTP server (JSON-RPC over HTTP in addition to the `velocious mcp` stdio server). Defaults to false.
  * @property {string} [directory] - Base directory for the project.
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.

package/build/configuration.js

@@ -26,6 +26,7 @@ import UUID from "pure-uuid"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
 import BackgroundJobsAdapter from "./background-jobs/adapter.js"
+import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./background-jobs/scheduled-enqueue-bound.js"
 import DatabaseOperation from "./database/operation.js"
 import { initializeAuditedModelRelationships } from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
@@ -259,7 +260,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, mcp = false, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -303,6 +304,7 @@ export default class VelociousConfiguration {
     this.debug = debug
     this._debugEndpoint = this._normalizeDebugEndpoint(debugEndpoint)
     this._apiManifest = this._normalizeApiManifest(apiManifest)
+    this._mcp = this._normalizeMcp(mcp)
     this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
@@ -485,6 +487,7 @@ export default class VelociousConfiguration {
     this._routeResolverHooks = [...(routeResolverHooks || [])]
     this._addDebugEndpointRouteHook()
     this._addApiManifestRouteHook()
+    this._addMcpRouteHook()
 
     /**
      * Stores the applied route mounts value.
@@ -624,6 +627,63 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Runs normalize mcp.
+   * @param {boolean | {path?: string, token?: string}} value - MCP endpoint configuration.
+   * @returns {{enabled: boolean, path: string, token: string | null}} - Normalized MCP endpoint configuration.
+   */
+  _normalizeMcp(value) {
+    if (value === false || value === undefined) return {enabled: false, path: "/mcp", token: null}
+    if (value === true) return {enabled: true, path: "/mcp", token: null}
+
+    if (typeof value !== "object" || value === null) {
+      throw new Error(`Expected mcp to be a boolean or object, got: ${String(value)}`)
+    }
+
+    const path = value.path || "/mcp"
+
+    if (typeof path !== "string" || !path.startsWith("/")) {
+      throw new Error(`Expected mcp.path to be a string starting with '/', got: ${String(path)}`)
+    }
+
+    const token = value.token === undefined || value.token === null ? null : value.token
+
+    if (token !== null && (typeof token !== "string" || !token.trim())) {
+      throw new Error(`Expected mcp.token to be a non-empty string, got: ${String(token)}`)
+    }
+
+    return {enabled: true, path, token: token === null ? null : token.trim()}
+  }
+
+  /**
+   * Runs add mcp route hook.
+   * @returns {void} - No return value.
+   */
+  _addMcpRouteHook() {
+    if (!this._mcp.enabled) return
+
+    this.addRouteResolverHook(({currentPath, request}) => {
+      if (request.httpMethod() !== "POST") return null
+      if (currentPath !== this._mcp.path) return null
+
+      // When a token is configured, an unauthenticated request gets no route at
+      // all (404) rather than a 401, so the endpoint's existence stays hidden.
+      if (this._mcp.token && !this.debugEndpointRequestAuthorized(request, this._mcp.token)) return null
+
+      return {
+        action: "handle",
+        controller: "velociousMcp",
+        controllerPath: "./built-in/mcp/controller.js",
+        // Tenant and ability resolution belong to the frontend-model dispatcher
+        // per command (withFrontendModelRequestContext), exactly like the regular
+        // /frontend-models route — the MCP transport never bypasses them.
+        skipAbilityResolution: true,
+        skipTenantResolution: true,
+        viewPath: "./built-in/mcp"
+      }
+    })
+  }
+
   /**
    * Runs add debug endpoint route hook.
    * @returns {void} - No return value.
@@ -1041,6 +1101,7 @@ export default class VelociousConfiguration {
       enforceTenantDatabaseScopes: this.getEnforceTenantDatabaseScopes(),
       exposeInternalErrorsToClients: this.getExposeInternalErrorsToClients(),
       initialized: this._isInitialized,
+      mcp: this._mcp.enabled ? {enabled: true, path: this._mcp.path, tokenConfigured: Boolean(this._mcp.token)} : {enabled: false},
       logging: {
         debugLowLevel: this._logging?.debugLowLevel === true,
         outputs: this._logging ? Object.keys(this._logging) : []
@@ -1707,6 +1768,20 @@ export default class VelociousConfiguration {
     const drainStoreOperationTimeoutMs = typeof configured.drainStoreOperationTimeoutMs === "number" && configured.drainStoreOperationTimeoutMs >= 1
       ? configured.drainStoreOperationTimeoutMs
       : 60_000
+    // `null` is an explicit opt-out of the scheduled-enqueue bound. A present
+    // but non-positive number is a mistake, not an opt-out, so it falls back to
+    // the framework default rather than silently disabling the watchdog.
+    const scheduledEnqueueTimeoutMs = "scheduledEnqueueTimeoutMs" in configured
+      ? (
+        configured.scheduledEnqueueTimeoutMs === null ?
+          null
+        : (
+          typeof configured.scheduledEnqueueTimeoutMs === "number" && configured.scheduledEnqueueTimeoutMs > 0 ?
+            configured.scheduledEnqueueTimeoutMs
+          : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
+        )
+      )
+      : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
     const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
     // An explicit config value wins over the env var — including `null`/`0`,
     // which disable the backstop even when the environment sets a default.
@@ -1732,7 +1807,7 @@ export default class VelociousConfiguration {
 
     const jobClasses = this.getBackgroundJobClasses()
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
   }
 
   /**

package/build/database/advisory-lock-bound.js

@@ -0,0 +1,16 @@
+// @ts-check
+
+/**
+ * Default bound for one blocking advisory-lock acquisition.
+ *
+ * A blocking `acquireAdvisoryLock(name)` call with no explicit timeout used to park a pooled
+ * connection for the driver's indefinite wait (MySQL/MariaDB: one year). One wedged holder — a
+ * killed process, a runner that died while holding the lock, a connection that never returned —
+ * then convoyed every later caller on the same lock name: the queue kept growing while every pool
+ * connection sat in MariaDB's `User lock` state and no dispatch happened anywhere.
+ *
+ * The default is deliberately far above any contention observed in healthy production operation, so
+ * a legitimate lock handover is never cut off, while a wedged holder stops stealing pool capacity
+ * forever. Pass `null` explicitly to opt back in to the indefinite wait.
+ * @type {number} */
+export const DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS = 15 * 60 * 1000

package/build/database/drivers/base.js

@@ -160,6 +160,7 @@ import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "../advisory-lock-bound.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
 import QueryAbortedError from "../query-aborted-error.js"
@@ -2928,17 +2929,37 @@ export default class VelociousDatabaseDriversBase {
    * same name and let you serialize functionality without blocking readers
    * or writers that do not participate in the same lock.
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - Resolves to true when the lock has been acquired, false if the timeout elapsed.
    */
   async acquireAdvisoryLock(name, args = {}) {
-    const acquired = await this._acquireAdvisoryLock(name, args)
+    const acquired = await this._acquireAdvisoryLock(name, {timeoutMs: this.advisoryLockAcquireTimeoutMs(args)})
 
     if (acquired) this._trackAdvisoryLock(name)
 
     return acquired
   }
 
+  /**
+   * Resolves the wait bound for one advisory-lock acquisition.
+   * An explicit `timeoutMs` — including an explicit `null` opt-out — always
+   * wins. Otherwise the database configuration's `advisoryLockAcquireTimeoutMs`
+   * applies, and a null there opts out too. Only when neither is configured does
+   * the framework default bound the wait.
+   * @param {{timeoutMs?: number | null}} [args] - Acquisition options from the caller.
+   * @returns {number | null} - Wait bound in milliseconds, or `null` for an indefinite wait.
+   */
+  advisoryLockAcquireTimeoutMs(args = {}) {
+    if (args.timeoutMs !== undefined) return args.timeoutMs
+
+    const configured = this.getArgs()?.advisoryLockAcquireTimeoutMs
+
+    if (configured === null) return null
+    if (typeof configured === "number" && configured >= 0) return configured
+
+    return DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS
+  }
+
   /**
    * Driver-specific blocking advisory-lock acquisition hook.
    * @abstract

package/build/database/drivers/pgsql/index.js

@@ -22,6 +22,11 @@ import Update from "./sql/update.js"
 
 const PG_TIMESTAMP_WITHOUT_TIMEZONE_OID = 1114
 
+/** Smallest wait between `pg_try_advisory_lock` probes; preserves the historical 50ms cadence for short bounds. */
+const PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS = 50
+/** Largest wait between `pg_try_advisory_lock` probes; keeps a long bounded wait from probing tens of thousands of times. */
+const PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS = 2000
+
 pgTypes.setTypeParser(PG_TIMESTAMP_WITHOUT_TIMEZONE_OID, (value) => new Date(`${value.replace(" ", "T")}Z`))
 
 export default class VelociousDatabaseDriversPgsql extends Base{
@@ -425,14 +430,32 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return signed.toString()
   }
 
+  /**
+   * Resolves the `pg_try_advisory_lock` probe cadence for one bounded wait.
+   *
+   * `pg_advisory_lock` has no native timeout, so a bounded acquisition polls. Scaling the interval
+   * with the bound keeps the historical 50ms cadence — and its fast acquisition — for the short
+   * explicit `timeoutMs` values callers already pass, while a long framework default stays
+   * responsive without turning one contended lock into tens of thousands of probe queries.
+   * @param {number} timeoutMs - Bounded wait in milliseconds.
+   * @returns {number} - Probe interval in milliseconds.
+   */
+  static advisoryLockPollIntervalMs(timeoutMs) {
+    return Math.min(
+      Math.max(Math.floor(timeoutMs / 100), PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS),
+      PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS
+    )
+  }
+
   /**
    * Blocks until a PostgreSQL session-level advisory lock is acquired on
    * this connection. Implemented via `pg_advisory_lock(bigint)`, which has
    * no native timeout — the `timeoutMs` argument is emulated by racing a
-   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see
-   * the same contract.
+   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see the
+   * same contract. The poll interval backs off to a cap so a long bounded wait
+   * does not turn one contended lock into thousands of probe queries.
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or negative blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
   async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
@@ -444,7 +467,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     }
 
     const deadline = Date.now() + timeoutMs
-    const pollIntervalMs = 50
+    const pollIntervalMs = VelociousDatabaseDriversPgsql.advisoryLockPollIntervalMs(timeoutMs)
 
     while (true) {
       if (await this._tryAcquireAdvisoryLock(name)) return true

package/build/environment-handlers/base.js

@@ -518,6 +518,15 @@ export default class VelociousEnvironmentHandlerBase {
     throw new Error("cliCommandsConsole not implemented")
   }
 
+  /**
+   * Runs cli commands mcp.
+   * @param {import("../cli/base-command.js").default} _command - Command.
+   * @returns {Promise<void>} - Resolves when the command completes.
+   */
+  async cliCommandsMcp(_command) {
+    throw new Error("cliCommandsMcp not implemented")
+  }
+
   /**
    * Runs cli commands server.
    * @param {import("../cli/base-command.js").default} _command - Command.

package/build/environment-handlers/node/cli/commands/mcp.js

@@ -0,0 +1,87 @@
+// @ts-check
+
+import Application from "../../../../application.js"
+import BaseCommand from "../../../../cli/base-command.js"
+import {startMcpStdioServer} from "../../../../mcp/json-rpc-server.js"
+
+/**
+ * Parses `--request-context key=value` occurrences from raw process args and the
+ * `MCP_REQUEST_CONTEXT` environment variable (JSON object) into one context hash.
+ * @param {object} args - Arguments.
+ * @param {string[]} [args.processArgs] - Raw CLI process args.
+ * @returns {Record<string, string | number | boolean> | undefined} - Parsed request context, or undefined when none configured.
+ */
+export function parseMcpRequestContext({processArgs = []}) {
+  /** @type {Record<string, string | number | boolean>} */
+  const context = {}
+
+  const envValue = process.env.MCP_REQUEST_CONTEXT
+
+  if (envValue) {
+    const parsedEnv = /** @type {Record<string, unknown>} */ (JSON.parse(envValue))
+
+    for (const [key, value] of Object.entries(parsedEnv)) {
+      assignContextValue(context, key, value)
+    }
+  }
+
+  for (let i = 0; i < processArgs.length; i++) {
+    if (processArgs[i] !== "--request-context") continue
+
+    const pair = processArgs[i + 1]
+
+    if (typeof pair !== "string") throw new Error("--request-context requires a key=value pair")
+
+    const separatorIndex = pair.indexOf("=")
+
+    if (separatorIndex < 1) throw new Error(`--request-context pair '${pair}' must be key=value`)
+
+    assignContextValue(context, pair.slice(0, separatorIndex), pair.slice(separatorIndex + 1))
+    i++
+  }
+
+  return Object.keys(context).length > 0 ? context : undefined
+}
+
+/**
+ * Assigns one scalar context value, converting numeric strings to numbers.
+ * @param {Record<string, string | number | boolean>} context - Target context hash.
+ * @param {string} key - Context key.
+ * @param {unknown} value - Raw value.
+ * @returns {void} - No return value.
+ */
+function assignContextValue(context, key, value) {
+  if (typeof value === "number" || typeof value === "boolean") {
+    context[key] = value
+
+    return
+  }
+
+  if (typeof value !== "string") throw new Error(`Request context value for '${key}' must be a scalar`)
+
+  const asNumber = Number(value)
+
+  context[key] = value.length > 0 && Number.isFinite(asNumber) ? asNumber : value
+}
+
+export default class VelociousCliCommandsMcp extends BaseCommand{
+  /**
+   * Runs execute.
+   * @returns {Promise<void>} - Starts the MCP stdio server and waits until stdin closes.
+   */
+  async execute() {
+    // Identify this process in `ps`/`top` instead of a generic "node" entry.
+    process.title = "velocious mcp"
+
+    const configuration = this.getConfiguration()
+    const requestContext = parseMcpRequestContext({processArgs: this.processArgs})
+    const application = new Application({configuration, type: "mcp"})
+
+    await application.initialize()
+
+    const server = startMcpStdioServer({configuration, requestContext})
+
+    await server.done
+    await application.stop()
+  }
+}