velocious 1.0.699 → 1.0.700

package/README.md

@@ -4,8 +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, 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))
+* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed, a non-throwing `withAdvisoryLockOrDefer` result for contended hot paths, event-driven slow acquire/hold duration telemetry with holder attribution, and an explicitly opt-in file-lock fallback tier with per-lock-name minimum-tier enforcement and acquisition provenance (see [docs/advisory-locks.md](docs/advisory-locks.md) and [docs/advisory-lock-backends.md](docs/advisory-lock-backends.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))
 * Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))

package/build/configuration-types.js

@@ -780,6 +780,16 @@
  * @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.
@@ -787,6 +797,7 @@
  * @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.

package/build/configuration.js

@@ -45,6 +45,7 @@ import VelociousPackage from "./packages/velocious-package.js"
 import FrontendTenantSqliteLifecycle from "./tenants/frontend-tenant-sqlite-lifecycle.js"
 import { resolveGenerationId, resolveInitialGenerationState, resolveLifecycleSocketPath } from "./background-jobs/generation-identity.js"
 import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
+import { resolveAdvisoryLockBackendPolicy } from "./database/advisory-lock-backend-policy.js"
 
 export { CurrentConfigurationNotSetError }
 
@@ -245,6 +246,20 @@ export default class VelociousConfiguration {
    * @type {Set<import("./database/drivers/base.js").default>} */
   _advisoryLockConnections = new Set()
 
+  /**
+   * Lazily created file-tier advisory-lock backend (STC-213). Stays `undefined`
+   * unless `advisoryLocks.backends.file.enabled: true` is explicitly configured —
+   * the file tier is never auto-enabled, and a non-Node environment handler
+   * (browser/Expo, no `fs`) cannot create one at all.
+   * @type {import("./database/advisory-lock-file-backend.js").default | undefined} */
+  _advisoryLockFileBackend = undefined
+
+  /**
+   * Most recent advisory-lock acquisition per lock name — the "which backend
+   * served this lock" surface (design §3).
+   * @type {Map<string, {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string}>} */
+  _advisoryLockAcquisitions = new Map()
+
   /** @type {Map<string, number>} */
   _schemaCacheGenerationsByReuseKey = new Map()
 
@@ -260,11 +275,12 @@ 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, mcp = false, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testTenantPools, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, advisoryLocks, 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, testTenantPools, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
     this._abilityResources = abilityResources || []
+    this._advisoryLocks = advisoryLocks
     this._autoload = autoload
     this._backgroundJobs = backgroundJobs
     this._beacon = beacon
@@ -4076,6 +4092,102 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Resolves the `advisoryLocks` configuration block (STC-210 design §10).
+   * Full backward compatibility: an app that configures nothing gets today's
+   * driver-native-only behavior — the file backend is **disabled by default**
+   * and only ever selectable by explicit configuration.
+   * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
+   */
+  getAdvisoryLockConfig() {
+    const configured = this._advisoryLocks || {}
+    const fileConfigured = configured.backends?.file || {}
+
+    return {
+      backends: {
+        file: {
+          directory: fileConfigured.directory,
+          enabled: fileConfigured.enabled === true,
+          leaseMs: typeof fileConfigured.leaseMs === "number" ? fileConfigured.leaseMs : 30_000,
+          renewIntervalMs: typeof fileConfigured.renewIntervalMs === "number" ? fileConfigured.renewIntervalMs : 10_000
+        }
+      },
+      policy: Array.isArray(configured.policy) ? configured.policy : []
+    }
+  }
+
+  /**
+   * Runs get advisory lock policy.
+   * @returns {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} - Per-lock-name backend policy entries.
+   */
+  getAdvisoryLockPolicy() {
+    return this.getAdvisoryLockConfig().policy
+  }
+
+  /**
+   * Resolves the effective backend policy for one lock name (design §5).
+   * @param {string} lockName - Concrete lock name.
+   * @returns {import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy} - Resolved policy.
+   */
+  resolveAdvisoryLockPolicy(lockName) {
+    return resolveAdvisoryLockBackendPolicy(lockName, this.getAdvisoryLockPolicy())
+  }
+
+  /**
+   * Returns the file-tier advisory-lock backend when this deployment has
+   * explicitly enabled it (`advisoryLocks.backends.file.enabled: true`),
+   * creating it on first use. Returns `undefined` when the tier is disabled
+   * (the default) — callers must never fall back to it implicitly. Creation
+   * goes through the environment handler so browser/Expo configurations
+   * without `fs` fail loudly instead of half-working.
+   * @returns {Promise<import("./database/advisory-lock-file-backend.js").default | undefined>} - Resolves with the enabled file backend, or undefined.
+   */
+  async getAdvisoryLockFileBackend() {
+    const config = this.getAdvisoryLockConfig()
+
+    if (!config.backends.file.enabled) return undefined
+    if (this._advisoryLockFileBackend) return this._advisoryLockFileBackend
+
+    const directory = config.backends.file.directory || `${this.getDirectory()}/tmp/advisory-locks`
+
+    this._advisoryLockFileBackend = await this.getEnvironmentHandler().createAdvisoryLockFileBackend({
+      directory,
+      leaseMs: config.backends.file.leaseMs,
+      renewIntervalMs: config.backends.file.renewIntervalMs
+    })
+
+    return this._advisoryLockFileBackend
+  }
+
+  /**
+   * Records which backend tier served one advisory-lock acquisition so
+   * `getAdvisoryLockBackendStatus()` can answer "which backend served this
+   * lock" (design §3).
+   * @param {object} args - Acquisition record.
+   * @param {string} args.lockName - Lock name.
+   * @param {import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier} args.backend - Tier that served the acquisition.
+   * @param {boolean} args.fencingSupported - Whether the serving tier carries fencing tokens.
+   * @returns {void}
+   */
+  recordAdvisoryLockAcquisition({lockName, backend, fencingSupported}) {
+    this._advisoryLockAcquisitions.set(lockName, {backend, fencingSupported, servedAt: new Date().toISOString()})
+  }
+
+  /**
+   * The "which backend served this lock" diagnostics surface (design §3):
+   * per lock name, the tier of the most recent acquisition, whether that tier
+   * carries fencing tokens, and the resolved policy (minimum/allowed/preferred
+   * tiers) for the name.
+   * @param {string} lockName - Lock name.
+   * @returns {{acquisition: {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string} | null, policy: import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy}} - Backend status for the name.
+   */
+  getAdvisoryLockBackendStatus(lockName) {
+    return {
+      acquisition: this._advisoryLockAcquisitions.get(lockName) ?? null,
+      policy: this.resolveAdvisoryLockPolicy(lockName)
+    }
+  }
+
   /**
    * Registers a dedicated connection that currently holds an advisory lock, so a
    * shutdown can close it and release the lock. See `_advisoryLockConnections`.
@@ -4155,6 +4267,15 @@ export default class VelociousConfiguration {
           // leave the rest of the connections open.
           await this._closeAdvisoryLockConnections()
         } finally {
+          try {
+            // Release file-tier advisory-lock holds explicitly (STC-213): the
+            // lease would make them reclaimable anyway, but a clean shutdown
+            // should not leave lock directories behind for the staleness path.
+            await this._advisoryLockFileBackend?.releaseAllHeld()
+          } catch (error) {
+            closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+          }
+
           for (const pool of Object.values(this.databasePools)) {
             if (!pool) continue
 

package/build/database/advisory-lock-backend-policy.js

@@ -0,0 +1,204 @@
+// @ts-check
+
+/**
+ * Advisory-lock backend tiers (STC-210 design, `docs/advisory-lock-backends.md` §1/§9).
+ * `process-local` and `file` are host-local; `driver-native` and `lock-server` are
+ * cross-host. Tier strength order (strongest first):
+ * `lock-server` ≡ `driver-native` > `file` > `process-local`.
+ * @typedef {"process-local" | "file" | "driver-native" | "lock-server"} AdvisoryLockTier
+ */
+/**
+ * One per-lock-name backend policy entry as declared in configuration (§5).
+ * @typedef {object} AdvisoryLockBackendPolicyEntry
+ * @property {string} name - Lock name or `*`-suffixed glob pattern (e.g. `background_jobs:*`).
+ * @property {AdvisoryLockTier} [minTier] - Weakest tier this name may ever be served by. Defaults to `driver-native` (default-deny).
+ * @property {AdvisoryLockTier[]} [allowedTiers] - Explicit whitelist of servable tiers. Defaults to every tier at or above `minTier`.
+ * @property {AdvisoryLockTier} [preferredTier] - Tier used when available; falling below it triggers the fallback report (§3). Defaults to `driver-native`.
+ */
+/**
+ * Policy resolved for one concrete lock name, with tier gaps already closed:
+ * `allowedTiers` always contains every tier at or above `minTier`, so a
+ * cross-host-minimum name can never be served by `file` or `process-local`.
+ * @typedef {object} ResolvedAdvisoryLockBackendPolicy
+ * @property {AdvisoryLockTier} minTier - Weakest tier this name may be served by.
+ * @property {AdvisoryLockTier[]} allowedTiers - Tiers that may serve this name (minimum-closed).
+ * @property {AdvisoryLockTier} preferredTier - Tier preferred when available.
+ * @property {AdvisoryLockBackendPolicyEntry | null} entry - The matched configuration entry, or null for the default policy.
+ */
+
+/**
+ * Thrown when an acquisition would have to be served by a tier below the
+ * lock name's declared minimum tier. Fail-closed refusal (§9): the name is
+ * never served by the weaker tier, and the refusal is reported on the
+ * framework-error channel as `advisory-lock-min-tier-refused`.
+ */
+export class AdvisoryLockMinTierRefusedError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{lockName: string, requestedBackend: AdvisoryLockTier, minTier: AdvisoryLockTier}} args - Refusal details.
+   */
+  constructor(message, {lockName, requestedBackend, minTier}) {
+    super(message)
+    this.name = "AdvisoryLockMinTierRefusedError"
+    this.lockName = lockName
+    this.requestedBackend = requestedBackend
+    this.minTier = minTier
+  }
+}
+
+/**
+ * Thrown when no enabled backend that satisfies the lock name's minimum tier
+ * is available (§9). Distinct from `AdvisoryLockTimeoutError` (a backend
+ * served the wait but the holder never released).
+ */
+export class AdvisoryLockBackendUnavailableError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{lockName: string, minTier: AdvisoryLockTier, reasons: string[]}} args - Unavailability details.
+   */
+  constructor(message, {lockName, minTier, reasons}) {
+    super(message)
+    this.name = "AdvisoryLockBackendUnavailableError"
+    this.lockName = lockName
+    this.minTier = minTier
+    this.reasons = reasons
+  }
+}
+
+/**
+ * Tier strength ranks (§9): higher rank is stronger. `lock-server` and
+ * `driver-native` are both cross-host and rank equal.
+ * @type {Record<AdvisoryLockTier, number>} */
+const TIER_RANKS = {
+  "driver-native": 2,
+  file: 1,
+  "lock-server": 3,
+  "process-local": 0
+}
+
+/** All tiers ordered strongest-first. */
+const TIERS_STRONGEST_FIRST = /** @type {AdvisoryLockTier[]} */ (["lock-server", "driver-native", "file", "process-local"])
+
+/**
+ * Runs tier rank.
+ * @param {AdvisoryLockTier} tier - Tier to rank.
+ * @returns {number} - Strength rank (higher is stronger).
+ */
+export function advisoryLockTierRank(tier) {
+  const rank = TIER_RANKS[tier]
+
+  if (rank === undefined) throw new Error(`Unknown advisory-lock tier ${JSON.stringify(String(tier))}`)
+
+  return rank
+}
+
+/**
+ * Runs tier is at least as strong as.
+ * @param {AdvisoryLockTier} tier - Candidate serving tier.
+ * @param {AdvisoryLockTier} minimum - Required minimum tier.
+ * @returns {boolean} - Whether `tier` satisfies the minimum.
+ */
+export function advisoryLockTierSatisfies(tier, minimum) {
+  return advisoryLockTierRank(tier) >= advisoryLockTierRank(minimum)
+}
+
+/**
+ * Resolves the effective backend policy for one concrete lock name:
+ * longest-prefix glob match over the configured entries (exact names win),
+ * default-deny for undeclared names (`minTier: driver-native`,
+ * `preferredTier: driver-native`), and `allowedTiers` closed upward so a
+ * cross-host minimum can never be served by a host-local tier.
+ * @param {string} lockName - Concrete lock name.
+ * @param {AdvisoryLockBackendPolicyEntry[] | undefined} policy - Configured policy entries.
+ * @returns {ResolvedAdvisoryLockBackendPolicy} - Resolved policy.
+ */
+export function resolveAdvisoryLockBackendPolicy(lockName, policy) {
+  const entry = matchAdvisoryLockPolicyEntry(lockName, policy)
+  const minTier = entry?.minTier ?? "driver-native"
+  const preferredTier = entry?.preferredTier ?? "driver-native"
+
+  // §9: eligibility filters to tier strength >= minTier even when a weaker
+  // tier was declared in `allowedTiers` — a cross-host minimum can never be
+  // served by `file` or `process-local`. A `preferredTier` below the minimum
+  // stays visible here so the runner can refuse it loudly before contacting
+  // the weaker backend.
+  const declaredAllowed = entry?.allowedTiers
+  const allowedTiers = TIERS_STRONGEST_FIRST.filter((tier) => {
+    if (!advisoryLockTierSatisfies(tier, minTier)) return false
+
+    if (!Array.isArray(declaredAllowed)) return true
+
+    return declaredAllowed.includes(tier)
+  })
+
+  return {allowedTiers, entry: entry ?? null, minTier, preferredTier}
+}
+
+/**
+ * Matches one policy entry for a lock name: exact `name` matches win;
+ * otherwise the longest `*`-suffixed prefix pattern wins.
+ * @param {string} lockName - Concrete lock name.
+ * @param {AdvisoryLockBackendPolicyEntry[] | undefined} policy - Configured policy entries.
+ * @returns {AdvisoryLockBackendPolicyEntry | null} - Matched entry or null.
+ */
+function matchAdvisoryLockPolicyEntry(lockName, policy) {
+  if (!Array.isArray(policy)) return null
+
+  let bestPrefixMatch = null
+  let bestPrefixLength = -1
+
+  for (const entry of policy) {
+    if (typeof entry?.name !== "string") continue
+
+    if (entry.name === lockName) return entry
+
+    if (entry.name.endsWith("*")) {
+      const prefix = entry.name.slice(0, -1)
+
+      if (lockName.startsWith(prefix) && prefix.length > bestPrefixLength) {
+        bestPrefixMatch = entry
+        bestPrefixLength = prefix.length
+      }
+    }
+  }
+
+  return bestPrefixMatch
+}
+
+/**
+ * Refuses a downgrade below the lock name's minimum tier before any contact
+ * with the weaker backend (§9), reporting the refusal on the framework-error
+ * channel so a silent downgrade is impossible to hide.
+ * @param {object} args - Refusal args.
+ * @param {import("../configuration.js").default} args.configuration - Configuration owning the error channel.
+ * @param {string} args.lockName - Lock name.
+ * @param {AdvisoryLockTier} args.requestedBackend - Tier the acquisition would fall to.
+ * @param {AdvisoryLockTier} args.minTier - Declared minimum tier.
+ * @returns {never} - Always throws.
+ */
+export function refuseAdvisoryLockTierBelowMinimum({configuration, lockName, requestedBackend, minTier}) {
+  const error = new AdvisoryLockMinTierRefusedError(
+    `Advisory lock ${JSON.stringify(lockName)} requires minimum tier ${JSON.stringify(minTier)}; the ${JSON.stringify(requestedBackend)} tier is refused. Enable a cross-host backend or declare minTier: "file" for this lock name (single-host deployments only).`,
+    {lockName, minTier, requestedBackend}
+  )
+
+  configuration.getErrorEvents().emit("framework-error", {
+    context: "advisory-lock-min-tier-refused",
+    error,
+    lockName,
+    minTier,
+    requestedBackend
+  })
+  configuration.getErrorEvents().emit("all-error", {
+    context: "advisory-lock-min-tier-refused",
+    error,
+    errorType: "framework-error",
+    lockName,
+    minTier,
+    requestedBackend
+  })
+
+  throw error
+}