velocious 1.0.599 → 1.0.601

package/README.md

@@ -775,22 +775,20 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
-Unexpected frontend-model endpoint failures return their original message by default with `errorType: "internal_error"` and a server-generated `correlationId` shared with the matching framework-error report. Set `secureFrontendModelErrors: true` to return only explicitly safe messages and otherwise `errorMessage: "Request failed."`. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
+Unexpected frontend-model endpoint failures return their original message and full stack trace by default in every environment, including production. Responses use `errorType: "internal_error"`, a server-generated `correlationId` shared with the matching framework-error report, and the established `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields without adding irrelevant debug fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
 Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
 Invalid frontend-model write attributes and attachment names, including attributes rejected by `permittedParams()`, return the specific safe error message with `velocious.code: "frontend-model-attribute-error"` and are not emitted as framework errors.
-In `development` and `test`, Velocious also includes `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields so browser/system-test failures are easier to diagnose without exposing those details in production.
-Other non-production environments, such as `staging`, keep the same client-safe default unless you explicitly opt in with `exposeInternalErrorsToClients: true`:
+To mask unexpected internal details, explicitly opt out for the application configuration:
 
 ```js
 const configuration = new Configuration({
-  environment: "staging",
-  exposeInternalErrorsToClients: true
+  exposeInternalErrorsToClients: false
 })
 ```
 
-This opt-in is ignored in `production`; production frontend-model responses never include internal exception details.
+With this opt-out, built-in commands, custom commands, and sync replay failures return `errorMessage: "Request failed."` and omit the debug message and stack fields in every environment. `secureFrontendModelErrors: true` remains a deprecated compatibility alias when `exposeInternalErrorsToClients` is omitted; an explicit `exposeInternalErrorsToClients` value always wins.
 
-Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
+Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. When exposure is disabled, Velocious strips the established debug fields even if a reporter supplies them. This is useful for attaching an error-reporting URL while keeping an opted-out error message generic:
 
 ```js
 configuration.addClientErrorPayloadReporter(async ({error, requestDetails, context}) => {
@@ -1919,7 +1917,7 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 })
 ```
 
-Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return an `internal_error` response with the original message by default (or `Request failed.` when `secureFrontendModelErrors` is enabled) and a correlation ID, then emits them as `framework-error`/`all-error` with the same correlation ID and `context.frontendModelEndpoint === true`. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` errors keep their expected-error status. A raw `errorType` property alone is not considered safe and does not suppress reporting.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return an `internal_error` response with the original message and stack trace by default (or `Request failed.` without debug fields when `exposeInternalErrorsToClients: false`) and a correlation ID, then emits them as `framework-error`/`all-error` with the same correlation ID and `context.frontendModelEndpoint === true`. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` errors keep their expected-error status without irrelevant debug fields. A raw `errorType` property alone is not considered safe and does not suppress reporting.
 
 Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
 
