velocious 1.0.530 → 1.0.533

package/README.md

@@ -2007,13 +2007,13 @@ VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS=5400000
 
 `VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS` (default: `indefinite`) bounds how long a `background-jobs-worker` waits for in-flight jobs on `SIGTERM`/`SIGINT` before terminating any forked or spawned child runners still running, so they are not orphaned across a deploy. The default waits for jobs to finish and never interrupts a running job; set a positive number of milliseconds for a finite cap (keep it shorter than your process supervisor's graceful-stop window so the worker reaps its own runners first). See [docs/background-jobs.md](docs/background-jobs.md#worker-shutdown-and-process-job-draining).
 
-`maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores. The older `forked: false` option still maps to inline mode.
+`maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores; select it with `executionMode: "forked"`.
 
-New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). Pooled rows remain readable by older mains during rolling upgrades and run there with legacy one-shot fork behavior. `forked: true` remains an explicit alias for `"forked"`; `forked: false` remains inline. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
+New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
 
 `maxConcurrentForkedJobs` (default: `4`) caps how many out-of-process `executionMode: "forked"` or `executionMode: "spawned"` jobs one worker may keep in flight. Forked jobs use `child_process.fork()` with an attached IPC channel. After the main process acknowledges their durable status report, forked and spawned one-shot runners exit without waiting for graceful Beacon/database teardown; the OS closes their process-owned resources. A missing or rejected status acknowledgement makes the runner exit as failed instead of reporting clean success. Spawned jobs use the legacy `background-jobs-runner` CLI process via `child_process.spawn()` and are only for callers that intentionally want that spawned behavior.
 
