velocious 1.0.693 → 1.0.695

package/README.md

@@ -4,7 +4,7 @@
 * Database framework with familiar MVC concepts
 * Database models with migrations and validations
 * Database models that work almost the same in frontend and backend, including online CRUD for [composite primary keys](docs/composite-primary-keys.md)
-* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed (see [docs/advisory-locks.md](docs/advisory-locks.md))
+* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed, a non-throwing `withAdvisoryLockOrDefer` result for contended hot paths, and event-driven slow acquire/hold duration telemetry with holder attribution (see [docs/advisory-locks.md](docs/advisory-locks.md)) (see [docs/advisory-locks.md](docs/advisory-locks.md))
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage, including caller-selected `pre-runtime` and `post-publication` execution sets and recorded `changeTable` batches that combine operations into one `ALTER` on bulk-capable drivers (see [docs/database-migrations.md](docs/database-migrations.md), [docs/migration-execution-phases.md](docs/migration-execution-phases.md), and [docs/change-table.md](docs/change-table.md))

package/build/configuration-types.js

@@ -69,6 +69,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 {{slowAcquireMs?: number | null, slowHoldMs?: number | null}} [advisoryLockTelemetry] - Event-driven advisory-lock duration telemetry thresholds. `slowAcquireMs` (default `5000`) reports an acquire wait that completed slower than the threshold, including the eventual outcome; `advisory-lock-acquire-timeout` always fires when a wait exceeds its bound and carries the holder identity available on the tier at that moment. `slowHoldMs` (default `60000`) reports a hold that outlives the threshold at release. `null` disables that report. Reports fire on the events themselves — no periodic scanner — on `getErrorEvents()` as `framework-error` with `context: "advisory-lock-telemetry"`. See [docs/advisory-locks.md](../docs/advisory-locks.md).
  * @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.
@@ -744,6 +745,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
@@ -776,6 +783,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

