velocious 1.0.699 → 1.0.700

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

@@ -1,6 +1,24 @@
 // @ts-check
 
 import timeout, {TimeoutError} from "awaitery/build/timeout.js"
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "./advisory-lock-bound.js"
+import {
+  AdvisoryLockBackendUnavailableError,
+  resolveAdvisoryLockBackendPolicy,
+  refuseAdvisoryLockTierBelowMinimum
+} from "./advisory-lock-backend-policy.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 {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.
+ */
 
 /**
  * Thrown when an advisory lock could not be acquired before `timeoutMs` elapsed.
@@ -77,19 +95,41 @@ export default class AdvisoryLockRunner {
    * cleanup can release the lock even if callback database work is stuck.
    * @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 {(args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>} callback - Callback to invoke while the lock is held.
    * @param {{timeoutMs?: number | null, holdTimeoutMs?: number | null, dedicatedConnection?: boolean}} [args] - Lock and hold timeout options.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLock(name, callback, args = {}) {
+    const fileBackend = await this.fileBackendForName(name)
+
+    if (fileBackend) {
+      const acquired = await fileBackend.acquire(name, {timeoutMs: this.fileAcquireTimeoutMs(args)})
+
+      if (!acquired) {
+        throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)} on the file tier`, {name})
+      }
+
+      const lockBackend = this.fileProvenance(fileBackend, name)
+
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      return await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await fileBackend.release(name)})
+    }
+
     return await this.withLockConnection(args, async (connection) => {
+      const lockBackend = this.driverProvenance(connection)
+
+      this.assertDriverTierEligible(name, lockBackend)
+
       const acquired = await connection.acquireAdvisoryLock(name, args)
 
       if (!acquired) {
         throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
       }
 
-      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      return await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await connection.releaseAdvisoryLock(name)})
     })
   }
 
@@ -102,22 +142,45 @@ export default class AdvisoryLockRunner {
    * cancellation.
    * @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 {(args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>} callback - Callback to invoke while the lock is held.
    * @param {{holdTimeoutMs?: number | null, dedicatedConnection?: boolean}} [args] - Hold timeout options.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLockOrFail(name, callback, args = {}) {
+    const fileBackend = await this.fileBackendForName(name)
+
+    if (fileBackend) {
+      const acquired = await fileBackend.tryAcquire(name)
+
+      if (!acquired) {
+        throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held on the file tier`, {name})
+      }
+
+      const lockBackend = this.fileProvenance(fileBackend, name)
+
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      return await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await fileBackend.release(name)})
+    }
+
     return await this.withLockConnection(args, async (connection) => {
+      const lockBackend = this.driverProvenance(connection)
+
+      this.assertDriverTierEligible(name, lockBackend)
+
       const acquired = await connection.tryAcquireAdvisoryLock(name)
 
       if (!acquired) {
         throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
       }
 
-      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      return await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await connection.releaseAdvisoryLock(name)})
     })
   }
 
+  /**
   /**
    * Runs a callback if the advisory lock can be acquired without waiting;
    * otherwise returns a `{acquired: false}` defer result instead of throwing.
@@ -133,33 +196,172 @@ export default class AdvisoryLockRunner {
    * 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 {(args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => 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 = {}) {
+    const fileBackend = await this.fileBackendForName(name)
+
+    if (fileBackend) {
+      const acquired = await fileBackend.acquire(name, {timeoutMs: 0})
+
+      if (!acquired) return {acquired: false, reason: "contended", lockName: name}
+
+      const lockBackend = this.fileProvenance(fileBackend, name)
+
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      const result = await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await fileBackend.release(name)})
+
+      return {acquired: true, result}
+    }
+
     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})
+      const lockBackend = this.driverProvenance(connection)
+
+      this.assertDriverTierEligible(name, lockBackend)
+
+      this.configuration.recordAdvisoryLockAcquisition({backend: lockBackend.backend, fencingSupported: lockBackend.fencingSupported, lockName: name})
+
+      const result = await this.runLockedCallback({callback, holdTimeoutMs: args.holdTimeoutMs, lockBackend, name, release: async () => await connection.releaseAdvisoryLock(name)})
 
       return {acquired: true, result}
     })
   }
 
   /**
-   * Runs the lock holder callback and releases the lock from its owning connection.
+   * Runs the lock holder callback and releases the lock from its owning backend.
    * @template T
-   * @param {{callback: (args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>, connection: import("./drivers/base.js").default, holdTimeoutMs?: number | null, name: string}} args - Locked callback args.
+   * @param {{callback: (args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>, holdTimeoutMs?: number | null, lockBackend: AdvisoryLockBackendProvenance, name: string, release: () => Promise<unknown>}} args - Locked callback args.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
-  async runLockedCallback({callback, connection, holdTimeoutMs, name}) {
+  async runLockedCallback({callback, holdTimeoutMs, lockBackend, name, release}) {
     try {
-      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
+      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend)
     } finally {
-      await connection.releaseAdvisoryLock(name)
+      await release()
+    }
+  }
+
+  /**
+   * Resolves the backend policy for one lock name and returns the file
+   * backend when the name explicitly opts into the file tier
+   * (`preferredTier: "file"` plus `advisoryLocks.backends.file.enabled: true`).
+   * A name whose declared minimum tier is cross-host is refused loudly
+   * (`AdvisoryLockMinTierRefusedError`) before any contact with the file
+   * tier. A name that prefers the file tier while the backend is disabled
+   * moves to the driver path (a stronger-or-equal tier), never the other way
+   * around. Nothing here ever auto-enables the file tier.
+   * @param {string} name - Lock name.
+   * @returns {Promise<import("./advisory-lock-file-backend.js").default | null>} - Resolves with the file backend serving this name, or null for the driver path.
+   */
+  async fileBackendForName(name) {
+    const policy = resolveAdvisoryLockBackendPolicy(name, this.configuration.getAdvisoryLockPolicy())
+
+    if (policy.preferredTier !== "file") return null
+
+    if (!advisoryLockPolicyAllowsFileTier(policy)) {
+      refuseAdvisoryLockTierBelowMinimum({
+        configuration: this.configuration,
+        lockName: name,
+        minTier: policy.minTier,
+        requestedBackend: "file"
+      })
+    }
+
+    const backend = await this.configuration.getAdvisoryLockFileBackend()
+
+    if (!backend) {
+      // Preferred tier unavailable: fail *upward* to the driver path (a
+      // stronger-or-equal tier), never downward. If the driver cannot satisfy
+      // the minimum either, `assertDriverTierEligible` throws
+      // `AdvisoryLockBackendUnavailableError` on the driver path.
+      return null
+    }
+
+    return backend
+  }
+
+  /**
+   * Fail-closed check on the driver path (design §9): an undeclared lock name
+   * keeps today's behavior (any driver serves it — full backward
+   * compatibility), but a name with an explicit policy entry is refused with
+   * `AdvisoryLockBackendUnavailableError` when the configured driver cannot
+   * satisfy its minimum tier (e.g. `minTier: "driver-native"` on a SQLite
+   * driver, which has no native advisory-lock primitive).
+   * @param {string} name - Lock name.
+   * @param {AdvisoryLockBackendProvenance} lockBackend - Tier the driver path would serve with.
+   * @returns {void}
+   */
+  assertDriverTierEligible(name, lockBackend) {
+    const policy = resolveAdvisoryLockBackendPolicy(name, this.configuration.getAdvisoryLockPolicy())
+
+    if (!policy.entry) return
+
+    const tier = lockBackend.backend
+
+    if (tier === "process-local" && !policy.allowedTiers.includes("process-local")) {
+      throw new AdvisoryLockBackendUnavailableError(
+        `Advisory lock ${JSON.stringify(name)} requires minimum tier ${JSON.stringify(policy.minTier)} but the configured driver (${String(lockBackend.driverType)}) only offers the process-local tier`,
+        {lockName: name, minTier: policy.minTier, reasons: [`driver tier ${tier} below minTier ${policy.minTier}`]}
+      )
+    }
+  }
+
+  /**
+   * Resolves the wait bound for a file-tier acquisition: an explicit caller
+   * `timeoutMs` (including an explicit `null` opt-out) wins, otherwise the
+   * same framework default that bounds driver acquisitions applies.
+   * @param {{timeoutMs?: number | null}} args - Lock options.
+   * @returns {number | null} - Wait bound in milliseconds, or `null` for an indefinite wait.
+   */
+  fileAcquireTimeoutMs(args) {
+    if (args.timeoutMs !== undefined) return args.timeoutMs
+
+    return DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS
+  }
+
+  /**
+   * Builds the acquisition provenance for a file-tier hold. The file tier
+   * cannot carry fencing tokens, so the limitation is reported on every
+   * acquisition rather than silently pretended away (design §8).
+   * @param {import("./advisory-lock-file-backend.js").default} backend - Backend that served the acquisition.
+   * @param {string} name - Lock name.
+   * @returns {AdvisoryLockBackendProvenance} - Acquisition provenance.
+   */
+  fileProvenance(backend, name) {
+    return {backend: "file", fencingSupported: false, holderId: backend.holderId, lockName: name}
+  }
+
+  /**
+   * Builds the acquisition provenance for a driver-served hold. SQLite has no
+   * native advisory-lock primitive, so its emulation tier is reported as
+   * `process-local` rather than pretending to be database-native.
+   * @param {import("./drivers/base.js").default} connection - Connection that served the acquisition.
+   * @returns {AdvisoryLockBackendProvenance} - Acquisition provenance.
+   */
+  driverProvenance(connection) {
+    let driverType = null
+
+    try {
+      driverType = connection.getType()
+    } catch {
+      // Test stub drivers may not implement getType(); the tier alone identifies the backend.
+    }
+
+    const tier = typeof connection.advisoryLockBackendTier === "function"
+      ? connection.advisoryLockBackendTier()
+      : (driverType === "sqlite" ? "process-local" : "driver-native")
+
+    return {
+      backend: /** @type {import("./advisory-lock-backend-policy.js").AdvisoryLockTier} */ (tier),
+      driverType: driverType ?? undefined,
+      fencingSupported: tier === "driver-native"
     }
   }
 