@@ -2264,6 +2262,7 @@ You can configure the main host/port in your configuration:
 export default new Configuration({
   // ...
   backgroundJobs: {
+    mode: "background",
     host: "127.0.0.1",
     port: 7331,
     databaseIdentifier: "default",
@@ -2280,6 +2279,16 @@ export default new Configuration({
 })
 ```
 
+`backgroundJobs.mode` is separate from a job's `executionMode`. The default
+`"background"` mode preserves the Node SQL queue, TCP main/worker transport, and
+per-job `"pooled"` execution default. `"inline"` is a platform-neutral,
+non-durable application mode: `performLater` performs immediately and rejects
+queue/scheduling/retry/execution options whose guarantees require durable state.
+Custom persistence can be supplied as a `BackgroundJobsAdapter` instance or
+synchronous factory. See [runtime modes and adapters](docs/background-jobs.md#runtime-modes-and-adapters)
+for the contract, lifecycle, Node TCP/wake behavior, the explicit
+`platform-job.js` browser/Expo entry, and SQL-only compatibility boundaries.
+
 Or via env vars:
 
 ```
@@ -2357,7 +2366,7 @@ Queue a job:
 await MyJob.performLater("a", "b")
 ```
 
-Jobs use `executionMode: "forked"` by default. This runs the job in a separate attached Node child process. To run inline:
+Durably queued jobs use `executionMode: "pooled"` by default. To run one inside the worker process instead:
 
 ```js
 await MyJob.performLaterWithOptions({

package/build/background-jobs/adapter-client.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+/** Platform-neutral producer client for a configured adapter. */
+export default class BackgroundJobsAdapterClient {
+  /**
+   * Creates an adapter-backed producer.
+   * @param {{configuration: import("../configuration.js").default}} args - Client options.
+   */
+  constructor({configuration}) {
+    this.configuration = configuration
+  }
+
+  /**
+   * Enqueues a job through the configured adapter.
+   * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Job request.
+   * @returns {Promise<string>} - Job id.
+   */
+  async enqueue(args) {
+    const adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.enqueue(args)
+  }
+
+  /**
+   * Replaces a stable schedule through the configured adapter.
+   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Replacement request.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  async replaceScheduled(args) {
+    const adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.replaceScheduled(args)
+  }
+
+  /**
+   * Cancels a stable schedule through the configured adapter.
+   * @param {{scheduleKey: string}} args - Cancellation request.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  async cancelScheduled({scheduleKey}) {
+    const adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.cancelScheduled(scheduleKey)
+  }
+}

package/build/background-jobs/adapter.js

@@ -0,0 +1,139 @@
+// @ts-check
+
+/**
+ * Platform-neutral persistence and lifecycle contract used by the background-jobs
+ * runtime. Adapters own durable queue state; transport and job execution remain
+ * separate concerns.
+ */
+export default class BackgroundJobsAdapter {
+  /**
+   * Ensures the adapter can accept work.
+   * @returns {Promise<void>} - Resolves when ready.
+   */
+  async ensureReady() { throw new Error("BackgroundJobsAdapter#ensureReady is not implemented") }
+
+  /**
+   * Closes adapter-owned resources.
+   * @returns {Promise<void>} - Resolves after close.
+   */
+  async close() {}
+
+  /**
+   * Reports adapter health.
+   * @returns {Promise<import("./types.js").BackgroundJobsHealth>} - Adapter health.
+   */
+  async health() {
+    return {ready: true}
+  }
+
+  /**
+   * Ensures framework-owned persistence during a migration lifecycle. Non-SQL
+   * adapters may leave this as a no-op.
+   * @param {{dbs: Record<string, import("../database/drivers/base.js").default>}} _args - Migrated databases.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async ensureFrameworkSchema(_args) {}
+
+  /**
+   * Reconciles configured queue limits.
+   * @returns {Promise<void>} - Resolves after reconciliation.
+   */
+  async reconcileQueueConcurrency() { throw new Error("BackgroundJobsAdapter#reconcileQueueConcurrency is not implemented") }
+
+  /**
+   * Enqueues a job.
+   * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Job request.
+   * @returns {Promise<string>} - Job id.
+   */
+  async enqueue(_args) { throw new Error("BackgroundJobsAdapter#enqueue is not implemented") }
+
+  /**
+   * Replaces the owner of a stable schedule key.
+   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Replacement request.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  async replaceScheduled(_args) { throw new Error("BackgroundJobsAdapter#replaceScheduled is not implemented") }
+
+  /**
+   * Cancels the owner of a stable schedule key.
+   * @param {string} _scheduleKey - Stable schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  async cancelScheduled(_scheduleKey) { throw new Error("BackgroundJobsAdapter#cancelScheduled is not implemented") }
+
+  /**
+   * Finds the next eligible job.
+   * @param {{executionMode?: import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]}} [_args] - Dequeue filters.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next eligible job.
+   */
+  async nextAvailableJob(_args = {}) { throw new Error("BackgroundJobsAdapter#nextAvailableJob is not implemented") }
+
+  /**
+   * Finds the soonest future job.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Soonest future job.
+   */
+  async nextScheduledJob() { throw new Error("BackgroundJobsAdapter#nextScheduledJob is not implemented") }
+
+  /**
+   * Reads one job.
+   * @param {string} _jobId - Job id.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Job row.
+   */
+  async getJob(_jobId) { throw new Error("BackgroundJobsAdapter#getJob is not implemented") }
+
+  /**
+   * Starts a job by claiming its durable handoff.
+   * @param {{jobId: string, workerId?: string}} _args - Handoff request.
+   * @returns {Promise<import("./types.js").BackgroundJobHandoff | null>} - Claimed handoff.
+   */
+  async markHandedOff(_args) { throw new Error("BackgroundJobsAdapter#markHandedOff is not implemented") }
+
+  /**
+   * Marks a handed-off job successful.
+   * @param {{jobId: string, handoffId?: string, workerId?: string, handedOffAtMs?: number}} _args - Completion report.
+   * @returns {Promise<boolean>} - Whether the fenced report was accepted.
+   */
+  async markCompleted(_args) { throw new Error("BackgroundJobsAdapter#markCompleted is not implemented") }
+
+  /**
+   * Returns a handed-off job to its schedule.
+   * @param {{jobId: string, delayMs: number, handoffId?: string, workerId?: string, handedOffAtMs?: number}} _args - Reschedule report.
+   * @returns {Promise<boolean>} - Whether the fenced report was accepted.
+   */
+  async markRescheduled(_args) { throw new Error("BackgroundJobsAdapter#markRescheduled is not implemented") }
+
+  /**
+   * Returns a handed-off job to the queue.
+   * @param {{jobId: string, handoffId: string}} _args - Handoff release.
+   * @returns {Promise<void>} - Resolves after the job is returned.
+   */
+  async markReturnedToQueue(_args) { throw new Error("BackgroundJobsAdapter#markReturnedToQueue is not implemented") }
+
+  /**
+   * Finds active handoffs for a worker.
+   * @param {{workerId: string}} _args - Worker identity.
+   * @returns {Promise<Array<{jobId: string, handoffId: string}>>} - Active worker handoffs.
+   */
+  async handedOffJobsForWorker(_args) { throw new Error("BackgroundJobsAdapter#handedOffJobsForWorker is not implemented") }
+
+  /**
+   * Marks a handed-off job failed or retryable.
+   * @param {{jobId: string, error: ReturnType<typeof JSON.parse>, handoffId?: string, workerId?: string, handedOffAtMs?: number}} _args - Failure report.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Updated job when accepted.
+   */
+  async markFailed(_args) { throw new Error("BackgroundJobsAdapter#markFailed is not implemented") }
+
+  /**
+   * Reclaims expired handoffs.
+   * @param {{orphanedAfterMs?: number}} [_args] - Sweep options.
+   * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - Newly orphaned jobs.
+   */
+  async markOrphanedJobs(_args = {}) { throw new Error("BackgroundJobsAdapter#markOrphanedJobs is not implemented") }
+
+  /**
+   * Prunes terminal jobs past their retention windows.
+   * @param {{completedTtlMs?: number | null, failedTtlMs?: number | null, batchSize?: number}} [_args] - Retention options.
+   * @returns {Promise<number>} - Deleted rows.
+   */
+  async pruneTerminalJobs(_args = {}) { throw new Error("BackgroundJobsAdapter#pruneTerminalJobs is not implemented") }
+}

package/build/background-jobs/job-registry.js

@@ -3,7 +3,7 @@
 import fs from "fs/promises"
 import path from "path"
 import toImportSpecifier from "../utils/to-import-specifier.js"
-import VelociousJob from "./job.js"
+import VelociousJob from "./platform-job.js"
 
 export default class BackgroundJobRegistry {
   /**

package/build/background-jobs/job.js

@@ -1,101 +1,31 @@
 // @ts-check
 
-import BackgroundJobsClient from "./client.js"
-import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import configurationResolver from "../configuration-resolver.js"
+import PlatformVelociousJob from "./platform-job.js"
+import {
+  cancelScheduledBackgroundJobForConfiguration,
+  enqueueBackgroundJobForConfiguration,
+  replaceScheduledBackgroundJobForConfiguration
+} from "./runtime.js"
 
 /**
- * Base class for background jobs.
- *
- * `TArgs` is the tuple of arguments the subclass's `perform` accepts, so a job that
- * needs arguments declares them as required and typed — for example
- * `class RunBuildJob extends VelociousJob<[string]>` with `async perform(buildId)`.
- * The default empty tuple keeps argument-less jobs (`extends VelociousJob`,
- * `async perform()`) working unchanged.
+ * Node background-job entry. It preserves lazy configuration discovery for
+ * fresh producer processes while the explicit platform entry stays free of
+ * Node-only configuration resolution.
  * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
+ * @augments {PlatformVelociousJob<TArgs>}
  */
-export default class VelociousJob {
-  /**
-   * Database identifiers checked out while this job performs. Set an explicit
-   * list to avoid holding unrelated configured database connections, or `[]`
-   * when the job establishes any connections it needs itself. Left undefined,
-   * jobs retain the existing behavior of checking out every active database.
-   * @type {string[] | undefined}
-   */
-  static databaseIdentifiers = undefined
-
-  /**
-   * Queue this job class runs on. Subclasses set e.g. `static queue = "builds"`
-   * to route onto a queue with its own cluster-wide concurrency cap (configured
-   * via `backgroundJobs.queues`). The `{queue}` enqueue option overrides it.
-   * Left undefined, jobs run on the `"default"` queue.
-   * @type {string | undefined}
-   */
-  static queue = undefined
-
-  /**
-   * Optional process title shown for the runner while this job executes.
-   * Velocious sets `process.title` to this for the duration of the job — so
-   * `ps`/`top`/`htop` identify what a runner is doing — and restores the
-   * runner's base title when the job finishes. Left undefined, the runner falls
-   * back to `velocious job-runner: <JobName>`. Set e.g.
-   * `static processTitle = "velocious media transcoder"` to give a job a
-   * custom, human-readable title.
-   * @type {string | undefined}
-   */
-  static processTitle = undefined
-
-  /**
-   * Stops this performance and reschedules the same logical job row. This is
-   * normal control flow: it does not count as a failure or consume a retry.
-   * @param {number} delayMs - Non-negative safe-integer delay in milliseconds.
-   * @returns {never} - This method never returns.
-   */
-  rescheduleIn(delayMs) {
-    if (!Number.isSafeInteger(delayMs) || delayMs < 0) {
-      throw new TypeError("background job reschedule delayMs must be a non-negative safe integer")
-    }
-
-    throw new BackgroundJobRescheduleSignal(delayMs)
-  }
-
-  /**
-   * Runs job name.
-   * @returns {string} - Job name.
-   */
-  static jobName() {
-    return this.name
-  }
-
-  /**
-   * Folds this job class's static `queue` into the enqueue options unless the
-   * caller already specified one.
-   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
-   * @returns {import("./types.js").BackgroundJobOptions} - Options including the resolved queue.
-   */
-  static _withQueue(options) {
-    const merged = options ? {...options} : {}
-
-    if (merged.queue === undefined && typeof this.queue === "string" && this.queue.length > 0) {
-      merged.queue = this.queue
-    }
-
-    return merged
-  }
-
+export default class VelociousJob extends PlatformVelociousJob {
   /**
    * Runs perform later.
    * @param {...ReturnType<typeof JSON.parse>} args - Job args.
    * @returns {Promise<string>} - Job id.
    */
   static async performLater(...args) {
+    const configuration = await configurationResolver()
     const {jobArgs, jobOptions} = this._splitArgsAndOptions(args)
-    const client = new BackgroundJobsClient()
 
-    return await client.enqueue({
-      jobName: this.jobName(),
-      args: jobArgs,
-      options: this._withQueue(jobOptions)
-    })
+    return await enqueueBackgroundJobForConfiguration({configuration, JobClass: this, jobArgs, jobOptions})
   }
 
   /**
@@ -106,13 +36,9 @@ export default class VelociousJob {
    * @returns {Promise<string>} - Job id.
    */
   static async performLaterWithOptions({args, options}) {
-    const client = new BackgroundJobsClient()
+    const configuration = await configurationResolver()
 
-    return await client.enqueue({
-      jobName: this.jobName(),
-      args,
-      options: this._withQueue(options)
-    })
+    return await enqueueBackgroundJobForConfiguration({configuration, JobClass: this, jobArgs: args, jobOptions: options})
   }
 
   /**
@@ -124,14 +50,9 @@ export default class VelociousJob {
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */
   static async replaceScheduled({scheduleKey, args, options}) {
-    const client = new BackgroundJobsClient()
+    const configuration = await configurationResolver()
 
-    return await client.replaceScheduled({
-      scheduleKey,
-      jobName: this.jobName(),
-      args,
-      options: this._withQueue(options)
-    })
+    return await replaceScheduledBackgroundJobForConfiguration({configuration, JobClass: this, scheduleKey, jobArgs: args, jobOptions: options})
   }
 
   /**
@@ -140,38 +61,8 @@ export default class VelociousJob {
    * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
    */
   static async cancelScheduled(scheduleKey) {
-    const client = new BackgroundJobsClient()
-
-    return await client.cancelScheduled({scheduleKey})
-  }
+    const configuration = await configurationResolver()
 
-  /**
-   * Runs split args and options.
-   * @param {Array<ReturnType<typeof JSON.parse>>} args - Job args.
-   * @returns {{jobArgs: Array<ReturnType<typeof JSON.parse>>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
-   */
-  static _splitArgsAndOptions(args) {
-    if (args.length === 0) {
-      return {jobArgs: [], jobOptions: {}}
-    }
-
-    const lastArg = args[args.length - 1]
-    const isOptionsArg = lastArg && typeof lastArg === "object" && !Array.isArray(lastArg) && "jobOptions" in lastArg
-
-    if (isOptionsArg) {
-      const {jobOptions} = /** @type {{jobOptions: import("./types.js").BackgroundJobOptions}} */ (lastArg)
-      return {jobArgs: args.slice(0, -1), jobOptions: jobOptions || {}}
-    }
-
-    return {jobArgs: args, jobOptions: {}}
-  }
-
-  /**
-   * Override in subclasses.
-   * @param {TArgs} _args - Job args (the tuple this job class was parameterized with).
-   * @returns {Promise<void>} - Resolves when complete.
-   */
-  async perform(..._args) {
-    throw new Error("perform not implemented")
+    return await cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
   }
 }

package/build/background-jobs/main.js

@@ -3,7 +3,6 @@
 import net from "net"
 import JsonSocket from "./json-socket.js"
 import BackgroundJobsScheduler from "./scheduler.js"
-import BackgroundJobsStore from "./store.js"
 import Logger from "../logger.js"
 import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jobs.js"
 import VelociousError from "../velocious-error.js"
@@ -78,7 +77,8 @@ export default class BackgroundJobsMain {
     // long is treated as wedged/dead: its leases are released and it is dropped.
     this.workerStaleTimeoutMs = typeof workerStaleTimeoutMs === "number" && workerStaleTimeoutMs >= 1 ? workerStaleTimeoutMs : WORKER_STALE_TIMEOUT_MS
     this.workerLivenessSweepMs = typeof workerLivenessSweepMs === "number" && workerLivenessSweepMs >= 1 ? workerLivenessSweepMs : WORKER_LIVENESS_SWEEP_MS
-    this.store = new BackgroundJobsStore({configuration, databaseIdentifier: config.databaseIdentifier})
+    /** @type {import("./adapter.js").default | undefined} */
+    this.adapter = undefined
     this.logger = new Logger(this)
     /**
      * Narrows the runtime value to the documented type.
@@ -146,6 +146,24 @@ export default class BackgroundJobsMain {
     this._beaconClient = undefined
   }
 
+  /**
+   * Compatibility alias for integrations that inspect the active main store.
+   * @returns {import("./adapter.js").default} - Adapter acquired by start.
+   */
+  get store() {
+    if (!this.adapter) throw new Error("Background jobs main has not acquired its adapter")
+
+    return this.adapter
+  }
+
+  /**
+   * Preserves the historical subclass seam while keeping one adapter reference.
+   * @param {import("./adapter.js").default} adapter - Adapter to assign.
+   */
+  set store(adapter) {
+    this.adapter = adapter
+  }
+
   /**
    * Runs start.
    * @returns {Promise<void>} - Resolves when listening.
@@ -154,19 +172,24 @@ export default class BackgroundJobsMain {
     this._stopped = false
     this.stopPromise = undefined
     this.configuration.setCurrent()
-    await this.configuration.initialize({type: "background-jobs-main"})
-    await this.configuration.connectBeacon({peerType: "background-jobs-main"})
-    await this.store.ensureReady()
-    // Queue-cap changes are reconciled against the persisted backlog here, at
-    // main-process startup — the explicit lifecycle for applying queue
-    // configuration changes. The store serializes the adoption/release UPDATEs
-    // across processes with a database advisory lock, so concurrently started
-    // mains cannot interleave them.
-    await this.store.reconcileQueueConcurrency()
-    const server = net.createServer((socket) => this._handleConnection(socket))
-    this.server = server
 
     try {
+      await this.configuration.initialize({type: "background-jobs-main"})
+      await this.configuration.connectBeacon({peerType: "background-jobs-main"})
+
+      if (!this.adapter) {
+        this.adapter = await this.configuration.acquireReadyBackgroundJobsAdapter()
+      }
+
+      // Queue-cap changes are reconciled against the persisted backlog here, at
+      // main-process startup — the explicit lifecycle for applying queue
+      // configuration changes. The store serializes the adoption/release UPDATEs
+      // across processes with a database advisory lock, so concurrently started
+      // mains cannot interleave them.
+      await this.store.reconcileQueueConcurrency()
+      const server = net.createServer((socket) => this._handleConnection(socket))
+      this.server = server
+
       await new Promise((resolve, reject) => {
         server.once("error", reject)
         server.listen(this.port, this.host, () => resolve(undefined))
@@ -221,7 +244,16 @@ export default class BackgroundJobsMain {
       // but this drain covers it).
       await this._drain()
     } catch (error) {
-      await this.stop()
+      try {
+        await this.stop()
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          "Background jobs main startup and cleanup failed",
+          {cause: cleanupError}
+        )
+      }
+
       throw error
     }
   }
@@ -243,20 +275,27 @@ export default class BackgroundJobsMain {
   async _stop() {
     this._stopped = true
 
-    await shutdownLifecycle({
-      onStopped: this.onStopped,
-      shutdown: async () => {
-        this._closeWorkers()
-        this._clearTimers()
-        this._disconnectBeaconHandlers()
-        await this.scheduler?.stop()
-        try {
-          await this._drainWorkerHandoffAdoptions()
-        } finally {
-          await this._stopBeaconAndServer()
+    try {
+      await shutdownLifecycle({
+        onStopped: this.onStopped,
+        shutdown: async () => {
+          this._closeWorkers()
+          this._clearTimers()
+          this._disconnectBeaconHandlers()
+          try {
+            await this.scheduler?.stop()
+          } finally {
+            try {
+              await this._drainWorkerHandoffAdoptions()
+            } finally {
+              await this._stopBeaconAndServer()
+            }
+          }
         }
-      }
-    })
+      })
+    } finally {
+      this.adapter = undefined
+    }
   }
 
   /**
@@ -318,7 +357,11 @@ export default class BackgroundJobsMain {
     try {
       await this._closeServer()
     } finally {
-      if (this.closeDatabaseConnectionsOnStop) await this.configuration.closeDatabaseConnections()
+      if (this.closeDatabaseConnectionsOnStop) {
+        await this.configuration.closeDatabaseConnections()
+      } else {
+        await this.configuration.closeBackgroundJobsAdapter()
+      }
     }
   }
 

package/build/background-jobs/perform-job.js

@@ -0,0 +1,23 @@
+// @ts-check
+
+/**
+ * Performs a job class inside its declared database-connection scope.
+ * @param {object} args - Performance options.
+ * @param {import("../configuration.js").default} args.configuration - Active configuration.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {string} args.name - Connection-scope label.
+ * @returns {Promise<void>} - Resolves after performance.
+ */
+export default async function performBackgroundJob({configuration, JobClass, jobArgs, name}) {
+  const jobInstance = new JobClass()
+  /**
+   * Narrows the generic subclass's runtime method to serialized job arguments.
+   * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>}
+   */
+  const perform = jobInstance.perform
+
+  await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name}, async () => {
+    await perform.apply(jobInstance, jobArgs)
+  })
+}