@@ -260,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
@@ -304,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
@@ -486,6 +487,7 @@ export default class VelociousConfiguration {
     this._routeResolverHooks = [...(routeResolverHooks || [])]
     this._addDebugEndpointRouteHook()
     this._addApiManifestRouteHook()
+    this._addMcpRouteHook()
 
     /**
      * Stores the applied route mounts value.
@@ -625,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.
@@ -1042,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) : []

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

@@ -118,6 +118,37 @@ export default class AdvisoryLockRunner {
     })
   }
 
+  /**
+   * Runs a callback if the advisory lock can be acquired without waiting;
+   * otherwise returns a `{acquired: false}` defer result instead of throwing.
+   *
+   * This is the non-throwing counterpart of `withAdvisoryLockOrFail` for hot
+   * paths: "holder busy, defer me" is a first-class outcome, so a contended
+   * lock produces zero exception traffic and — because the probe is a single
+   * immediate try-acquire — zero pinned connections. Callers reschedule via
+   * their own event-driven retry machinery. The result form is identical
+   * across tiers: the driver's `tryAcquireAdvisoryLock` maps per-tier (MySQL
+   * `GET_LOCK(name, 0)`, PostgreSQL `pg_try_advisory_lock`, SQL Server
+   * `sp_getapplock @LockTimeout = 0`, SQLite process-local queue, SQLite Node
+   * file lock), so a caller never branches on the backend.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {(args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{holdTimeoutMs?: number | null, dedicatedConnection?: boolean}} [args] - Hold timeout options.
+   * @returns {Promise<{acquired: true, result: T} | {acquired: false, reason: "contended", lockName: string}>} - Either the held-callback result or the defer outcome.
+   */
+  async withAdvisoryLockOrDefer(name, callback, args = {}) {
+    return await this.withLockConnection(args, async (connection) => {
+      const acquired = await connection.tryAcquireAdvisoryLock(name)
+
+      if (!acquired) return {acquired: false, reason: "contended", lockName: name}
+
+      const result = await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+
+      return {acquired: true, result}
+    })
+  }
+
   /**
    * Runs the lock holder callback and releases the lock from its owning connection.
    * @template T

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

@@ -0,0 +1,129 @@
+// @ts-check
+
+/**
+ * Event-driven advisory-lock duration telemetry (STC-261, parent epic STC-209).
+ *
+ * A lock convoy is only fixable when it is *attributable*: which lock name was
+ * contended, on which backend tier, for how long, and who held it. These reports
+ * fire on the acquisition/release events themselves — never from a periodic
+ * scanner — so a contended lock in production surfaces on the framework-error
+ * channel with the holder identity available on that tier at that moment,
+ * without SSH forensics.
+ *
+ * Three events, each with its own threshold (all configurable per database via
+ * `advisoryLockTelemetry`, see `docs/advisory-locks.md`):
+ *
+ * - `advisory-lock-slow-acquire` — an acquire wait completed slower than
+ *   `slowAcquireMs` (default 5000), including the eventual outcome (`acquired`
+ *   or `timeout`).
+ * - `advisory-lock-acquire-timeout` — a wait exceeded its timeout. The report
+ *   carries the holder identity available on the tier at that moment: the
+ *   driver-native tiers attribute the holder connection (MariaDB
+ *   `IS_USED_LOCK`, PostgreSQL `pg_locks` joined to `pg_stat_activity`, SQL
+ *   Server `sys.dm_tran_locks` request session, SQLite Node file tier
+ *   `owner.json` pid/hostname); the process-local tier reports the owning
+ *   driver's `holderId`.
+ * - `advisory-lock-slow-hold` — a hold lasted longer than `slowHoldMs`
+ *   (default 60000), emitted at release.
+ *
+ * Reports are emitted on `configuration.getErrorEvents()` as `framework-error`
+ * (plus the matching `all-error`) with `{context: "advisory-lock-telemetry",
+ * event, lockName, backendTier, ...}` payloads, matching the repo's "never
+ * swallow" rule so process-level bug reporters capture them.
+ *
+ * Holder lookups are strictly best-effort *after* the acquisition already
+ * settled: a failed lookup never changes the acquisition outcome and never
+ * throws to the caller.
+ */
+
+/**
+ * One advisory-lock telemetry report.
+ * @typedef {object} AdvisoryLockTelemetryReport
+ * @property {"advisory-lock-slow-acquire" | "advisory-lock-acquire-timeout" | "advisory-lock-slow-hold"} event - Which event fired.
+ * @property {string} lockName - The contended advisory-lock name.
+ * @property {string} backendTier - Tier that served (or refused) the acquisition: `driver-native`, `process-local`, or `file`.
+ * @property {number} durationMs - Measured duration of the acquire wait (or the hold).
+ * @property {"acquired" | "timeout" | null} outcome - For acquire events: whether the wait eventually acquired the lock. Null for hold reports.
+ * @property {number | null} timeoutMs - The effective acquire bound for acquire events. Null for hold reports or an unbounded wait.
+ * @property {string | null} holderId - Process-local holder attribution when the tier can name its local holder.
+ * @property {string | null} holderConnectionId - Driver-native holder attribution captured at the event moment (MariaDB `IS_USED_LOCK` connection id, PostgreSQL pid, SQL Server session id, SQLite file `pid@hostname`).
+ * @property {string | null} holderLookupError - Set when the best-effort holder lookup itself failed; the lookup never affects the acquisition.
+ */
+
+/**
+ * Resolved per-database telemetry thresholds.
+ * @typedef {object} AdvisoryLockTelemetryThresholds
+ * @property {number | null} slowAcquireMs - Report an acquire wait slower than this; `null` disables slow-acquire reports.
+ * @property {number | null} slowHoldMs - Report a hold longer than this at release; `null` disables hold reports.
+ */
+
+/** Framework default: report an acquire wait that completed slower than this. */
+export const DEFAULT_ADVISORY_LOCK_SLOW_ACQUIRE_MS = 5000
+
+/** Framework default: report a hold that outlives this at release. */
+export const DEFAULT_ADVISORY_LOCK_SLOW_HOLD_MS = 60 * 1000
+
+/**
+ * Resolve the telemetry thresholds for one database configuration.
+ * An explicit per-database `advisoryLockTelemetry` value wins; `null` opts out
+ * of that report; only when neither is configured does the framework default
+ * apply.
+ * @param {import("../configuration-types.js").DatabaseConfigurationType} args - Database configuration args.
+ * @returns {AdvisoryLockTelemetryThresholds} - Resolved thresholds.
+ */
+export function advisoryLockTelemetryThresholds(args) {
+  const configured = args?.advisoryLockTelemetry
+  /** @type {AdvisoryLockTelemetryThresholds} */
+  const thresholds = {
+    slowAcquireMs: DEFAULT_ADVISORY_LOCK_SLOW_ACQUIRE_MS,
+    slowHoldMs: DEFAULT_ADVISORY_LOCK_SLOW_HOLD_MS
+  }
+
+  if (configured?.slowAcquireMs === null) thresholds.slowAcquireMs = null
+  else if (typeof configured?.slowAcquireMs === "number" && configured.slowAcquireMs >= 0) thresholds.slowAcquireMs = configured.slowAcquireMs
+
+  if (configured?.slowHoldMs === null) thresholds.slowHoldMs = null
+  else if (typeof configured?.slowHoldMs === "number" && configured.slowHoldMs >= 0) thresholds.slowHoldMs = configured.slowHoldMs
+
+  return thresholds
+}
+
+/**
+ * Emit one telemetry report on the framework-error channel.
+ *
+ * Mirrors the repo's framework-error emission shape (see `configuration.js`
+ * `_reportBeaconError`): when no listener is attached to `framework-error` or
+ * `all-error`, a one-line summary goes to `stderr` so a convoy is never
+ * completely silent. A listener failure can never break lock handling, so
+ * emissions are guarded.
+ * @param {import("../configuration.js").default} configuration - Configuration instance owning the error channel.
+ * @param {AdvisoryLockTelemetryReport} report - The report payload.
+ * @returns {void} - No return value.
+ */
+export function emitAdvisoryLockTelemetryReport(configuration, report) {
+  /** @type {import("eventemitter3").EventEmitter | undefined} */
+  let errorEvents
+
+  try {
+    errorEvents = configuration?.getErrorEvents()
+  } catch {
+    return // No configuration to report through — never break lock handling.
+  }
+
+  if (!errorEvents) return
+
+  const hasListener = errorEvents.listenerCount("framework-error") > 0
+    || errorEvents.listenerCount("all-error") > 0
+  const payload = {context: "advisory-lock-telemetry", ...report}
+
+  try {
+    errorEvents.emit("framework-error", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+  } catch {
+    // A broken listener must never surface as a lock failure.
+  }
+
+  if (!hasListener) {
+    console.error(`[velocious advisory-lock-telemetry ${report.event}] lock=${JSON.stringify(report.lockName)} tier=${report.backendTier} durationMs=${report.durationMs}${report.outcome ? ` outcome=${report.outcome}` : ""}${report.holderConnectionId ? ` holderConnectionId=${report.holderConnectionId}` : ""}${report.holderId ? ` holderId=${report.holderId}` : ""} — subscribe via configuration.getErrorEvents().on("framework-error", …) to route these reports to your bug reporter`)
+  }
+}

package/build/database/drivers/base.js

@@ -161,6 +161,7 @@ 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 {advisoryLockTelemetryThresholds, emitAdvisoryLockTelemetryReport} from "../advisory-lock-telemetry.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
 import QueryAbortedError from "../query-aborted-error.js"
@@ -328,6 +329,18 @@ export default class VelociousDatabaseDriversBase {
   _failedQueryDiagnostics = new WeakMap()
   /** @type {Map<string, number>} */
   _heldAdvisoryLocks = new Map()
+  /**
+   * When each tracked advisory lock was first acquired, so the final release can
+   * report a hold that outlived `advisoryLockTelemetry.slowHoldMs`.
+   * @type {Map<string, number>}
+   */
+  _advisoryLockAcquiredAtByName = new Map()
+  /**
+   * Stable per-connection holder identity used by advisory-lock telemetry when
+   * the tier can only name local holders.
+   * @type {string | undefined}
+   */
+  _advisoryLockHolderId = undefined
   /**
    * Exclusive operation lease installed by a single-multi-use pool.
    * @type {import("../operation-lease.js").default | undefined}
@@ -2933,9 +2946,24 @@ export default class VelociousDatabaseDriversBase {
    * @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, {timeoutMs: this.advisoryLockAcquireTimeoutMs(args)})
+    const timeoutMs = this.advisoryLockAcquireTimeoutMs(args)
+    const startedAt = Date.now()
+    const acquired = await this._acquireAdvisoryLock(name, {timeoutMs})
+    const durationMs = Date.now() - startedAt
 
-    if (acquired) this._trackAdvisoryLock(name)
+    if (acquired) {
+      this._trackAdvisoryLock(name)
+
+      const slowAcquireMs = advisoryLockTelemetryThresholds(this.getArgs()).slowAcquireMs
+
+      if (slowAcquireMs !== null && durationMs > slowAcquireMs) {
+        await this._reportAdvisoryLockTelemetry({event: "advisory-lock-slow-acquire", lockName: name, durationMs, outcome: "acquired", timeoutMs})
+      }
+    } else {
+      // The wait exceeded its bound: attribute the lock to the holder that
+      // blocked it, captured at this moment on this tier.
+      await this._reportAdvisoryLockTelemetry({event: "advisory-lock-acquire-timeout", lockName: name, durationMs, outcome: "timeout", timeoutMs, captureHolder: true})
+    }
 
     return acquired
   }
@@ -3008,6 +3036,21 @@ export default class VelociousDatabaseDriversBase {
       this._heldAdvisoryLocks.delete(name)
     }
 
+    if (!this._heldAdvisoryLocks.has(name)) {
+      const acquiredAt = this._advisoryLockAcquiredAtByName.get(name)
+
+      this._advisoryLockAcquiredAtByName.delete(name)
+
+      if (acquiredAt !== undefined) {
+        const holdDurationMs = Date.now() - acquiredAt
+        const slowHoldMs = advisoryLockTelemetryThresholds(this.getArgs()).slowHoldMs
+
+        if (slowHoldMs !== null && holdDurationMs > slowHoldMs) {
+          await this._reportAdvisoryLockTelemetry({event: "advisory-lock-slow-hold", lockName: name, durationMs: holdDurationMs, outcome: null, timeoutMs: null})
+        }
+      }
+    }
+
     return released
   }
 
@@ -3051,6 +3094,8 @@ export default class VelociousDatabaseDriversBase {
    */
   _trackAdvisoryLock(name) {
     this._heldAdvisoryLocks.set(name, (this._heldAdvisoryLocks.get(name) || 0) + 1)
+
+    if (!this._advisoryLockAcquiredAtByName.has(name)) this._advisoryLockAcquiredAtByName.set(name, Date.now())
   }
 
   /**
@@ -3079,4 +3124,71 @@ export default class VelociousDatabaseDriversBase {
   isAdvisoryLockHeld(name) { // eslint-disable-line no-unused-vars
     throw new Error(`'isAdvisoryLockHeld' not implemented for ${this.constructor.name}`)
   }
+
+  /**
+   * Which advisory-lock backend tier this connection serves (STC-210 chain
+   * naming). The base driver is the driver-native tier; the SQLite drivers
+   * override to `process-local` / `file`.
+   * @returns {string} - Tier name reported on telemetry payloads.
+   */
+  advisoryLockBackendTier() {
+    return "driver-native"
+  }
+
+  /**
+   * Stable identity of this connection as a lock holder, reported on
+   * telemetry payloads so a slow acquire/hold is attributable to the reporting
+   * connection itself.
+   * @returns {string} - Holder id.
+   */
+  advisoryLockHolderId() {
+    if (!this._advisoryLockHolderId) this._advisoryLockHolderId = `advisory-lock-holder:${new UUID(4).format()}`
+
+    return this._advisoryLockHolderId
+  }
+
+  /**
+   * Best-effort identity of the connection currently holding the named lock,
+   * captured on the tier that served the acquisition. The base driver has no
+   * portable server-side lookup; MySQL/PostgreSQL/SQL Server/Node-SQLite
+   * override with their tier's holder attribution.
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - Holder connection identity, or null when the tier cannot attribute it.
+   */
+  async advisoryLockHolderConnectionId(name) { // eslint-disable-line no-unused-vars
+    return null
+  }
+
+  /**
+   * Emit one event-driven advisory-lock telemetry report (slow acquire,
+   * acquire timeout with holder attribution, slow hold). The holder lookup is
+   * best-effort: a failed lookup is recorded on the report and never affects
+   * the acquisition that already settled.
+   * @param {{event: "advisory-lock-slow-acquire" | "advisory-lock-acquire-timeout" | "advisory-lock-slow-hold", lockName: string, durationMs: number, outcome: "acquired" | "timeout" | null, timeoutMs: number | null, captureHolder?: boolean}} args - Report args.
+   * @returns {Promise<void>} - Resolves after the report is emitted.
+   */
+  async _reportAdvisoryLockTelemetry(args) {
+    /** @type {import("../advisory-lock-telemetry.js").AdvisoryLockTelemetryReport} */
+    const report = {
+      event: args.event,
+      lockName: args.lockName,
+      backendTier: this.advisoryLockBackendTier(),
+      durationMs: args.durationMs,
+      outcome: args.outcome,
+      timeoutMs: args.timeoutMs,
+      holderId: this.advisoryLockHolderId(),
+      holderConnectionId: null,
+      holderLookupError: null
+    }
+
+    if (args.captureHolder) {
+      try {
+        report.holderConnectionId = await this.advisoryLockHolderConnectionId(args.lockName)
+      } catch (error) {
+        report.holderLookupError = error instanceof Error ? error.message : String(error)
+      }
+    }
+
+    emitAdvisoryLockTelemetryReport(this.configuration, report)
+  }
 }

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

@@ -954,4 +954,20 @@ export default class VelociousDatabaseDriversMssql extends Base{
 
     return testResult === 0
   }
+
+  /**
+   * Attributes the current holder of the named application lock to its
+   * requesting session from `sys.dm_tran_locks`, captured at the telemetry
+   * event moment (best-effort; the caller guards failures).
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - SQL Server session id of the holder, or null when no session holds the lock.
+   */
+  async advisoryLockHolderConnectionId(name) {
+    const rows = await this.query(
+      `SELECT TOP 1 request_session_id AS velocious_advisory_lock_holder FROM sys.dm_tran_locks WHERE resource_type = 'APPLICATIONLOCK' AND resource_description = ${this.quote(name)}`
+    )
+    const holder = rows?.[0]?.velocious_advisory_lock_holder
+
+    return holder === null || holder === undefined ? null : String(holder)
+  }
 }

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

@@ -882,6 +882,20 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return Number(result) === 1
   }
 