@@ -218,16 +420,18 @@ export default class AdvisoryLockRunner {
    *
    * The callback receives a `TimeoutControl` from awaitery, enabling cooperative
    * cancellation via `control.check()`, `control.signal`, `control.timedOut`,
-   * and `control.remaining()`.
+   * and `control.remaining()`, plus `lockBackend` provenance for the tier that
+   * served the acquisition.
    * @template T
    * @param {string} name - Lock name (for the error message).
-   * @param {(args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>} callback - Callback holding the lock.
+   * @param {(args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>} callback - Callback holding the lock.
    * @param {number | null} [holdTimeoutMs] - Max hold time; falsy disables the timeout.
+   * @param {AdvisoryLockBackendProvenance} [lockBackend] - Provenance of the acquisition serving this hold.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
-  static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
+  static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend) {
     if (!holdTimeoutMs || holdTimeoutMs <= 0) {
-      return await callback()
+      return await callback({lockBackend: lockBackend ?? AdvisoryLockRunner.unknownBackendProvenance()})
     }
 
     let callbackSettled = false
@@ -235,7 +439,7 @@ export default class AdvisoryLockRunner {
     try {
       return await timeout({timeout: holdTimeoutMs}, async ({control}) => {
         try {
-          return await callback({control})
+          return await callback({control, lockBackend: lockBackend ?? AdvisoryLockRunner.unknownBackendProvenance()})
         } finally {
           callbackSettled = true
         }
@@ -248,6 +452,25 @@ export default class AdvisoryLockRunner {
       throw error
     }
   }
+
+  /**
+   * Neutral provenance for direct `runWithAdvisoryLockHoldTimeout` callers that
+   * hold a lock acquired outside this runner.
+   * @returns {AdvisoryLockBackendProvenance} - Provenance with an unknown tier.
+   */
+  static unknownBackendProvenance() {
+    return {backend: "process-local", fencingSupported: false}
+  }
+}
+
+/**
+ * Runs advisory lock policy allows file tier.
+ * @param {import("./advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy} policy - Resolved policy.
+ * @returns {boolean} - Whether the file tier may serve this name.
+ */
+function advisoryLockPolicyAllowsFileTier(policy) {
+  return policy.allowedTiers.includes("file")
 }
 
 export {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError}
+export {AdvisoryLockBackendUnavailableError, AdvisoryLockMinTierRefusedError} from "./advisory-lock-backend-policy.js"

package/build/environment-handlers/base.js

@@ -36,6 +36,19 @@ export default class VelociousEnvironmentHandlerBase {
    */
   resolveTestSharedTransactionPoolType({configuredPoolType}) { return configuredPoolType }
 
+  /**
+   * Creates the file-tier advisory-lock backend (STC-213). Only filesystem
+   * capable environments (the Node handler) can provide this tier; browser
+   * and Expo configurations have no `fs`, so the default refuses loudly
+   * instead of half-working when a deployment explicitly enables
+   * `advisoryLocks.backends.file.enabled`.
+   * @param {{directory: string, leaseMs: number, renewIntervalMs: number}} _args - Backend options.
+   * @returns {Promise<import("../database/advisory-lock-file-backend.js").default>} - Resolves with the created backend in filesystem-capable handlers.
+   */
+  async createAdvisoryLockFileBackend(_args) {
+    throw new Error("The advisory-lock file tier requires a filesystem-capable environment handler (Node)")
+  }
+
   /**
    * Node test runtimes may replace a physical child connection with a broker
    * proxy. Other environments never participate in this test-only protocol.

package/build/environment-handlers/node.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import "../database/annotations-async-hooks.js"
+import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
 import Base from "./base.js"
 import BackgroundJobsClient from "../background-jobs/client.js"
 import SqlBackgroundJobsAdapter from "../background-jobs/sql-adapter.js"
@@ -106,6 +107,16 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return AsyncTrackedMultiConnectionPool
   }
 
+  /**
+   * Creates the filesystem-backed advisory-lock backend for the file tier
+   * (STC-213). The Node handler is the only filesystem-capable environment.
+   * @param {{directory: string, leaseMs: number, renewIntervalMs: number}} args - Backend options.
+   * @returns {Promise<import("../database/advisory-lock-file-backend.js").default>} - Resolves with the created backend.
+   */
+  async createAdvisoryLockFileBackend(args) {
+    return new AdvisoryLockFileBackend(args)
+  }
+
   /**
    * Creates a test-only child proxy when TestRunner supplied an active broker.
    * @param {{DriverClass: typeof import("../database/drivers/base.js").default, config: import("../configuration-types.js").DatabaseConfigurationType, configuration: import("../configuration.js").default, databaseIdentifier: string, reuseKey?: string}} args - Connection details.

package/build/http-server/server-lock.js

@@ -1,11 +1,15 @@
 // @ts-check
 
-import fs from "node:fs/promises"
-import os from "node:os"
+import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
 import path from "node:path"
 
 /**
- * Directory-based lock that allows only one HTTP server process per app directory.
+ * Directory-based lock that allows only one HTTP server process per app
+ * directory. Thin wrapper over the shared file-lock backend
+ * (`src/database/advisory-lock-file-backend.js` — the STC-210 `file` tier
+ * primitive generalized from this lock's original hand-rolled directory
+ * protocol), so the server lock and the advisory-lock file tier share one
+ * acquisition, owner-metadata, lease-renewal, and staleness implementation.
  */
 export default class VelociousHttpServerLock {
   /**
@@ -20,53 +24,26 @@ export default class VelociousHttpServerLock {
     this.host = host
     this.port = port
     this.lockPath = path.join(configuration.getDirectory(), "tmp", "server.lock")
+    this.backend = new AdvisoryLockFileBackend({
+      directory: path.join(configuration.getDirectory(), "tmp"),
+      extraOwnerFields: {host: this.host, port: this.port},
+      pathStyle: "plain"
+    })
     this.acquired = false
   }
 
   /**
-   * Acquires the app-directory HTTP server lock before startup side effects run.
+   * Acquires the app-directory HTTP server lock before startup side effects
+   * run. A stale lock (dead local owner or expired lease) is reclaimed by the
+   * backend; a live foreign owner fails loudly with the owner details.
    * @returns {Promise<void>} - Resolves after the lock has been acquired.
    */
   async acquire() {
-    await fs.mkdir(path.dirname(this.lockPath), {recursive: true})
+    const acquired = await this.backend.acquire("server", {timeoutMs: 0})
 
-    while (true) {
-      const acquired = await this.tryAcquire()
+    if (!acquired) throw new Error(await this.lockHeldMessage())
 
-      if (acquired) {
-        return
-      }
-
-      if (await this.isStale()) {
-        await fs.rm(this.lockPath, {recursive: true, force: true})
-        continue
-      }
-
-      throw new Error(await this.lockHeldMessage())
-    }
-  }
-
-  /**
-   * Tries to create the lock directory and write owner metadata.
-   * @returns {Promise<boolean>} - Whether the lock was acquired.
-   */
-  async tryAcquire() {
-    try {
-      await fs.mkdir(this.lockPath)
-    } catch (error) {
-      if (/** @type {{code?: string}} */ (error).code === "EEXIST") return false
-      throw error
-    }
-
-    try {
-      await this.writeOwnerMetadata()
-      this.acquired = true
-
-      return true
-    } catch (error) {
-      await fs.rm(this.lockPath, {recursive: true, force: true})
-      throw error
-    }
+    this.acquired = true
   }
 
   /**
@@ -77,86 +54,15 @@ export default class VelociousHttpServerLock {
     if (!this.acquired) return
 
     this.acquired = false
-    await fs.rm(this.lockPath, {recursive: true, force: true})
-  }
-
-  /**
-   * Writes metadata used to explain or reclaim an existing server lock.
-   * @returns {Promise<void>} - Resolves after owner metadata has been written.
-   */
-  async writeOwnerMetadata() {
-    await fs.writeFile(path.join(this.lockPath, "owner.json"), JSON.stringify({
-      acquiredAt: new Date().toISOString(),
-      host: this.host,
-      hostname: os.hostname(),
-      pid: process.pid,
-      port: this.port
-    }))
-  }
-
-  /**
-   * Checks whether the current lock owner is a dead process on this host.
-   * @returns {Promise<boolean>} - Whether the existing lock belongs to a dead process.
-   */
-  async isStale() {
-    const owner = await this.readOwnerMetadata()
-
-    if (!this.isLocalProcessOwner(owner)) return false
-
-    return this.processIsDead(/** @type {{pid: number}} */ (owner).pid)
-  }
-
-  /**
-   * Runs is local process owner.
-   * @param {Record<string, ReturnType<typeof JSON.parse>> | null} owner - Existing lock owner metadata.
-   * @returns {boolean} - Whether owner metadata names a local process.
-   */
-  isLocalProcessOwner(owner) {
-    if (!owner) return false
-    if (typeof owner.pid !== "number") return false
-
-    return this.ownerHostnameMatches(owner)
-  }
-
-  /**
-   * Runs owner hostname matches.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} owner - Existing lock owner metadata.
-   * @returns {boolean} - Whether the owner hostname is local or absent.
-   */
-  ownerHostnameMatches(owner) {
-    if (!owner.hostname) return true
-    if (owner.hostname === os.hostname()) return true
-
-    return false
-  }
-
-  /**
-   * Runs process is dead.
-   * @param {number} pid - Process id.
-   * @returns {boolean} - Whether the process no longer exists.
-   */
-  processIsDead(pid) {
-    try {
-      process.kill(pid, 0)
-
-      return false
-    } catch (error) {
-      return /** @type {{code?: string}} */ (error).code === "ESRCH"
-    }
+    await this.backend.release("server")
   }
 
   /**
    * Reads owner metadata from an existing server lock directory.
-   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Parsed owner metadata, when readable.
+   * @returns {Promise<import("../database/advisory-lock-file-backend.js").AdvisoryLockFileOwner | null>} - Parsed owner metadata, when readable.
    */
   async readOwnerMetadata() {
-    try {
-      const rawOwner = await fs.readFile(path.join(this.lockPath, "owner.json"), "utf8")
-
-      return /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (JSON.parse(rawOwner))
-    } catch {
-      return null
-    }
+    return await this.backend.holderInfo("server")
   }
 
   /**

package/build/src/configuration-types.d.ts

@@ -1635,6 +1635,23 @@ export type TenantDatabaseProviderType = {
         tenant: ReturnType<typeof JSON.parse>;
     }) => void | Promise<void>;
 };
+export type AdvisoryLocksConfiguration = {
+    /**
+     * - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration.
+     */
+    backends?: {
+        file?: {
+            directory?: string;
+            enabled?: boolean;
+            leaseMs?: number;
+            renewIntervalMs?: number;
+        };
+    };
+    /**
+     * - Per-lock-name minimum/allowed/preferred tier rules (design §5).
+     */
+    policy?: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[];
+};
 export type ConfigurationArgsType = {
     /**
      * - Globally enable auto-batch-preload of relationships on lazy access. Default true.
@@ -1656,6 +1673,10 @@ export type ConfigurationArgsType = {
      * - Resolver for creating request-scoped ability instances.
      */
     abilityResolver?: AbilityResolverType;
+    /**
+     * - Advisory-lock backend chain configuration (backends + per-lock-name tier policy). Defaults to today's driver-native-only behavior.
+     */
+    advisoryLocks?: AdvisoryLocksConfiguration;
     /**
      * - Attachment storage configuration.
      */
@@ -2519,6 +2540,15 @@ export type ConfigurationArgsType = {
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [checkTenant] - Checks one tenant database before generic connection validation.
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, migrationsApplied: number, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [afterMigrateTenant] - Runs app-owned tenant work after generic migrations for one tenant. `migrationsApplied` is how many migrations actually ran (0 when the tenant was already up to date), so the app can skip expensive per-tenant work on no-op deploys.
  */
+/**
+ * Advisory-lock backend chain configuration (STC-210 design §10, file tier
+ * implemented by STC-213). Everything defaults to today's driver-native-only
+ * behavior; the file backend is disabled by default and only selectable by
+ * explicit configuration.
+ * @typedef {object} AdvisoryLocksConfiguration
+ * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration.
+ * @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
+ */
 /**
  * @typedef {object} ConfigurationArgsType
  * @property {boolean} [autoload] - Globally enable auto-batch-preload of relationships on lazy access. Default true.
@@ -2526,6 +2556,7 @@ export type ConfigurationArgsType = {
  * @property {string} [cookieSecret] - Secret for encrypting cookies.
  * @property {AbilityResourceClassType[]} [abilityResources] - Resource classes used to define abilities per model.
  * @property {AbilityResolverType} [abilityResolver] - Resolver for creating request-scoped ability instances.
+ * @property {AdvisoryLocksConfiguration} [advisoryLocks] - Advisory-lock backend chain configuration (backends + per-lock-name tier policy). Defaults to today's driver-native-only behavior.
  * @property {AttachmentsConfiguration} [attachments] - Attachment storage configuration.
  * @property {BackendProjectConfiguration[]} [backendProjects] - Backend project definitions used for frontend model generation.
  * @property {VelociousPackageConfiguration[]} [packages] - External Velocious packages that contribute models, frontend-model resources and migrations.