-`jobTimeoutMs` (or `VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS`, milliseconds; default: disabled) is a wall-clock backstop for a single `"forked"` runner. A forked job still running after the timeout is terminated (`SIGTERM`, then `SIGKILL` after the reaping grace) and reported `failed`, so a genuinely-hung runner can't pin a worker — and its whole-app boot and DB connections — indefinitely (notably a retired-release worker draining after a deploy). It's a coarse safety net, not per-job tuning: it applies to every forked runner, so set it well above the longest legitimate forked job. Omit it, or set `null`/`<= 0`, to disable. `"inline"` jobs are not covered — they share the worker's process and can't be killed without killing the worker. See [docs/background-jobs.md](docs/background-jobs.md#forked-job-timeout-hung-runner-backstop).
+`jobTimeoutMs` (or `VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS`, milliseconds; default: disabled) is a wall-clock backstop for `"forked"` and `"pooled"` jobs. A job still running after the timeout is terminated (`SIGTERM`, then `SIGKILL` after the reaping grace) and reported `failed`, so a genuinely-hung job can't pin a worker's capacity — and its whole-app boot and DB connections — indefinitely (notably a retired-release worker draining after a deploy). For a **pooled** job the whole child running it is killed, so its concurrent in-flight siblings on that child are also reported `failed` and requeued — a hung JS job can't be cancelled any other way — before a replacement child is spawned. It's a coarse safety net, not per-job tuning: it applies to every forked and pooled job, so set it well above the longest legitimate job. Omit it, or set `null`/`<= 0`, to disable. `"inline"` jobs are not covered — they share the worker's process and can't be killed without killing the worker. See [docs/background-jobs.md](docs/background-jobs.md#job-timeout-hung-runner-backstop).
 
 ### Dispatch strategy
 
@@ -2075,7 +2075,7 @@ await MyJob.performLaterWithOptions({
 
 Until `scheduledAtMs` is reached, the job remains queued but is not eligible for dispatch. The event-driven dispatcher arms its timer for the earliest future job and wakes at that timestamp. Omitting `scheduledAtMs` keeps the immediate-enqueue behavior.
 
-The older `options: {forked: false}` form is still accepted as an alias for inline execution, and `options: {forked: true}` maps to forked execution. To use the previous spawned CLI runner behavior explicitly, pass `options: {executionMode: "spawned"}`.
+Select a non-default runtime explicitly with `options: {executionMode: "inline" | "forked" | "spawned"}`.
 
 Inline jobs share the worker process and run concurrently up to `maxConcurrentInlineJobs`, so a single slow inline job no longer blocks the queue. A single worker can also override the configured cap explicitly:
 
@@ -2327,4 +2327,6 @@ npx velocious db:tenants:migrate projectTenant --parallel 20
 
 At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a tenant context, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. `Tenant.with` and `Tenant.each` run their callbacks inside `ensureConnections`, so switching into a tenant establishes its database connections (global + tenant) and passes them to the callback — the tenant is immediately queryable without the caller wiring up connections (already-open connections are reused, so nesting does not double-connect). `Tenant.with` is generic over its callback's return type, so a value returned from inside the tenant context comes back to the caller with its type preserved (no cast needed). `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
 
+`SchemaCloner` adds a missing auto-increment column and its separate source unique index in one schema alteration, including on MySQL/MariaDB where an auto-increment column must be keyed when it is created.
+
 See [docs/tenant-databases.md](docs/tenant-databases.md) for the full configuration and migration pattern.

package/build/background-jobs/main.js

@@ -1142,8 +1142,7 @@ export default class BackgroundJobsMain {
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
-              executionMode: job.executionMode,
-              forked: job.forked
+              executionMode: job.executionMode
             }
           }
         })

package/build/background-jobs/store.js

@@ -11,6 +11,16 @@ const MIGRATIONS_TABLE = "velocious_internal_migrations"
 const MIGRATION_SCOPE = "background_jobs"
 const MIGRATION_VERSION = "20250215000000"
 const EXECUTION_MODE_BACKFILL_MIGRATION_VERSION = "20260607131010"
+// Drops the redundant legacy `forked` boolean column and rewrites pooled rows to
+// persist `execution_mode = "pooled"` directly (retiring the pooled-as-forked
+// handoff-marker workaround), leaving `execution_mode` as the single source of
+// truth for a job's runtime.
+const DROP_FORKED_COLUMN_MIGRATION_VERSION = "20260719000000"
+// Legacy marker prefix used by rows written before this migration: pooled jobs
+// used to persist as `execution_mode = "forked"` plus a `velocious-pooled:*`
+// handoff id. Retained only to detect and convert those rows in the migration.
+const LEGACY_POOLED_HANDOFF_ID_PREFIX = "velocious-pooled:"
+const LEGACY_POOLED_QUEUED_HANDOFF_ID = `${LEGACY_POOLED_HANDOFF_ID_PREFIX}queued`
 const JOBS_TABLE = "background_jobs"
 const CONCURRENCY_TABLE = "background_job_concurrency"
 const DEFAULT_MAX_RETRIES = 10
@@ -25,18 +35,6 @@ const EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
  * process — the same isolation as forked without paying a fresh process per job.
  * @type {import("./types.js").BackgroundJobExecutionMode} */
 const DEFAULT_EXECUTION_MODE = "pooled"
-/**
- * Execution mode a legacy `forked = true` row (persisted before the
- * `execution_mode` column existed) backfills to. It must stay `"forked"` so an
- * upgrade never silently reinterprets already-persisted forked jobs as pooled —
- * distinct from {@link DEFAULT_EXECUTION_MODE}, which only governs new enqueues.
- * @type {import("./types.js").BackgroundJobExecutionMode} */
-const LEGACY_FORKED_EXECUTION_MODE = "forked"
-// Pooled jobs persist with the legacy-safe `forked` mode so a pre-pool main can
-// deserialize and run them during a rolling upgrade. Old versions ignore the
-// nullable handoff id on queued rows, making it a backward-compatible marker.
-const POOLED_HANDOFF_ID_PREFIX = "velocious-pooled:"
-const POOLED_QUEUED_HANDOFF_ID = `${POOLED_HANDOFF_ID_PREFIX}queued`
 const DEFAULT_QUEUE = "default"
 // Queue-derived durable concurrency keys are namespaced so they can't collide
 // with explicit caller-supplied concurrencyKeys.
@@ -154,8 +152,7 @@ export default class BackgroundJobsStore {
           id: jobId,
           job_name: jobName,
           args_json: argsJson,
-          forked: executionMode !== "inline",
-          execution_mode: executionMode === "pooled" ? LEGACY_FORKED_EXECUTION_MODE : executionMode,
+          execution_mode: executionMode,
           queue,
           max_retries: maxRetries,
           attempts: 0,
@@ -164,7 +161,7 @@ export default class BackgroundJobsStore {
           created_at_ms: now,
           concurrency_key: concurrency?.concurrencyKey || null,
           max_concurrency: concurrency?.maxConcurrency || null,
-          handoff_id: executionMode === "pooled" ? POOLED_QUEUED_HANDOFF_ID : null
+          handoff_id: null
         }
       })
     })