+  /**
+   * Attributes the current holder of the named lock to its physical session
+   * connection id via `IS_USED_LOCK(name)`, captured at the telemetry event
+   * moment (best-effort; the caller guards failures).
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - MariaDB/MySQL connection id of the holder, or null when no session holds the lock.
+   */
+  async advisoryLockHolderConnectionId(name) {
+    const rows = await this.query(`SELECT IS_USED_LOCK(${this.quote(name)}) AS velocious_advisory_lock_holder`)
+    const holder = rows?.[0]?.velocious_advisory_lock_holder
+
+    return holder === null || holder === undefined ? null : String(holder)
+  }
+
   /**
    * Runs is advisory lock held.
    * @param {string} name - Lock name.

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

@@ -505,6 +505,23 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return result === true || result === "t" || result === 1 || result === "1"
   }
 
+  /**
+   * Attributes the current holder of the named advisory lock to its backend
+   * process id from `pg_locks`, captured at the telemetry event moment
+   * (best-effort; the caller guards failures).
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - PostgreSQL backend pid of the holder, or null when no session holds the lock.
+   */
+  async advisoryLockHolderConnectionId(name) {
+    const key = this.advisoryLockKey(name)
+    const rows = await this.query(
+      `SELECT pid FROM pg_locks WHERE locktype = 'advisory' AND ((classid::bigint << 32) | (objid::bigint & 4294967295)) = ${key} LIMIT 1`
+    )
+    const holder = rows?.[0]?.pid
+
+    return holder === null || holder === undefined ? null : String(holder)
+  }
+
   /**
    * Runs is advisory lock held.
    * @param {string} name - Lock name.

package/build/database/drivers/sqlite/base.js

@@ -524,4 +524,24 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
   async isAdvisoryLockHeld(name) {
     return VelociousDatabaseDriversSqliteBase._advisoryLockState.ownersByName.has(name)
   }
+
+  /**
+   * The SQLite emulation is the process-local tier of the STC-210 chain.
+   * @returns {string} - Tier name reported on telemetry payloads.
+   */
+  advisoryLockBackendTier() {
+    return "process-local"
+  }
+
+  /**
+   * Attribute the named lock to the driver instance that owns it in the
+   * shared in-process registry (best-effort; the caller guards failures).
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - Owning driver's holder id, or null when no instance holds the lock.
+   */
+  async advisoryLockHolderConnectionId(name) {
+    const owner = VelociousDatabaseDriversSqliteBase._advisoryLockState.ownersByName.get(name)
+
+    return owner ? owner.advisoryLockHolderId() : null
+  }
 }

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

