velocious 1.0.598 → 1.0.600

package/src/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/src/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/src/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)
+  })
+}

package/src/background-jobs/platform-job.js

@@ -0,0 +1,156 @@
+// @ts-check
+
+import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import {cancelScheduledBackgroundJob, enqueueBackgroundJob, replaceScheduledBackgroundJob} 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.
+ * @template {Array<ReturnType<typeof JSON.parse>>} [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
+  }
+
+  /**
+   * Runs perform later.
+   * @param {...ReturnType<typeof JSON.parse>} args - Job args.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLater(...args) {
+    const {jobArgs, jobOptions} = this._splitArgsAndOptions(args)
+    return await enqueueBackgroundJob({JobClass: this, jobArgs, jobOptions})
+  }
+
+  /**
+   * Runs perform later with options.
+   * @param {object} args - Options.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLaterWithOptions({args, options}) {
+    return await enqueueBackgroundJob({JobClass: this, jobArgs: args, jobOptions: options})
+  }
+
+  /**
+   * Atomically replaces this job class's queued owner for a stable schedule key.
+   * @param {object} args - Options.
+   * @param {string} args.scheduleKey - Stable logical schedule key.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  static async replaceScheduled({scheduleKey, args, options}) {
+    return await replaceScheduledBackgroundJob({JobClass: this, scheduleKey, jobArgs: args, jobOptions: options})
+  }
+
+  /**
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  static async cancelScheduled(scheduleKey) {
+    return await cancelScheduledBackgroundJob(scheduleKey)
+  }
+
+  /**
+   * 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")
+  }
+}

package/src/background-jobs/runtime.js

@@ -0,0 +1,156 @@
+// @ts-check
+
+import {currentConfiguration} from "../current-configuration.js"
+import performBackgroundJob from "./perform-job.js"
+import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+
+let inlinePerformanceSequence = 0
+
+/**
+ * Rejects options whose semantics require durable queue state.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} options - Requested options.
+ * @returns {void}
+ */
+function validateInlineOptions(options) {
+  const optionNames = Object.keys(options || {})
+
+  if (optionNames.length > 0) {
+    throw new Error(`Background job option ${optionNames[0]} is not supported in inline mode`)
+  }
+}
+
+/**
+ * Builds an ephemeral inline performance id.
+ * @returns {string} - Performance id.
+ */
+function inlineJobId() {
+  inlinePerformanceSequence++
+  return `inline-${Date.now()}-${inlinePerformanceSequence}`
+}
+
+/**
+ * Enqueues durably in background mode or performs immediately in inline mode.
+ * @param {object} args - Enqueue request.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
+ */
+export async function enqueueBackgroundJob({JobClass, jobArgs, jobOptions}) {
+  const configuration = currentConfiguration()
+
+  return await enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions})
+}
+
+/**
+ * Enqueues using an explicitly resolved configuration.
+ * @param {object} args - Enqueue request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
+ */
+export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    validateInlineOptions(jobOptions)
+    configuration.setCurrent()
+    await configuration.initialize({type: "background-jobs-inline"})
+
+    try {
+      await performBackgroundJob({
+        configuration,
+        JobClass,
+        jobArgs,
+        name: `Background job inline mode: ${JobClass.jobName()}`
+      })
+    } catch (error) {
+      if (error instanceof BackgroundJobRescheduleSignal) {
+        throw new Error("rescheduleIn is not supported in inline mode", {cause: error})
+      }
+
+      throw error
+    }
+
+    return inlineJobId()
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.enqueue({
+    jobName: JobClass.jobName(),
+    args: jobArgs,
+    options: JobClass._withQueue(jobOptions)
+  })
+}
+
+/**
+ * Replaces a stable durable schedule in background mode.
+ * @param {object} args - Replacement request.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {string} args.scheduleKey - Stable schedule key.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+ */
+export async function replaceScheduledBackgroundJob({JobClass, scheduleKey, jobArgs, jobOptions}) {
+  const configuration = currentConfiguration()
+
+  return await replaceScheduledBackgroundJobForConfiguration({configuration, JobClass, scheduleKey, jobArgs, jobOptions})
+}
+
+/**
+ * Replaces a stable schedule using an explicitly resolved configuration.
+ * @param {object} args - Replacement request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {string} args.scheduleKey - Stable schedule key.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+ */
+export async function replaceScheduledBackgroundJobForConfiguration({configuration, JobClass, scheduleKey, jobArgs, jobOptions}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("replaceScheduled is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.replaceScheduled({
+    scheduleKey,
+    jobName: JobClass.jobName(),
+    args: jobArgs,
+    options: JobClass._withQueue(jobOptions)
+  })
+}
+
+/**
+ * Cancels a stable durable schedule in background mode.
+ * @param {string} scheduleKey - Stable schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+ */
+export async function cancelScheduledBackgroundJob(scheduleKey) {
+  const configuration = currentConfiguration()
+
+  return await cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
+}
+
+/**
+ * Cancels a stable schedule using an explicitly resolved configuration.
+ * @param {object} args - Cancellation request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {string} args.scheduleKey - Stable logical schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+ */
+export async function cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("cancelScheduled is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.cancelScheduled({scheduleKey})
+}