velocious 1.0.606 → 1.0.608

package/build/background-jobs/main.js

@@ -1354,7 +1354,8 @@ export default class BackgroundJobsMain {
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
-              executionMode: job.executionMode
+              executionMode: job.executionMode,
+              ...(job.timeoutMs === null ? {} : {timeoutMs: job.timeoutMs})
             }
           }
         })

package/build/background-jobs/store.js

@@ -9,6 +9,19 @@ import BackgroundJobRecord from "./job-record.js"
 import normalizeBackgroundJobError from "./normalize-error.js"
 import {coordinateSharedTransactionConnection} from "../testing/shared-transaction-connection-coordinator.js"
 import stableJsonStringify from "../utils/stable-json.js"
+import {
+  BACKGROUND_JOB_EXECUTION_MODES,
+  DEFAULT_BACKGROUND_JOB_EXECUTION_MODE,
+  DEFAULT_BACKGROUND_JOB_QUEUE,
+  QUEUE_CONCURRENCY_KEY_PREFIX,
+  normalizeBackgroundJobConcurrency,
+  normalizeBackgroundJobExecutionMode,
+  normalizeBackgroundJobMaxRetries,
+  normalizeBackgroundJobQueue,
+  normalizeBackgroundJobScheduledAtMs,
+  rescheduledBackgroundJobAtMs,
+  retryDelayMs
+} from "./job-semantics.js"
 import {
   MAIL_DELIVERY_OPERATIONS_TABLE,
   mailDeliveryOperationForJob,
@@ -27,6 +40,7 @@ import {
  * @property {number} maxRetries - Retry cap.
  * @property {string} queue - Queue name.
  * @property {number} scheduledAtMs - Eligibility timestamp.
+ * @property {number | null} timeoutMs - Per-job timeout override, or null when omitted.
  */
 
 const MIGRATIONS_TABLE = "velocious_internal_migrations"
@@ -52,22 +66,9 @@ const COUNTS_REVISION_KEY = "counts"
 export const BACKGROUND_JOB_COUNTS_CHANNEL = "velocious-background-job-counts"
 export const BACKGROUND_JOB_COUNT_BUCKETS = ["all", "queued", "handed_off", "completed", "failed", "orphaned"]
 const COUNTED_JOB_STATUSES = BACKGROUND_JOB_COUNT_BUCKETS.slice(1)
-const DEFAULT_MAX_RETRIES = 10
+const MAX_JOB_TIMEOUT_MS = 2_147_483_647
+const JOB_TIMEOUT_VALIDATION_MESSAGE = `background job timeoutMs must be a finite non-positive number or an integer between 1 and ${MAX_JOB_TIMEOUT_MS}`
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
-/**
- * Execution modes.
- * @type {import("./types.js").BackgroundJobExecutionMode[]} */
-const EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
-/**
- * Execution mode for a new enqueue that names neither `executionMode` nor the
- * legacy `forked` flag. Pooled routes the job to a warm, reused local runner
- * process — the same isolation as forked without paying a fresh process per job.
- * @type {import("./types.js").BackgroundJobExecutionMode} */
-const DEFAULT_EXECUTION_MODE = "pooled"
-const DEFAULT_QUEUE = "default"
-// Queue-derived durable concurrency keys are namespaced so they can't collide
-// with explicit caller-supplied concurrencyKeys.
-const QUEUE_CONCURRENCY_KEY_PREFIX = "queue:"
 
 /**
  * Columns the dashboard is allowed to sort job listings by, mapped to their
@@ -498,7 +499,8 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       maxRetries: preparedJob.maxRetries,
       queue: preparedJob.queue,
       scheduledAtMs: options.scheduledAtMs === undefined ? null : preparedJob.scheduledAtMs,
-      scheduling: options.scheduledAtMs === undefined ? "immediate" : "scheduled"
+      scheduling: options.scheduledAtMs === undefined ? "immediate" : "scheduled",
+      ...(preparedJob.timeoutMs === null ? {} : {timeoutMs: preparedJob.timeoutMs})
     })
 
     return createHash("sha256").update(serialized).digest("hex")
@@ -783,7 +785,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       .map(([queue, priority]) => `WHEN ${db.quote(queue)} THEN ${priority}`)
       .join(" ")
 
-    return `CASE COALESCE(${queueColumn}, ${db.quote(DEFAULT_QUEUE)}) ${whens} ELSE 0 END`
+    return `CASE COALESCE(${queueColumn}, ${db.quote(DEFAULT_BACKGROUND_JOB_QUEUE)}) ${whens} ELSE 0 END`
   }
 
   /**
@@ -1302,13 +1304,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Delay in milliseconds.
    */
   getRetryDelayMs(retryCount) {
-    const scheduleSeconds = [10, 60, 600, 3600]
-
-    if (retryCount <= scheduleSeconds.length) {
-      return scheduleSeconds[retryCount - 1] * 1000
-    }
-
-    return (retryCount - 3) * 60 * 60 * 1000
+    return retryDelayMs(retryCount)
   }
 
   /**
@@ -1332,8 +1328,33 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       jobName,
       maxRetries: this._normalizeMaxRetries(options?.maxRetries),
       queue,
-      scheduledAtMs: this._normalizeScheduledAtMs(options?.scheduledAtMs, createdAtMs)
+      scheduledAtMs: this._normalizeScheduledAtMs(options?.scheduledAtMs, createdAtMs),
+      timeoutMs: this._normalizeJobTimeoutMs(options)
+    }
+  }
+
+  /**
+   * Normalizes a per-job timeout while preserving omitted (worker fallback)
+   * separately from explicitly disabled.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {number | null} - Positive timeout, zero for disabled, or null when omitted.
+   */
+  _normalizeJobTimeoutMs(options) {
+    if (options?.timeoutMs === undefined) return null
+
+    const timeoutMs = options.timeoutMs
+
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+      throw VelociousError.safe(JOB_TIMEOUT_VALIDATION_MESSAGE)
     }
+
+    if (timeoutMs <= 0) return 0
+
+    if (!Number.isInteger(timeoutMs) || timeoutMs > MAX_JOB_TIMEOUT_MS) {
+      throw VelociousError.safe(JOB_TIMEOUT_VALIDATION_MESSAGE)
+    }
+
+    return timeoutMs
   }
 
   /**
@@ -1371,6 +1392,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         schedule_key: scheduleKey,
         concurrency_key: concurrency?.concurrencyKey || null,
         max_concurrency: concurrency?.maxConcurrency || null,
+        timeout_ms: preparedJob.timeoutMs,
         handoff_id: null
       }
     })
@@ -1382,11 +1404,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Normalized max retries.
    */
   _normalizeMaxRetries(maxRetries) {
-    if (typeof maxRetries === "number" && Number.isFinite(maxRetries) && maxRetries >= 0) {
-      return Math.floor(maxRetries)
-    }
-
-    return DEFAULT_MAX_RETRIES
+    return normalizeBackgroundJobMaxRetries(maxRetries)
   }
 
   /**
@@ -1396,10 +1414,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Dispatch timestamp.
    */
   _normalizeScheduledAtMs(scheduledAtMs, defaultScheduledAtMs) {
-    if (scheduledAtMs === undefined) return defaultScheduledAtMs
-    if (Number.isSafeInteger(scheduledAtMs) && scheduledAtMs >= 0) return scheduledAtMs
-
-    throw VelociousError.safe("background job scheduledAtMs must be a non-negative safe integer")
+    return normalizeBackgroundJobScheduledAtMs(scheduledAtMs, defaultScheduledAtMs)
   }
 
   /**
@@ -1408,14 +1423,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Future eligibility timestamp.
    */
   _rescheduledAtMs(delayMs) {
-    this._validateRescheduleDelayMs(delayMs)
-
-    const scheduledAtMs = Date.now() + delayMs
-    if (!Number.isSafeInteger(scheduledAtMs)) {
-      throw VelociousError.safe("background job reschedule scheduledAtMs must be a safe integer")
-    }
-
-    return scheduledAtMs
+    return rescheduledBackgroundJobAtMs(delayMs, Date.now())
   }
 
   /**
@@ -1424,9 +1432,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {void}
    */
   _validateRescheduleDelayMs(delayMs) {
-    if (!Number.isSafeInteger(delayMs) || delayMs < 0) {
-      throw VelociousError.safe("background job reschedule delayMs must be a non-negative safe integer")
-    }
+    rescheduledBackgroundJobAtMs(delayMs, 0)
   }
 
   /**
@@ -1612,6 +1618,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     table.text("last_error", {null: true})
     table.string("concurrency_key", {null: true, index: true})
     table.integer("max_concurrency", {null: true})
+    table.bigint("timeout_ms", {null: true})
 
     await db.createTable(table)
   }
@@ -1704,6 +1711,35 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
 
     await this._ensureQueueColumn(db)
     await this._ensureScheduleKeyColumn(db)
+    await this._ensureJobTimeoutColumn(db)
+  }
+
+  /**
+   * Idempotently adds the per-job wall-clock timeout to existing job tables.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when ensured.
+   */
+  async _ensureJobTimeoutColumn(db) {
+    const lockName = `${MIGRATION_SCOPE}:timeout_ms_column`
+    const acquired = await db.acquireAdvisoryLock(lockName)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs timeout schema lock")
+
+    try {
+      db.clearSchemaCache()
+      const table = await db.getTableByNameOrFail(JOBS_TABLE)
+
+      if (!(await table.getColumnByName("timeout_ms"))) {
+        const tableData = new TableData(JOBS_TABLE)
+        tableData.bigint("timeout_ms", {null: true})
+
+        for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+
+        db.clearSchemaCache()
+      }
+    } finally {
+      await db.releaseAdvisoryLock(lockName)
+    }
   }
 
   /**
@@ -2083,14 +2119,14 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     // `execution_mode` is the single source of truth for a job's runtime and is
     // written on every enqueue; the drop-forked migration backfills any pre-existing
     // rows before the legacy `forked` column is removed.
-    const executionMode = row.execution_mode ? this._normalizeExecutionModeName(String(row.execution_mode)) : DEFAULT_EXECUTION_MODE
+    const executionMode = row.execution_mode ? this._normalizeExecutionModeName(String(row.execution_mode)) : DEFAULT_BACKGROUND_JOB_EXECUTION_MODE
 
     return {
       id: String(row.id),
       jobName: String(row.job_name),
       args: this._parseArgs(row.args_json),
       executionMode,
-      queue: row.queue ? String(row.queue) : DEFAULT_QUEUE,
+      queue: row.queue ? String(row.queue) : DEFAULT_BACKGROUND_JOB_QUEUE,
       scheduleKey: row.schedule_key ? String(row.schedule_key) : null,
       status: row.status ? String(row.status) : "queued",
       attempts: this._normalizeNumber(row.attempts),
@@ -2105,26 +2141,9 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       workerId: row.worker_id ? String(row.worker_id) : null,
       lastError: row.last_error ? String(row.last_error) : null,
       concurrencyKey: row.concurrency_key ? String(row.concurrency_key) : null,
-      maxConcurrency: this._normalizeNumber(row.max_concurrency)
-    }
-  }
-
-  /**
-   * Validates concurrency options.
-   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
-   * @returns {{concurrencyKey: string, maxConcurrency: number} | null} - Normalized configuration.
-   */
-  _normalizeConcurrencyOptions(options) {
-    const key = options?.concurrencyKey
-    const cap = options?.maxConcurrency
-    if (key === undefined && cap === undefined) return null
-    if (typeof key !== "string" || key.length === 0 || !Number.isInteger(cap) || Number(cap) <= 0) {
-      throw new Error("background job concurrencyKey and maxConcurrency must be paired; concurrencyKey must be non-empty and maxConcurrency must be a positive integer")
+      maxConcurrency: this._normalizeNumber(row.max_concurrency),
+      timeoutMs: this._normalizeNumber(row.timeout_ms)
     }
-    if (key.startsWith(QUEUE_CONCURRENCY_KEY_PREFIX)) {
-      throw new Error(`background job concurrencyKey must not start with the reserved "${QUEUE_CONCURRENCY_KEY_PREFIX}" prefix, which is reserved for queue-derived concurrency caps`)
-    }
-    return {concurrencyKey: key, maxConcurrency: Number(cap)}
   }
 
   /**
@@ -2133,11 +2152,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {string} - Queue name.
    */
   _normalizeQueue(options) {
-    const queue = options?.queue
-
-    if (typeof queue === "string" && queue.trim().length > 0) return queue.trim()
-
-    return DEFAULT_QUEUE
+    return normalizeBackgroundJobQueue(options)
   }
 
   /**
@@ -2151,15 +2166,11 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {{concurrencyKey: string, maxConcurrency: number, queueDerived: boolean} | null} - Resolved concurrency.
    */
   _resolveConcurrency(options, queue) {
-    const explicit = this._normalizeConcurrencyOptions(options)
-
-    if (explicit) return {...explicit, queueDerived: false}
-
-    const cap = this._queueMaxConcurrency(queue)
-
-    if (cap === null) return null
-
-    return {concurrencyKey: `${QUEUE_CONCURRENCY_KEY_PREFIX}${queue}`, maxConcurrency: cap, queueDerived: true}
+    return normalizeBackgroundJobConcurrency({
+      options: options || {},
+      queue,
+      queues: this.configuration.getBackgroundJobsConfig().queues
+    })
   }
 
   /**
@@ -2667,21 +2678,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {import("./types.js").BackgroundJobExecutionMode} - Normalized execution mode.
    */
   _normalizeExecutionMode(options) {
-    const executionMode = options?.executionMode
-
-    if (executionMode) {
-      return this._normalizeExecutionModeName(executionMode)
-    }
-
-    // The `forked` option alias was removed. Reject it loudly instead of silently
-    // defaulting to pooled, which would turn an explicitly inline (`forked: false`)
-    // or one-shot forked (`forked: true`) job into a pooled child-runner job — a
-    // silent semantic change for any not-yet-migrated caller.
-    if (options && "forked" in options) {
-      throw new Error("The background job `forked` option was removed; pass `executionMode` (\"inline\", \"forked\", \"pooled\", or \"spawned\") instead")
-    }
-
-    return DEFAULT_EXECUTION_MODE
+    return normalizeBackgroundJobExecutionMode(options || {}, DEFAULT_BACKGROUND_JOB_EXECUTION_MODE)
   }
 
   /**
@@ -2690,11 +2687,11 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {import("./types.js").BackgroundJobExecutionMode} - Normalized execution mode.
    */
   _normalizeExecutionModeName(executionMode) {
-    for (const mode of EXECUTION_MODES) {
-      if (mode === executionMode) return mode
-    }
-
-    throw new Error(`Invalid background job executionMode: ${executionMode}`)
+    return normalizeBackgroundJobExecutionMode(
+      {executionMode: /** @type {import("./types.js").BackgroundJobExecutionMode} */ (executionMode)},
+      DEFAULT_BACKGROUND_JOB_EXECUTION_MODE,
+      BACKGROUND_JOB_EXECUTION_MODES
+    )
   }
 
   /**

package/build/background-jobs/types.js

@@ -3,6 +3,31 @@
 /**
  * @typedef {"inline" | "forked" | "pooled" | "spawned"} BackgroundJobExecutionMode
  */
+/**
+ * @typedef {object} LocalBackgroundJobsClock
+ * @property {() => number} now - Current epoch milliseconds.
+ * @property {(callback: () => void, delayMs: number) => ReturnType<typeof setTimeout> | number} setTimeout - Arms a timer.
+ * @property {(timerId: ReturnType<typeof setTimeout> | number) => void} clearTimeout - Clears a timer.
+ */
+/**
+ * @typedef {object} ResolvedBackgroundJobConcurrency
+ * @property {string} concurrencyKey - Durable cap identity.
+ * @property {number} maxConcurrency - Positive cap.
+ * @property {boolean} queueDerived - Whether queue configuration owns the cap.
+ */
+/**
+ * @typedef {object} PreparedLocalBackgroundJob
+ * @property {string} argsDigest - Fixed-width digest of the serialized arguments.
+ * @property {string} argsJson - Serialized arguments.
+ * @property {ResolvedBackgroundJobConcurrency | null} concurrency - Resolved concurrency.
+ * @property {number} createdAtMs - Creation timestamp.
+ * @property {"inline"} executionMode - Local in-process execution mode.
+ * @property {string} jobId - Durable id.
+ * @property {string} jobName - Registered name.
+ * @property {number} maxRetries - Retry cap.
+ * @property {string} queue - Queue name.
+ * @property {number} scheduledAtMs - Eligibility timestamp.
+ */
 /**
  * @typedef {object} BackgroundJobsHealth
  * @property {boolean} ready - Whether the adapter can accept and process work.
@@ -20,7 +45,7 @@
  */
 /**
  * @typedef {object} BackgroundJobOptions
- * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"pooled"` (a warm, reused local runner process). `"forked"` runs the job in a fresh `child_process.fork()` child, `"spawned"` in a detached CLI runner, and `"inline"` inside the worker process. Omit to use the default `"pooled"` mode.
+ * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Node defaults to `"pooled"` (a warm, reused local runner process). Browser/Expo local dispatch defaults to and only accepts `"inline"`. `"forked"` runs a Node job in a fresh `child_process.fork()` child, and `"spawned"` in a detached CLI runner.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
  * @property {string} [queue] - Queue name. Defaults to `"default"`. When the queue has a configured cap in `backgroundJobs.queues`, that cap is enforced cluster-wide.
  * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap. Overrides any queue-derived cap.
@@ -28,6 +53,7 @@
  * @property {boolean} [deduplicateWhileQueued] - When true, skip the enqueue if an identical still-queued job (same job name, args and queue) is scheduled no later than this enqueue, returning the earliest matching job's id. A future retry does not suppress earlier work. Deduplication is independent of `concurrencyKey`, so the job keeps its normal (e.g. queue-derived) concurrency cap. Keeps an interval-scheduled recurring job (e.g. retention pruning) from piling up redundant queued rows when it runs slower than its interval or no worker is free.
  * @property {string} [idempotencyKey] - Durable enqueue identity scoped to the resolved job class name and queue. Exact replay returns the original job id across every state and after job pruning; reuse with different canonical arguments or behavior-affecting options fails. Ownership is independent of `deduplicateWhileQueued` and is retained until an explicit future retention policy removes it.
  * @property {number} [scheduledAtMs] - Epoch timestamp in milliseconds when the job becomes eligible for dispatch. Defaults to enqueue time.
+ * @property {number} [timeoutMs] - Per-job wall-clock timeout for forked and pooled execution. A positive integer up to 2,147,483,647 overrides the worker-level `jobTimeoutMs`; a non-positive finite value disables the timeout for this job.
  */
 /**
  * @typedef {object} BackgroundJobPayload
@@ -61,6 +87,7 @@
  * @property {string | null} lastError - Last failure message.
  * @property {string | null} concurrencyKey - Durable concurrency key.
  * @property {number | null} maxConcurrency - Durable per-key cap.
+ * @property {number | null} timeoutMs - Per-job wall-clock timeout override, or null when omitted.
  */
 /**
  * @typedef {"queued" | "handed_off" | null} BackgroundJobReplacementPreviousStatus

package/build/background-jobs/worker.js

@@ -690,7 +690,7 @@ export default class BackgroundJobsWorker {
     state.lastDispatchSeq = ++this._pooledDispatchSeq
 
     return new Promise((resolve) => {
-      const timeoutTimer = this._armPooledJobTimeout({child, jobId: payload.id})
+      const timeoutTimer = this._armPooledJobTimeout({child, payload})
 
       state.inflight.set(payload.id, {payload, resolve, timeoutTimer})
       try {
@@ -753,15 +753,15 @@ export default class BackgroundJobsWorker {
    * the timer, or null when no timeout is configured.
    * @param {object} args - Options.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
-   * @param {string} args.jobId - Job id whose overrun is guarded.
+   * @param {import("./types.js").BackgroundJobPayload & {id: string}} args.payload - Job payload whose overrun is guarded.
    * @returns {ReturnType<typeof setTimeout> | null} - The armed timer, or null.
    */
-  _armPooledJobTimeout({child, jobId}) {
-    const timeoutMs = this._resolveJobTimeoutMs()
+  _armPooledJobTimeout({child, payload}) {
+    const timeoutMs = this._resolveJobTimeoutMs(payload.options)
 
     if (!(typeof timeoutMs === "number" && timeoutMs > 0)) return null
 
-    return setTimeout(() => this._onPooledJobTimeout({child, jobId}), timeoutMs)
+    return setTimeout(() => this._onPooledJobTimeout({child, jobId: payload.id}), timeoutMs)
   }
 
   /**
@@ -1016,7 +1016,7 @@ export default class BackgroundJobsWorker {
    * @returns {Promise<void>} - Resolves when the child exits.
    */
   _waitForForkedChild({child, payload}) {
-    const timeoutState = this._armForkedJobTimeout({child})
+    const timeoutState = this._armForkedJobTimeout({child, payload})
 
     return new Promise((resolve) => {
       child.once("exit", (code, signal) => {
@@ -1040,10 +1040,11 @@ export default class BackgroundJobsWorker {
    * and behavior is unchanged.
    * @param {object} args - Options.
    * @param {import("node:child_process").ChildProcess} args.child - Forked child process.
+   * @param {import("./types.js").BackgroundJobPayload & {id: string}} args.payload - Job payload.
    * @returns {ForkedJobTimeoutState} - Timeout state.
    */
-  _armForkedJobTimeout({child}) {
-    const timeoutMs = this._resolveJobTimeoutMs()
+  _armForkedJobTimeout({child, payload}) {
+    const timeoutMs = this._resolveJobTimeoutMs(payload.options)
     /** @type {ForkedJobTimeoutState} */
     const state = {timedOut: false, timeoutMs, timer: null, sigkillTimer: null}
 
@@ -1056,14 +1057,18 @@ export default class BackgroundJobsWorker {
 
   /**
    * Resolves the effective wall-clock job timeout in ms (shared by forked and pooled jobs), or null when disabled. The
-   * constructor override wins; otherwise the value comes from the background-jobs
-   * configuration. A non-positive value disables the backstop.
+   * per-job override wins, followed by the constructor override, then the value
+   * from the background-jobs configuration. A non-positive value disables the
+   * backstop at whichever level supplied it.
+   * @param {import("./types.js").BackgroundJobOptions} [jobOptions] - Per-job options.
    * @returns {number | null} - Timeout in ms, or null when disabled.
    */
-  _resolveJobTimeoutMs() {
-    const raw = typeof this.jobTimeoutMsOverride === "number"
-      ? this.jobTimeoutMsOverride
-      : (this.configuration ? this.configuration.getBackgroundJobsConfig().jobTimeoutMs : null)
+  _resolveJobTimeoutMs(jobOptions) {
+    const raw = typeof jobOptions?.timeoutMs === "number"
+      ? jobOptions.timeoutMs
+      : (typeof this.jobTimeoutMsOverride === "number"
+          ? this.jobTimeoutMsOverride
+          : (this.configuration ? this.configuration.getBackgroundJobsConfig().jobTimeoutMs : null))
 
     // A non-finite (e.g. Infinity) or non-positive value disables the backstop;
     // a finite value beyond Node's timer range is clamped to the max rather than

package/build/configuration-types.js

@@ -158,14 +158,16 @@
 
 /** @typedef {"background" | "inline"} BackgroundJobsMode */
 /** @typedef {(args: {configuration: import("./configuration.js").default}) => import("./background-jobs/adapter.js").default} BackgroundJobsAdapterFactory */
+/** @typedef {typeof import("./background-jobs/platform-job.js").default} BackgroundJobClass */
 
 /**
  * @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 {BackgroundJobClass[]} [jobClasses] - Static portable job classes available to Browser/Expo local dispatch. Defaults to `[]`; Node keeps its filesystem registry.
  * @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.
+ * @property {string} [databaseIdentifier] - Database identifier used to store background jobs. Browser/Expo local dispatch uses this existing SQLite database and defaults to `"default"`.
  * @property {number} [maxConcurrentInlineJobs] - How many `forked: false` jobs a single
  *   `background-jobs-worker` process is allowed to run in parallel. Concurrency
  *   is at the JS event-loop level: every concurrent job shares the worker's

package/build/configuration.js

@@ -1543,7 +1543,22 @@ export default class VelociousConfiguration {
         : 60 * 60 * 1000
     }
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+    const jobClasses = this.getBackgroundJobClasses()
+
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobClasses, jobTimeoutMs, retention}
+  }
+
+  /**
+   * Returns statically registered portable background jobs.
+   * @returns {import("./configuration-types.js").BackgroundJobClass[]} - Configured job classes.
+   */
+  getBackgroundJobClasses() {
+    const jobClasses = this._backgroundJobs?.jobClasses
+
+    if (jobClasses === undefined) return []
+    if (!Array.isArray(jobClasses)) throw new TypeError("backgroundJobs.jobClasses must be an array")
+
+    return [...jobClasses]
   }
 
   /**

package/build/database/drivers/sqlite/index.js

@@ -255,6 +255,35 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     await fs.writeFile(ownerPath, payload)
   }
 
+  /**
+   * Publishes a fully initialized lock directory with one atomic rename.
+   * A losing candidate is removed in the same call, so concurrent acquisition
+   * cannot observe or delete another process's half-written owner metadata.
+   * @param {string} lockPath - Stable advisory-lock path.
+   * @returns {Promise<boolean>} - Whether this candidate became the lock owner.
+   */
+  async _publishAdvisoryLockDirectory(lockPath) {
+    const candidatePath = await fs.mkdtemp(`${lockPath}.pending-`)
+    let published = false
+
+    try {
+      await this._writeAdvisoryLockMetadata(candidatePath)
+
+      try {
+        await fs.rename(candidatePath, lockPath)
+        published = true
+        return true
+      } catch (error) {
+        const code = /** @type {Error & {code?: string}} */ (error)?.code
+
+        if (code === "EEXIST" || code === "ENOTEMPTY") return false
+        throw error
+      }
+    } finally {
+      if (!published) await fs.rm(candidatePath, {force: true, recursive: true})
+    }
+  }
+
   /**
    * Runs acquire advisory lock file.
    * @param {string} name - Lock name.
@@ -272,28 +301,21 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     // mkdir succeeds, the deadline elapses, or an unexpected error is
     // re-thrown.
     while (true) {
-      try {
-        await fs.mkdir(lockPath)
-        await this._writeAdvisoryLockMetadata(lockPath)
+      if (await this._publishAdvisoryLockDirectory(lockPath)) return true
 
-        return true
-      } catch (error) {
-        if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
-
-        if (await this._isAdvisoryLockStale(lockPath)) {
-          await fs.rm(lockPath, {recursive: true, force: true})
-          continue
-        }
+      if (await this._isAdvisoryLockStale(lockPath)) {
+        await fs.rm(lockPath, {recursive: true, force: true})
+        continue
+      }
 
-        if (deadline !== null) {
-          const remaining = deadline - Date.now()
+      if (deadline !== null) {
+        const remaining = deadline - Date.now()
 
-          if (remaining <= 0) return false
+        if (remaining <= 0) return false
 
-          await wait(Math.min(pollIntervalMs, remaining))
-        } else {
-          await wait(pollIntervalMs)
-        }
+        await wait(Math.min(pollIntervalMs, remaining))
+      } else {
+        await wait(pollIntervalMs)
       }
     }
   }
@@ -308,31 +330,14 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
     const lockPath = this._advisoryLockPath(name)
 
-    try {
-      await fs.mkdir(lockPath)
-      await this._writeAdvisoryLockMetadata(lockPath)
+    if (await this._publishAdvisoryLockDirectory(lockPath)) return true
 
-      return true
-    } catch (error) {
-      if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
-
-      if (await this._isAdvisoryLockStale(lockPath)) {
-        await fs.rm(lockPath, {recursive: true, force: true})
-
-        try {
-          await fs.mkdir(lockPath)
-          await this._writeAdvisoryLockMetadata(lockPath)
-
-          return true
-        } catch (retryError) {
-          if (/** @type {Error & {code?: string}} */ (retryError)?.code === "EEXIST") return false
-
-          throw retryError
-        }
-      }
-
-      return false
+    if (await this._isAdvisoryLockStale(lockPath)) {
+      await fs.rm(lockPath, {recursive: true, force: true})
+      return await this._publishAdvisoryLockDirectory(lockPath)
     }
+
+    return false
   }
 
   /**

package/build/environment-handlers/browser.js

@@ -2,6 +2,7 @@ import Base from "./base.js"
 import * as inflection from "inflection"
 import restArgsError from "../utils/rest-args-error.js"
 import Logger from "../logger.js"
+import LocalBackgroundJobsAdapter from "../background-jobs/local-adapter.js"
 
 /**
  * Defines this typedef.
@@ -40,6 +41,15 @@ function isMigrationObject(migration) {
 }
 
 export default class VelociousEnvironmentsHandlerBrowser extends Base {
+  /**
+   * Creates the Browser/Expo local SQLite adapter and in-process dispatcher.
+   * @param {{configuration: import("../configuration.js").default}} args - Adapter options.
+   * @returns {LocalBackgroundJobsAdapter} - Local background-jobs adapter.
+   */
+  createBackgroundJobsAdapter({configuration}) {
+    return new LocalBackgroundJobsAdapter({configuration})
+  }
+
   /**
    * Find commands require context result.
    * @type {CommandsRequireContextType | undefined} */