velocious 1.0.598 → 1.0.600

package/src/background-jobs/sql-adapter.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+import BackgroundJobsStore from "./store.js"
+
+/** Built-in SQL adapter preserving the existing durable store implementation. */
+export default class SqlBackgroundJobsAdapter extends BackgroundJobsStore {
+  /**
+   * Ensures the built-in SQL schema during migration.
+   * @param {{dbs: Record<string, import("../database/drivers/base.js").default>}} args - Migrated databases.
+   * @returns {Promise<void>} - Resolves when the SQL schema is present.
+   */
+  async ensureFrameworkSchema({dbs}) {
+    const databaseIdentifier = this.getDatabaseIdentifier() || "default"
+    const frameworkDb = dbs[databaseIdentifier]
+
+    if (!frameworkDb) return
+
+    await this.ensureSchema(frameworkDb)
+  }
+}

package/src/background-jobs/store.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {createHash, randomUUID} from "crypto"
+import BackgroundJobsAdapter from "./adapter.js"
 import Logger from "../logger.js"
 import TableData from "../database/table-data/index.js"
 import VelociousError from "../velocious-error.js"
@@ -100,7 +101,7 @@ const schemaApplyChains = new Map()
 /** @type {Map<string, Promise<void>>} */
 const transactionMutationChains = new Map()
 
-export default class BackgroundJobsStore {
+export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   /**
    * Runs constructor.
    * @param {object} args - Options.
@@ -108,6 +109,7 @@ export default class BackgroundJobsStore {
    * @param {string} [args.databaseIdentifier] - Database identifier.
    */
   constructor({configuration, databaseIdentifier}) {
+    super()
     this.configuration = configuration
     this.databaseIdentifier = databaseIdentifier
     this.logger = new Logger(this)

package/src/background-jobs/types.js

@@ -3,6 +3,16 @@
 /**
  * @typedef {"inline" | "forked" | "pooled" | "spawned"} BackgroundJobExecutionMode
  */
+/**
+ * @typedef {object} BackgroundJobsHealth
+ * @property {boolean} ready - Whether the adapter can accept and process work.
+ */
+/**
+ * @typedef {object} BackgroundJobsProducer
+ * @property {(args: {jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<string>} enqueue - Enqueues a job.
+ * @property {(args: {scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<BackgroundJobReplacementResult>} replaceScheduled - Replaces a stable schedule.
+ * @property {(args: {scheduleKey: string}) => Promise<BackgroundJobCancellationResult>} cancelScheduled - Cancels a stable schedule.
+ */
 /**
  * @typedef {object} BackgroundJobHandoff
  * @property {string} handoffId - Unique handoff lease id.

package/src/background-jobs/web/controller.js

@@ -99,11 +99,14 @@ export default class VelociousBackgroundJobsWebController extends Controller {
    */
   async health() {
     await this._respond(async () => {
+      const health = await this.getConfiguration().backgroundJobsHealth()
+
       await this.render({json: {
         capabilities: {backgroundJobCountDeltas: 1},
-        ok: true,
+        ok: health.ready,
+        ready: health.ready,
         service: "velocious-background-jobs"
-      }})
+      }, status: health.ready ? 200 : 503})
     })
   }
 

package/src/background-jobs/worker.js

@@ -10,6 +10,7 @@ import {randomUUID} from "crypto"
 import {fileURLToPath} from "node:url"
 import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import performBackgroundJob from "./perform-job.js"
 
 /**
  * Per-forked-child timeout bookkeeping.
@@ -958,14 +959,11 @@ export default class BackgroundJobsWorker {
     const registry = new BackgroundJobRegistry({configuration})
     await registry.load()
     const JobClass = registry.getJobByName(payload.jobName)
-    const jobInstance = new JobClass()
-    /**
-     * Perform.
-     * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
-    const perform = jobInstance.perform
-
-    await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job worker inline: ${payload.jobName}`}, async () => {
-      await perform.apply(jobInstance, payload.args || [])
+    await performBackgroundJob({
+      configuration,
+      JobClass,
+      jobArgs: payload.args || [],
+      name: `Background job worker inline: ${payload.jobName}`
     })
   }
 

package/src/configuration-types.js

@@ -156,8 +156,13 @@
  *   `background_jobs` table (see `pollIntervalMs`).
  */
 