@@ -175,7 +172,6 @@ export default class BackgroundJobsStore {
   /**
    * Runs next available job.
    * @param {object} [args] - Options.
-   * @param {boolean} [args.forked] - Compatibility filter for non-inline vs inline jobs.
    * @param {import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]} [args.executionMode] - Execution mode or modes to match.
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next job.
    */
@@ -186,7 +182,6 @@ export default class BackgroundJobsStore {
       return await this._nextQueuedJob({
         db,
         scheduledAtOperator: "<=",
-        forked: args.forked,
         executionMode: args.executionMode
       })
     })
@@ -213,11 +208,10 @@ export default class BackgroundJobsStore {
    * @param {object} args - Options.
    * @param {import("../database/drivers/base.js").default} args.db - Database connection.
    * @param {"<=" | ">"} args.scheduledAtOperator - Scheduled timestamp operator.
-   * @param {boolean} [args.forked] - Compatibility filter for non-inline vs inline jobs.
    * @param {import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]} [args.executionMode] - Execution mode or modes to match.
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next matching queued job.
    */
-  async _nextQueuedJob({db, scheduledAtOperator, forked, executionMode}) {
+  async _nextQueuedJob({db, scheduledAtOperator, executionMode}) {
     const now = Date.now()
     let query = db
       .newQuery()
@@ -236,9 +230,6 @@ export default class BackgroundJobsStore {
       )
     }
 
-    if (typeof forked === "boolean") {
-      query = query.where({forked})
-    }
     if (executionMode) query = this._whereExecutionMode({db, executionMode, query})
 
     if (scheduledAtOperator === "<=") {
@@ -420,9 +411,7 @@ export default class BackgroundJobsStore {
       const queuedJob = await this._getJobRowById(db, jobId)
       if (!queuedJob || queuedJob.status !== "queued") return null
       if (queuedJob.concurrencyKey && !(await this._reserveConcurrency(db, queuedJob.concurrencyKey))) return null
-      const handoffId = queuedJob.executionMode === "pooled"
-        ? `${POOLED_HANDOFF_ID_PREFIX}${randomUUID()}`
-        : randomUUID()
+      const handoffId = randomUUID()
 
       const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
@@ -496,7 +485,7 @@ export default class BackgroundJobsStore {
           status: "queued",
           scheduled_at_ms: Date.now(),
           handed_off_at_ms: null,
-          handoff_id: job.executionMode === "pooled" ? POOLED_QUEUED_HANDOFF_ID : null,
+          handoff_id: null,
           worker_id: null
         },
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"}
@@ -842,7 +831,6 @@ export default class BackgroundJobsStore {
     table.string("id", {primaryKey: true})
     table.string("job_name", {null: false, index: true})
     table.text("args_json", {null: false})
-    table.boolean("forked", {null: false})
     table.string("execution_mode", {null: false})
     table.string("queue", {null: true, index: true})
     table.integer("max_retries", {null: false})
@@ -916,6 +904,7 @@ export default class BackgroundJobsStore {
     }
 
     await this._backfillExecutionModesOnce(db)
+    await this._dropForkedColumnOnce(db)
 
     const lockName = `${MIGRATION_SCOPE}:concurrency_columns`
     const acquired = await db.acquireAdvisoryLock(lockName)
@@ -1001,12 +990,20 @@ export default class BackgroundJobsStore {
     try {
       if (await this._hasMigration(db, migrationVersion)) return
 
+      // A table created after the `forked` column was dropped has nothing to
+      // backfill from; record the migration so it is not re-attempted.
+      db.clearSchemaCache()
+      if (!(await (await db.getTableByNameOrFail(JOBS_TABLE)).getColumnByName("forked"))) {
+        await this._recordMigration(db, migrationVersion)
+        return
+      }
+
       const tableNameSql = db.quoteTable(JOBS_TABLE)
       const forkedColumnSql = db.quoteColumn("forked")
       const executionModeColumnSql = db.quoteColumn("execution_mode")
 
       await db.query(
-        `UPDATE ${tableNameSql} SET ${executionModeColumnSql} = ${db.quote(LEGACY_FORKED_EXECUTION_MODE)} ` +
+        `UPDATE ${tableNameSql} SET ${executionModeColumnSql} = ${db.quote("forked")} ` +
         `WHERE ${forkedColumnSql} = ${db.quote(true)} AND ${executionModeColumnSql} IS NULL`
       )
       await db.query(
@@ -1020,6 +1017,60 @@ export default class BackgroundJobsStore {
     }
   }
 
+  /**
+   * Rewrites pre-existing pooled rows (persisted as `execution_mode = "forked"`
+   * plus a `velocious-pooled:*` handoff marker) to `execution_mode = "pooled"`,
+   * clears the queued marker, then drops the now-redundant `forked` column so
+   * `execution_mode` is the single source of truth. Runs once, guarded by the
+   * migration ledger and a per-key advisory lock; a fresh table (created without
+   * the column) short-circuits.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async _dropForkedColumnOnce(db) {
+    const migrationVersion = DROP_FORKED_COLUMN_MIGRATION_VERSION
+    const migrationKey = this._migrationKey(migrationVersion)
+
+    if (await this._hasMigration(db, migrationVersion)) return
+
+    await db.acquireAdvisoryLock(migrationKey)
+
+    try {
+      if (await this._hasMigration(db, migrationVersion)) return
+
+      db.clearSchemaCache()
+
+      if (await (await db.getTableByNameOrFail(JOBS_TABLE)).getColumnByName("forked")) {
+        const tableNameSql = db.quoteTable(JOBS_TABLE)
+        const executionModeColumnSql = db.quoteColumn("execution_mode")
+        const handoffIdColumnSql = db.quoteColumn("handoff_id")
+
+        // Pooled rows used to persist as execution_mode "forked" + a pooled handoff
+        // marker; recover their real mode before the marker is cleared.
+        await db.query(
+          `UPDATE ${tableNameSql} SET ${executionModeColumnSql} = ${db.quote("pooled")} ` +
+          `WHERE ${executionModeColumnSql} = ${db.quote("forked")} ` +
+          `AND ${handoffIdColumnSql} LIKE ${db.quote(`${LEGACY_POOLED_HANDOFF_ID_PREFIX}%`)}`
+        )
+        // The queued-pooled marker was a sentinel, not a real lease; clear it.
+        await db.query(
+          `UPDATE ${tableNameSql} SET ${handoffIdColumnSql} = NULL ` +
+          `WHERE ${handoffIdColumnSql} = ${db.quote(LEGACY_POOLED_QUEUED_HANDOFF_ID)}`
+        )
+
+        const dropForked = new TableData(JOBS_TABLE)
+        dropForked.addColumn("forked", {dropColumn: true})
+        for (const sql of await db.alterTableSQLs(dropForked)) await db.query(sql)
+
+        db.clearSchemaCache()
+      }
+
+      await this._recordMigration(db, migrationVersion)
+    } finally {
+      await db.releaseAdvisoryLock(migrationKey)
+    }
+  }
+
   /**
    * Runs record migration.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
@@ -1097,7 +1148,6 @@ export default class BackgroundJobsStore {
       scheduledAt,
       shouldRetry
     })
-    if (shouldRetry && job.executionMode === "pooled") update.handoff_id = POOLED_QUEUED_HANDOFF_ID
 
     const affectedRows = await this._updateAffectedRows(db, {
       tableName: JOBS_TABLE,
@@ -1206,18 +1256,17 @@ export default class BackgroundJobsStore {
    * @returns {import("./types.js").BackgroundJobRow} - Normalized job row.
    */
   _normalizeJobRow(row) {
-    const persistedExecutionMode = row.execution_mode ? String(row.execution_mode) : null
     const handoffId = row.handoff_id ? String(row.handoff_id) : null
-    const executionMode = persistedExecutionMode
-      ? this._normalizePersistedExecutionMode({executionMode: persistedExecutionMode, handoffId})
-      : this._normalizeExecutionMode({forked: this._normalizeBoolean(row.forked)})
+    // `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
 
     return {
       id: String(row.id),
       jobName: String(row.job_name),
       args: this._parseArgs(row.args_json),
       executionMode,
-      forked: executionMode !== "inline",
       queue: row.queue ? String(row.queue) : DEFAULT_QUEUE,
       status: row.status ? String(row.status) : "queued",
       attempts: this._normalizeNumber(row.attempts),
@@ -1501,19 +1550,6 @@ export default class BackgroundJobsStore {
     return numeric
   }
 
-  /**
-   * Runs normalize boolean.
-   * @param {?} value - Input value.
-   * @returns {boolean} - Normalized boolean.
-   */
-  _normalizeBoolean(value) {
-    if (value === null || value === undefined) return false
-    if (typeof value === "boolean") return value
-    if (typeof value === "number") return value !== 0
-
-    return value === "true"
-  }
-
   /**
    * Runs normalize execution mode.
    * @param {import("./types.js").BackgroundJobOptions} [options] - Job options.
@@ -1525,11 +1561,14 @@ export default class BackgroundJobsStore {
     if (executionMode) {
       return this._normalizeExecutionModeName(executionMode)
     }
-    // The legacy `forked` flag stays authoritative when supplied: `false` is
-    // inline and `true` is forked (never the pooled default). Only an enqueue
-    // that names neither option falls through to the pooled default.
-    if (options?.forked === false) return "inline"
-    if (options?.forked === true) return LEGACY_FORKED_EXECUTION_MODE
+
+    // 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
   }
@@ -1548,20 +1587,8 @@ export default class BackgroundJobsStore {
   }
 
   /**
-   * Normalizes a legacy-safe persisted execution mode.
-   * @param {object} args - Options.
-   * @param {string} args.executionMode - Persisted legacy execution mode.
-   * @param {string | null} args.handoffId - Persisted handoff id or pooled marker.
-   * @returns {import("./types.js").BackgroundJobExecutionMode} - Runtime execution mode.
-   */
-  _normalizePersistedExecutionMode({executionMode, handoffId}) {
-    if (executionMode === LEGACY_FORKED_EXECUTION_MODE && handoffId?.startsWith(POOLED_HANDOFF_ID_PREFIX)) return "pooled"
-
-    return this._normalizeExecutionModeName(executionMode)
-  }
-
-  /**
-   * Filters persisted legacy-safe execution modes.
+   * Filters queued jobs by one or more execution modes against the
+   * `execution_mode` column (the single source of truth).
    * @param {object} args - Options.
    * @param {import("../database/drivers/base.js").default} args.db - Database connection.
    * @param {import("./types.js").BackgroundJobExecutionMode | import("./types.js").BackgroundJobExecutionMode[]} args.executionMode - Runtime modes.
@@ -1570,20 +1597,8 @@ export default class BackgroundJobsStore {
    */
   _whereExecutionMode({db, executionMode, query}) {
     const executionModes = Array.isArray(executionMode) ? executionMode : [executionMode]
-    /** @type {string[]} */
-    const conditions = []
     const executionModeColumn = db.quoteColumn("execution_mode")
-    const handoffIdColumn = db.quoteColumn("handoff_id")
-
-    for (const mode of executionModes) {
-      if (mode === "pooled") {
-        conditions.push(`(${executionModeColumn} = ${db.quote(LEGACY_FORKED_EXECUTION_MODE)} AND ${handoffIdColumn} = ${db.quote(POOLED_QUEUED_HANDOFF_ID)})`)
-      } else if (mode === LEGACY_FORKED_EXECUTION_MODE) {
-        conditions.push(`(${executionModeColumn} = ${db.quote(mode)} AND (${handoffIdColumn} IS NULL OR ${handoffIdColumn} <> ${db.quote(POOLED_QUEUED_HANDOFF_ID)}))`)
-      } else {
-        conditions.push(`${executionModeColumn} = ${db.quote(mode)}`)
-      }
-    }
+    const conditions = executionModes.map((mode) => `${executionModeColumn} = ${db.quote(mode)}`)
 
     return query.where(`(${conditions.join(" OR ")})`)
   }

package/build/background-jobs/types.js

@@ -10,8 +10,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.
- * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`. Omitting both `forked` and `executionMode` uses the default `"pooled"` mode.
+ * @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 {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.
@@ -35,7 +34,6 @@
  * @property {string} jobName - Job class name.
  * @property {Array<?>} args - Serialized job arguments.
  * @property {BackgroundJobExecutionMode} executionMode - How the job should run.
- * @property {boolean} forked - Compatibility flag; true for non-inline execution.
  * @property {string} queue - Queue name (defaults to `"default"`).
  * @property {string} status - Current job status.
  * @property {number | null} attempts - Failure attempts count.

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

@@ -196,7 +196,6 @@ export default class VelociousBackgroundJobsWebController extends Controller {
       createdAtMs: job.createdAtMs,
       executionMode: job.executionMode,
       failedAtMs: job.failedAtMs,
-      forked: job.forked,
       handedOffAtMs: job.handedOffAtMs,
       id: job.id,
       jobName: job.jobName,

package/build/background-jobs/worker.js

@@ -72,7 +72,7 @@ export default class BackgroundJobsWorker {
    * @param {number} [args.pooledRunnerMaxLifetimeMs] - Override the per-runner recycle lifetime.
    * @param {number} [args.forkedChildSigkillGraceMs] - Override the grace period between SIGTERM and SIGKILL when reaping lingering process runners on stop.
    * @param {number} [args.heartbeatIntervalMs] - Override the liveness heartbeat interval (default 15000ms).
-   * @param {number} [args.jobTimeoutMs] - Override the forked-job wall-clock timeout from `configuration.getBackgroundJobsConfig()`. `0` disables it.
+   * @param {number} [args.jobTimeoutMs] - Override the wall-clock timeout for forked and pooled jobs from `configuration.getBackgroundJobsConfig()`. `0` disables it.
    */
   constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, forkedChildSigkillGraceMs, heartbeatIntervalMs, jobTimeoutMs} = {}) {
     /**
@@ -129,7 +129,7 @@ export default class BackgroundJobsWorker {
       ? forkedChildSigkillGraceMs
       : FORKED_CHILD_SIGKILL_GRACE_MS
     /**
-     * Constructor override for the forked-job wall-clock timeout. When unset the
+     * Constructor override for the forked and pooled wall-clock job timeout. When unset the
      * timeout is read from `configuration.getBackgroundJobsConfig().jobTimeoutMs`
      * at fork time (default: disabled).
      * @type {number | undefined}
@@ -186,7 +186,7 @@ export default class BackgroundJobsWorker {
     this.inflightPooledJobs = new Set()
     /** @type {Set<import("node:child_process").ChildProcess>} */
     this.pooledChildren = new Set()
-    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void}>, retiring: boolean, settling?: boolean}>} */
+    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, retiring: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
     this.pooledChildStates = new Map()
   }
 
@@ -480,14 +480,9 @@ export default class BackgroundJobsWorker {
    * @returns {import("./types.js").BackgroundJobExecutionMode} - Execution mode.
    */
   _executionModeForPayload(payload) {
-    const options = payload.options || {}
-    const executionMode = options.executionMode
+    const executionMode = payload.options?.executionMode
 
-    if (executionMode) return this._normalizeExecutionMode(executionMode)
-
-    if (options.forked === false) return "inline"
-    if (options.forked === true) return "forked"
-    return "pooled"
+    return executionMode ? this._normalizeExecutionMode(executionMode) : "pooled"
   }
 
   /**
@@ -659,7 +654,9 @@ export default class BackgroundJobsWorker {
     if (!state) throw new Error("Pooled runner state missing")
 
     return new Promise((resolve) => {
-      state.inflight.set(payload.id, {payload, resolve})
+      const timeoutTimer = this._armPooledJobTimeout({child, jobId: payload.id})
+
+      state.inflight.set(payload.id, {payload, resolve, timeoutTimer})
       try {
         child.send({type: "job", payload})
       } catch (error) {
@@ -668,6 +665,58 @@ export default class BackgroundJobsWorker {
     })
   }
 
+  /**
+   * Arms a per-job wall-clock backstop for a pooled job. A pooled child hosts many
+   * concurrent jobs, so a single genuinely-hung job would otherwise pin its
+   * runner's concurrency slot forever — the lifetime recycle only retires a child
+   * once its in-flight set drains, which a hung job never does. On overrun the
+   * whole child is terminated so the hung job (and its siblings) requeue. Returns
+   * 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.
+   * @returns {ReturnType<typeof setTimeout> | null} - The armed timer, or null.
+   */
+  _armPooledJobTimeout({child, jobId}) {
+    const timeoutMs = this._resolveJobTimeoutMs()
+
+    if (!(typeof timeoutMs === "number" && timeoutMs > 0)) return null
+
+    return setTimeout(() => this._onPooledJobTimeout({child, jobId}), timeoutMs)
+  }
+
+  /**
+   * Fired when a pooled job overruns its timeout. Terminates the child running it
+   * (SIGTERM, then SIGKILL after the grace) — a hung JS job cannot be cancelled
+   * any other way. The non-clean exit flows through `_handlePooledChildFailure`,
+   * which reports every in-flight job on the child failed (so they requeue) and
+   * drops it from tracking; capacity is refilled on the next dispatch.
+   * @param {object} args - Options.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {string} args.jobId - Job id that overran.
+   * @returns {void}
+   */
+  _onPooledJobTimeout({child, jobId}) {
+    const state = this.pooledChildStates.get(child)
+
+    // Already settling/gone, or the job finished in the race with this timer.
+    if (!state || state.settling || !state.inflight.has(jobId)) return
+
+    try {
+      child.kill("SIGTERM")
+    } catch {
+      // Child already exited; nothing to do.
+    }
+
+    state.timeoutSigkillTimer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL")
+      } catch {
+        // Child already exited; nothing to do.
+      }
+    }, this.forkedChildSigkillGraceMs)
+  }
+
   /**
    * Creates a reusable pooled child.
    * @returns {import("node:child_process").ChildProcess} - New pooled child.
@@ -705,6 +754,7 @@ export default class BackgroundJobsWorker {
     const entry = state.inflight.get(record.jobId)
     if (!entry) return
 
+    if (entry.timeoutTimer) clearTimeout(entry.timeoutTimer)
     state.inflight.delete(record.jobId)
     state.jobsRun += 1
     const resolve = entry.resolve
@@ -789,7 +839,15 @@ export default class BackgroundJobsWorker {
   async _handlePooledChildFailure({child, error}) {
     const state = this.pooledChildStates.get(child)
     if (state?.settling) return
-    if (state) state.settling = true
+    if (state) {
+      state.settling = true
+      // Cancel this child's pending timers before its in-flight set is reported —
+      // the SIGKILL grace from a timeout kill, and every armed per-job backstop.
+      if (state.timeoutSigkillTimer) clearTimeout(state.timeoutSigkillTimer)
+      for (const inflightEntry of state.inflight.values()) {
+        if (inflightEntry.timeoutTimer) clearTimeout(inflightEntry.timeoutTimer)
+      }
+    }
     this.pooledChildren.delete(child)
     this.inflightProcessChildren.delete(child)
 
@@ -908,7 +966,7 @@ export default class BackgroundJobsWorker {
    * @returns {ForkedJobTimeoutState} - Timeout state.
    */
   _armForkedJobTimeout({child}) {
-    const timeoutMs = this._resolveForkedJobTimeoutMs()
+    const timeoutMs = this._resolveJobTimeoutMs()
     /** @type {ForkedJobTimeoutState} */
     const state = {timedOut: false, timeoutMs, timer: null, sigkillTimer: null}
 
@@ -920,12 +978,12 @@ export default class BackgroundJobsWorker {
   }
 
   /**
-   * Resolves the effective forked-job timeout in ms, or null when disabled. The
+   * 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.
    * @returns {number | null} - Timeout in ms, or null when disabled.
    */
-  _resolveForkedJobTimeoutMs() {
+  _resolveJobTimeoutMs() {
     const raw = typeof this.jobTimeoutMsOverride === "number"
       ? this.jobTimeoutMsOverride
       : (this.configuration ? this.configuration.getBackgroundJobsConfig().jobTimeoutMs : null)

package/build/database/drivers/mysql/sql/alter-table.js

@@ -1,6 +1,48 @@
 // @ts-check
 
 import AlterTableBase from "../../../query/alter-table-base.js"
+import TableColumn from "../../../table-data/table-column.js"
 
 export default class VelociousDatabaseConnectionDriversMysqlSqlAlterTable extends AlterTableBase {
+  /**
+   * Builds MySQL ALTER TABLE statements, adding indexes atomically with columns.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async toSQLs() {
+    const sqls = await super.toSQLs()
+    const indexes = this.tableData.getIndexes()
+
+    if (indexes.length === 0) return sqls
+    if (sqls.length !== 1) throw new Error("Expected one MySQL ALTER TABLE statement when adding indexes")
+
+    const options = this.getOptions()
+    let sql = sqls[0]
+
+    for (const index of indexes) {
+      sql += ", ADD"
+
+      if (index.getUnique()) sql += " UNIQUE"
+
+      sql += " INDEX"
+
+      const indexName = index.getName()
+
+      if (typeof indexName === "string") {
+        sql += ` ${options.quoteIndexName(indexName)}`
+      }
+
+      sql += " ("
+      sql += index
+        .getColumns()
+        .map((column) => {
+          const columnName = column instanceof TableColumn ? column.getName() : column
+
+          return options.quoteColumnName(columnName)
+        })
+        .join(", ")
+      sql += ")"
+    }
+
+    return [sql]
+  }
 }