@@ -204,6 +204,39 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     return await this._isAdvisoryLockFileHeld(name)
   }
 
+  /**
+   * The Node SQLite driver layers the opt-in file tier on top of the
+   * process-local pre-filter, so telemetry reports it as `file`.
+   * @returns {string} - Tier name reported on telemetry payloads.
+   */
+  advisoryLockBackendTier() {
+    return "file"
+  }
+
+  /**
+   * Attribute the named lock to the file-tier owner recorded in
+   * `owner.json` (`pid@hostname`), captured at the telemetry event moment
+   * (best-effort; the caller guards failures). Falls back to the
+   * process-local owner when the filesystem lock is not the holder.
+   * @param {string} name - Lock name.
+   * @returns {Promise<string | null>} - File lock owner identity, or null when no process holds the lock.
+   */
+  async advisoryLockHolderConnectionId(name) {
+    const lockPath = this._advisoryLockPath(name)
+
+    try {
+      const content = await fs.readFile(path.join(lockPath, "owner.json"), "utf8")
+      const owner = JSON.parse(content)
+
+      if (owner && typeof owner.pid === "number" && typeof owner.hostname === "string") return `${owner.pid}@${owner.hostname}`
+    } catch {
+      // No file lock directory or unreadable metadata: fall through to the
+      // in-process owner below.
+    }
+
+    return await super.advisoryLockHolderConnectionId(name)
+  }
+
   /**
    * Runs resolve advisory lock directory.
    * @returns {string} - The advisory-lock directory.

package/build/database/record/index.js

@@ -3033,6 +3033,34 @@ class VelociousDatabaseRecord {
     return await runner.withAdvisoryLockOrFail(name, callback, args)
   }
 
+  /**
+   * Runs `callback` if the named advisory lock can be acquired immediately;
+   * otherwise resolves with a `{acquired: false, reason: "contended"}` defer
+   * result instead of throwing. This is the non-throwing counterpart of
+   * `withAdvisoryLockOrFail` for hot paths: contention is a normal outcome,
+   * so callers reschedule via their own event-driven retry machinery with zero
+   * exception traffic and zero pinned connections (the probe is a single
+   * immediate try-acquire on the tier's native try primitive). The result form
+   * is identical across tiers.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{holdTimeoutMs?: number | null, dedicatedConnection?: boolean}} [args] - `holdTimeoutMs` caps how long the callback may hold the lock; `dedicatedConnection` spawns a separate lock session without enabling a hold timeout.
+   * @returns {Promise<{acquired: true, result: T} | {acquired: false, reason: "contended", lockName: string}>} - Either the held-callback result or the defer outcome.
+   * @throws {AdvisoryLockHoldTimeoutError} - If `holdTimeoutMs` elapses while the callback holds the lock.
+   */
+  static async withAdvisoryLockOrDefer(name, callback, args = {}) {
+    await this.ensureInitialized()
+
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
+
+    return await runner.withAdvisoryLockOrDefer(name, callback, args)
+  }
+
   /**
    * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
    * not settled within `holdTimeoutMs`. The callback is not cancelled — this is