+/** @typedef {"background" | "inline"} BackgroundJobsMode */
+/** @typedef {(args: {configuration: import("./configuration.js").default}) => import("./background-jobs/adapter.js").default} BackgroundJobsAdapterFactory */
+
 /**
  * @typedef {object} BackgroundJobsConfiguration
+ * @property {import("./background-jobs/adapter.js").default | BackgroundJobsAdapterFactory} [adapter] - Adapter instance or synchronous factory. A factory creates one adapter per configuration lifecycle; the framework closes adapters it resolves.
+ * @property {BackgroundJobsMode} [mode] - `"background"` uses the configured adapter/transport and durable queue semantics; `"inline"` performs immediately without durable queue state. Defaults to `"background"`.
  * @property {string} [host] - Hostname for the background jobs main process.
  * @property {number} [port] - Port for the background jobs main process.
  * @property {string} [databaseIdentifier] - Database identifier used to store background jobs.

package/src/configuration.js

@@ -11,11 +11,20 @@
  * @property {string[]} [databaseIdentifiers] - Database identifiers to include in the connection scope.
  * @property {string} [name] - Human-readable name for the checked-out database connections.
  */
+/**
+ * One adapter instance and its serialized ready/close lifecycle.
+ * @typedef {object} BackgroundJobsAdapterGeneration
+ * @property {import("./background-jobs/adapter.js").default} adapter - Adapter owned by this generation.
+ * @property {boolean} closing - Whether close has claimed this generation.
+ * @property {Promise<void> | undefined} readyPromise - Shared readiness attempt.
+ * @property {Promise<void> | undefined} closePromise - Shared close operation.
+ */
 
 import {digg} from "diggerize"
 import gettextConfig from "gettext-universal/build/src/config.js"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
+import BackgroundJobsAdapter from "./background-jobs/adapter.js"
 import DatabaseOperation from "./database/operation.js"
 import {initializeAuditedModelRelationships} from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
@@ -204,6 +213,9 @@ export default class VelociousConfiguration {
    * @type {Promise<void> | null} */
   _closeDatabaseConnectionsPromise = null
 
+  /** @type {BackgroundJobsAdapterGeneration | undefined} */
+  _backgroundJobsAdapterGeneration = undefined
+
   /**
    * Dedicated advisory-lock connections currently holding a lock. These are spawned
    * outside the pools' tracked sets (so a hold-timeout lock survives pool checkouts),
@@ -268,7 +280,7 @@ export default class VelociousConfiguration {
     this.debug = debug
     this._debugEndpoint = this._normalizeDebugEndpoint(debugEndpoint)
     this._apiManifest = this._normalizeApiManifest(apiManifest)
-    this._environment = environment || process.env.VELOCIOUS_ENV || process.env.NODE_ENV || "development"
+    this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
     this._exposeInternalErrorsToClients = exposeInternalErrorsToClients
@@ -1441,22 +1453,23 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get background jobs config.
-   * @returns {Required<import("./configuration-types.js").BackgroundJobsConfiguration> & {retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
+   * @returns {Omit<Required<import("./configuration-types.js").BackgroundJobsConfiguration>, "adapter" | "retention"> & {retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
    */
   getBackgroundJobsConfig() {
-    const envHost = process.env.VELOCIOUS_BACKGROUND_JOBS_HOST
-    const envPortRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_PORT
-    const envDatabaseIdentifier = process.env.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
-    const envMaxConcurrentForkedRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
-    const envMaxConcurrentRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
-    const envPooledRunnerCountRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
-    const envPooledRunnerConcurrencyRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_CONCURRENCY
-    const envPooledRunnerMaxJobsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
-    const envPooledRunnerMaxRssBytesRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
-    const envPooledRunnerMaxLifetimeMsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
-    const envDispatchStrategy = process.env.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
-    const envPollIntervalRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
-    const envJobTimeoutRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
+    const processEnvironment = globalThis.process?.env
+    const envHost = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_HOST
+    const envPortRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_PORT
+    const envDatabaseIdentifier = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
+    const envMaxConcurrentForkedRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
+    const envMaxConcurrentRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
+    const envPooledRunnerCountRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
+    const envPooledRunnerConcurrencyRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_CONCURRENCY
+    const envPooledRunnerMaxJobsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
+    const envPooledRunnerMaxRssBytesRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
+    const envPooledRunnerMaxLifetimeMsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
+    const envDispatchStrategy = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
+    const envPollIntervalRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
+    const envJobTimeoutRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
     const envPort = envPortRaw ? Number(envPortRaw) : undefined
     const envMaxConcurrentForked = envMaxConcurrentForkedRaw ? Number(envMaxConcurrentForkedRaw) : undefined
     const envMaxConcurrent = envMaxConcurrentRaw ? Number(envMaxConcurrentRaw) : undefined
@@ -1468,6 +1481,11 @@ export default class VelociousConfiguration {
     const envPollInterval = envPollIntervalRaw ? Number(envPollIntervalRaw) : undefined
     const envJobTimeout = envJobTimeoutRaw ? Number(envJobTimeoutRaw) : undefined
     const configured = this._backgroundJobs || {}
+    const mode = configured.mode === undefined ? "background" : configured.mode
+
+    if (mode !== "background" && mode !== "inline") {
+      throw new TypeError(`backgroundJobs.mode must be "background" or "inline", got: ${String(mode)}`)
+    }
     const host = configured.host || envHost || "127.0.0.1"
     const port = typeof configured.port === "number"
       ? configured.port
@@ -1522,7 +1540,146 @@ export default class VelociousConfiguration {
         : 60 * 60 * 1000
     }
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+  }
+
+  /**
+   * Resolves and memoizes one background-jobs adapter for this configuration lifecycle.
+   * @returns {BackgroundJobsAdapter} - Active adapter.
+   */
+  getBackgroundJobsAdapter() {
+    if (this._backgroundJobsAdapterGeneration) return this._backgroundJobsAdapterGeneration.adapter
+
+    const configuredAdapter = this._backgroundJobs?.adapter
+    const adapter = typeof configuredAdapter === "function"
+      ? configuredAdapter({configuration: this})
+      : (configuredAdapter || this.getEnvironmentHandler().createBackgroundJobsAdapter({configuration: this}))
+
+    if (!(adapter instanceof BackgroundJobsAdapter)) {
+      throw new TypeError("backgroundJobs.adapter must be a BackgroundJobsAdapter instance or a synchronous factory returning one")
+    }
+
+    this._backgroundJobsAdapterGeneration = {
+      adapter,
+      closing: false,
+      closePromise: undefined,
+      readyPromise: undefined
+    }
+    return adapter
+  }
+
+  /**
+   * Atomically acquires the exact ready adapter for the active lifecycle.
+   * A close that claims the generation while readiness is pending wins: this
+   * operation waits for that close, creates the next generation, readies it,
+   * and returns only that live instance.
+   * @returns {Promise<BackgroundJobsAdapter>} - Exact ready adapter generation.
+   */
+  async acquireReadyBackgroundJobsAdapter() {
+    while (true) {
+      const databaseClosePromise = this._closeDatabaseConnectionsPromise
+
+      if (databaseClosePromise) {
+        await databaseClosePromise
+        continue
+      }
+
+      this.getBackgroundJobsAdapter()
+      const generation = this._backgroundJobsAdapterGeneration
+
+      if (!generation) throw new Error("Background jobs adapter generation was not created")
+
+      if (generation.closing) {
+        if (generation.closePromise) await generation.closePromise
+        continue
+      }
+
+      const readyPromise = generation.readyPromise || Promise.resolve().then(async () => {
+        await generation.adapter.ensureReady()
+      })
+
+      generation.readyPromise = readyPromise
+
+      try {
+        await readyPromise
+      } catch (error) {
+        if (generation.readyPromise === readyPromise) generation.readyPromise = undefined
+        throw error
+      }
+
+      if (generation.closing) {
+        if (generation.closePromise) await generation.closePromise
+        continue
+      }
+
+      if (this._backgroundJobsAdapterGeneration !== generation) continue
+
+      return generation.adapter
+    }
+  }
+
+  /**
+   * Readies the active adapter once per lifecycle. A failed attempt remains retryable.
+   * @returns {Promise<void>} - Resolves when ready.
+   */
+  async ensureBackgroundJobsAdapterReady() {
+    await this.acquireReadyBackgroundJobsAdapter()
+  }
+
+  /**
+   * Returns health without resolving persistence in non-durable inline mode.
+   * @returns {Promise<import("./background-jobs/types.js").BackgroundJobsHealth>} - Current health.
+   */
+  async backgroundJobsHealth() {
+    if (this.getBackgroundJobsConfig().mode === "inline") return {ready: true}
+
+    const adapter = await this.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.health()
+  }
+
+  /**
+   * Closes the resolved adapter once and clears lifecycle caches.
+   * @returns {Promise<void>} - Resolves after close.
+   */
+  async closeBackgroundJobsAdapter() {
+    const generation = this._backgroundJobsAdapterGeneration
+
+    if (!generation) return
+    if (generation.closePromise) return await generation.closePromise
+
+    generation.closing = true
+    const closePromise = (async () => {
+      /** @type {Error[]} */
+      const closeErrors = []
+
+      if (generation.readyPromise) {
+        try {
+          await generation.readyPromise
+        } catch (error) {
+          closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      try {
+        await generation.adapter.close()
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
+
+      if (closeErrors.length === 1) throw closeErrors[0]
+      if (closeErrors.length > 1) throw new AggregateError(closeErrors, "Failed to ready and close the background-jobs adapter")
+    })()
+
+    generation.closePromise = closePromise
+
+    try {
+      await closePromise
+    } finally {
+      if (this._backgroundJobsAdapterGeneration === generation) {
+        this._backgroundJobsAdapterGeneration = undefined
+      }
+    }
   }
 
   /**
@@ -1531,6 +1688,10 @@ export default class VelociousConfiguration {
    * @returns {void}
    */
   setBackgroundJobsConfig(backgroundJobs) {
+    if (this._backgroundJobsAdapterGeneration && backgroundJobs.adapter !== undefined) {
+      throw new Error("Cannot replace backgroundJobs.adapter during an active adapter lifecycle; close it first")
+    }
+
     this._backgroundJobs = Object.assign({}, this._backgroundJobs, backgroundJobs)
   }
 
@@ -2099,8 +2260,8 @@ export default class VelociousConfiguration {
     }
 
     const initializeModelsPromise = (async () => {
-      const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
-        && process.env.VELOCIOUS_BROWSER_TESTS === "true"
+      const shouldSkipDummyModelInitialization = globalThis.process?.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
+        && globalThis.process?.env.VELOCIOUS_BROWSER_TESTS === "true"
         && this.getEnvironment() === "test"
 
       if (!shouldSkipDummyModelInitialization) {
@@ -3425,34 +3586,50 @@ export default class VelociousConfiguration {
     const constructors = new Set()
 
     this._closeDatabaseConnectionsPromise = (async () => {
-      try {
-        // Close dedicated advisory-lock connections first: they are spawned outside the
-        // pools' tracked sets, so `pool.closeAll()` would not reach them and a lock held
-        // by a runner torn down mid-pass would leak until the DB server's `wait_timeout`.
-        // Still close the pools even if this throws, so a stuck lock connection does not
-        // leave the rest of the connections open.
-        await this._closeAdvisoryLockConnections()
-      } finally {
-        for (const pool of Object.values(this.databasePools)) {
-          if (!pool) continue
+      /** @type {Error[]} */
+      const closeErrors = []
 
-          await pool.closeAll()
+      try {
+        await this.closeBackgroundJobsAdapter()
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
 
-          const PoolClass = /** @type {typeof import("./database/pool/base.js").default} */ (pool.constructor)
-          constructors.add(PoolClass)
-        }
+      try {
+        try {
+          // Close dedicated advisory-lock connections first: they are spawned outside the
+          // pools' tracked sets, so `pool.closeAll()` would not reach them and a lock held
+          // by a runner torn down mid-pass would leak until the DB server's `wait_timeout`.
+          // Still close the pools if this throws, so a stuck lock connection does not
+          // leave the rest of the connections open.
+          await this._closeAdvisoryLockConnections()
+        } finally {
+          for (const pool of Object.values(this.databasePools)) {
+            if (!pool) continue
+
+            await pool.closeAll()
+
+            const PoolClass = /** @type {typeof import("./database/pool/base.js").default} */ (pool.constructor)
+            constructors.add(PoolClass)
+          }
 
-        for (const PoolClass of constructors) {
-          PoolClass.clearGlobalConnections(this)
-        }
+          for (const PoolClass of constructors) {
+            PoolClass.clearGlobalConnections(this)
+          }
 
-        this._frontendTenantSqliteLifecycle.reset()
+          this._frontendTenantSqliteLifecycle.reset()
 
-        // Allow full re-initialization after connections are closed.
-        this._modelInitializationGeneration += 1
-        this._modelsInitialized = false
-        this._isInitialized = false
+          // Allow full re-initialization after connections are closed.
+          this._modelInitializationGeneration += 1
+          this._modelsInitialized = false
+          this._isInitialized = false
+        }
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
       }
+
+      if (closeErrors.length === 1) throw closeErrors[0]
+      if (closeErrors.length > 1) throw new AggregateError(closeErrors, "Failed to close background-jobs and database resources")
     })()
 
     try {

package/src/environment-handlers/base.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import BackgroundJobsAdapterClient from "../background-jobs/adapter-client.js"
 import {validateTimeZone} from "../time-zone.js"
 
 /**
@@ -575,6 +576,25 @@ export default class VelociousEnvironmentHandlerBase {
     return
   }
 
+  /**
+   * Creates the environment's default persistence adapter.
+   * @abstract
+   * @param {{configuration: import("../configuration.js").default}} _args - Adapter options.
+   * @returns {import("../background-jobs/adapter.js").default} - Default adapter.
+   */
+  createBackgroundJobsAdapter(_args) {
+    throw new Error("This environment requires an explicit backgroundJobs.adapter")
+  }
+
+  /**
+   * Creates the platform-neutral producer path for an explicit adapter.
+   * @param {{configuration: import("../configuration.js").default}} args - Client options.
+   * @returns {import("../background-jobs/types.js").BackgroundJobsProducer} - Adapter-backed producer.
+   */
+  backgroundJobsClient(args) {
+    return new BackgroundJobsAdapterClient(args)
+  }
+
   /**
    * Runs require command.
    * @abstract

package/src/environment-handlers/node.js

@@ -2,6 +2,8 @@
 
 import "../database/annotations-async-hooks.js"
 import Base from "./base.js"
+import BackgroundJobsClient from "../background-jobs/client.js"
+import SqlBackgroundJobsAdapter from "../background-jobs/sql-adapter.js"
 import CliCommandsDestroyMigration from "./node/cli/commands/destroy/migration.js"
 import CliCommandsInit from "./node/cli/commands/init.js"
 import CliCommandsGenerateBaseModels from "./node/cli/commands/generate/base-models.js"
@@ -65,6 +67,25 @@ function pathWithinAllowedPrefixes(filePath, allowedPathPrefixes) {
 }
 
 export default class VelociousEnvironmentHandlerNode extends Base{
+  /**
+   * Creates the built-in SQL persistence adapter.
+   * @param {{configuration: import("../configuration.js").default}} args - Adapter options.
+   * @returns {SqlBackgroundJobsAdapter} - SQL adapter.
+   */
+  createBackgroundJobsAdapter({configuration}) {
+    return new SqlBackgroundJobsAdapter({configuration})
+  }
+
+  /**
+   * Preserves the Node TCP producer and main-process wake-up path. The main
+   * owns the configured persistence adapter; Node producers never bypass it.
+   * @param {{configuration: import("../configuration.js").default}} args - Client options.
+   * @returns {import("../background-jobs/types.js").BackgroundJobsProducer} - Producer client.
+   */
+  backgroundJobsClient({configuration}) {
+    return new BackgroundJobsClient({configuration})
+  }
+
   /**
    * Gives concurrent shared-transaction child jobs independent proxy sessions.
    * A configured single-connection pool shares mutable transaction state between
@@ -1100,26 +1121,12 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async ensureFrameworkSchema({dbs}) {
-    const {default: BackgroundJobsStore} = await import("../background-jobs/store.js")
-    const store = new BackgroundJobsStore({configuration: this.getConfiguration()})
-    const databaseIdentifier = store.getDatabaseIdentifier() ?? "default"
-    const frameworkDb = dbs[databaseIdentifier]
-
-    // Only ensure the framework schema when the background-jobs database is actually
-    // part of this migrate operation. When it isn't among the migrated set — e.g.
-    // `db:tenants:migrate <tenant>`, which migrates only tenant databases — the
-    // framework store lives elsewhere (typically the default DB) and was already
-    // ensured by the plain `db:migrate` that precedes it. Reaching into it here would
-    // open a fresh connection to that shared database once per tenant worker for
-    // schema work that is already applied. So skip when the framework DB isn't in
-    // this set; the runtime store still creates it lazily if a plain migrate never
-    // ran. Queue-cap reconciliation never runs on this path at all — it belongs to
-    // main-process startup (`BackgroundJobsStore#reconcileQueueConcurrency`).
-    if (!frameworkDb) return
-
-    // Reuse the connection db:migrate already holds for this database; opening a
-    // nested checkout would deadlock a database whose pool is capped at one connection.
-    await store.ensureSchema(frameworkDb)
+    // Migration passes its already checked-out DB into the adapter hook. Do not
+    // run runtime readiness here: SQL readiness would open a nested checkout and
+    // can deadlock a single-connection migration pool.
+    const adapter = this.getConfiguration().getBackgroundJobsAdapter()
+
+    await adapter.ensureFrameworkSchema({dbs})
   }
 
   /**

package/src/jobs/prune-terminal-background-jobs.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import BackgroundJobsStore from "../background-jobs/store.js"
 import Configuration from "../configuration.js"
 import VelociousJob from "../background-jobs/job.js"
 
@@ -59,9 +58,9 @@ export default class PruneTerminalBackgroundJobsJob extends VelociousJob {
   async perform() {
     const configuration = Configuration.current()
     const config = configuration.getBackgroundJobsConfig()
-    const store = new BackgroundJobsStore({configuration, databaseIdentifier: config.databaseIdentifier})
+    const adapter = await configuration.acquireReadyBackgroundJobsAdapter()
 
-    await store.pruneTerminalJobs({
+    await adapter.pruneTerminalJobs({
       completedTtlMs: config.retention.completedTtlMs,
       failedTtlMs: config.retention.failedTtlMs,
       batchSize: config.retention.batchSize