velocious 1.0.516 → 1.0.518

package/README.md

@@ -1930,6 +1930,8 @@ Create the file `src/routes/testing/another-action.ejs` and so something like th
 
 Velocious includes a simple background jobs system inspired by Sidekiq.
 
+Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
+
 Production apps can listen for `background-job-failed` or its `all-error` mirror to report accepted failed attempts, including retry and terminal state metadata. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
 
 ## Setup

package/build/background-jobs/job.js

@@ -13,6 +13,15 @@ import BackgroundJobsClient from "./client.js"
  * @template {Array<?>} [TArgs=[]]
  */
 export default class VelociousJob {
+  /**
+   * 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
+
   /**
    * Runs job name.
    * @returns {string} - Job name.
@@ -21,6 +30,22 @@ export default class VelociousJob {
     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 {...?} args - Job args.
@@ -33,7 +58,7 @@ export default class VelociousJob {
     return await client.enqueue({
       jobName: this.jobName(),
       args: jobArgs,
-      options: jobOptions
+      options: this._withQueue(jobOptions)
     })
   }
 
@@ -50,7 +75,7 @@ export default class VelociousJob {
     return await client.enqueue({
       jobName: this.jobName(),
       args,
-      options
+      options: this._withQueue(options)
     })
   }
 

package/build/background-jobs/store.js

@@ -11,6 +11,7 @@ const MIGRATION_SCOPE = "background_jobs"
 const MIGRATION_VERSION = "20250215000000"
 const EXECUTION_MODE_BACKFILL_MIGRATION_VERSION = "20260607131010"
 const JOBS_TABLE = "background_jobs"
+const CONCURRENCY_TABLE = "background_job_concurrency"
 const DEFAULT_MAX_RETRIES = 10
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
 /**
@@ -18,6 +19,10 @@ const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
  * @type {import("./types.js").BackgroundJobExecutionMode[]} */
 const EXECUTION_MODES = ["inline", "forked", "spawned"]
 const DEFAULT_EXECUTION_MODE = "forked"
+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
@@ -94,8 +99,17 @@ export default class BackgroundJobsStore {
     const executionMode = this._normalizeExecutionMode(options)
     const maxRetries = this._normalizeMaxRetries(options?.maxRetries)
     const argsJson = JSON.stringify(args || [])
+    const queue = this._normalizeQueue(options)
+    const concurrency = this._resolveConcurrency(options, queue)
 
     await this._withDb(async (db) => {
+      if (concurrency) {
+        if (concurrency.queueDerived) {
+          await this._ensureQueueConcurrencyKey(db, concurrency)
+        } else {
+          await this._ensureConcurrencyKey(db, concurrency)
+        }
+      }
       await db.insert({
         tableName: JOBS_TABLE,
         data: {
@@ -104,11 +118,14 @@ export default class BackgroundJobsStore {
           args_json: argsJson,
           forked: executionMode !== "inline",
           execution_mode: executionMode,
+          queue,
           max_retries: maxRetries,
           attempts: 0,
           status: "queued",
           scheduled_at_ms: now,
-          created_at_ms: now
+          created_at_ms: now,
+          concurrency_key: concurrency?.concurrencyKey || null,
+          max_concurrency: concurrency?.maxConcurrency || null
         }
       })
     })
@@ -169,6 +186,17 @@ export default class BackgroundJobsStore {
       .where({status: "queued"})
       .where(`scheduled_at_ms ${scheduledAtOperator} ${db.quote(now)}`)
 
+    if (scheduledAtOperator === "<=") {
+      const jobsTable = db.quoteTable(JOBS_TABLE)
+      const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
+      query = query.where(
+        `(${jobsTable}.${db.quoteColumn("concurrency_key")} IS NULL OR EXISTS (` +
+        `SELECT 1 FROM ${concurrencyTable} WHERE ` +
+        `${concurrencyTable}.${db.quoteColumn("concurrency_key")} = ${jobsTable}.${db.quoteColumn("concurrency_key")} AND ` +
+        `${concurrencyTable}.${db.quoteColumn("active_count")} < ${concurrencyTable}.${db.quoteColumn("max_concurrency")}))`
+      )
+    }
+
     if (typeof forked === "boolean") {
       query = query.where({forked})
     }
@@ -314,8 +342,12 @@ export default class BackgroundJobsStore {
     const handedOffAtMs = Date.now()
     const handoffId = randomUUID()
 
-    return await this._withDb(async (db) => {
-      await db.update({
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
+      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 affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "handed_off",
@@ -326,12 +358,13 @@ export default class BackgroundJobsStore {
         conditions: {id: jobId, status: "queued"}
       })
 
-      const job = await this._getJobRowById(db, jobId)
-
-      if (job?.status !== "handed_off" || job.handoffId !== handoffId) return null
+      if (affectedRows !== 1) {
+        await this._releaseConcurrency(db, queuedJob.concurrencyKey)
+        return null
+      }
 
       return {handedOffAtMs, handoffId}
-    })
+    }))
   }
 
   /**
@@ -346,13 +379,13 @@ export default class BackgroundJobsStore {
   async markCompleted({jobId, handoffId, workerId, handedOffAtMs}) {
     await this.ensureReady()
 
-    return await this._withDb(async (db) => await this._withHandoffLock({db, jobId}, async () => {
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
       const job = await this._getJobRowById(db, jobId)
 
       if (!job) return false
       if (!this._shouldAcceptReport({job, handoffId, workerId, handedOffAtMs})) return false
 
-      await db.update({
+      const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "completed",
@@ -361,9 +394,9 @@ export default class BackgroundJobsStore {
         conditions: this._activeHandoffConditions(job)
       })
 
-      const updatedJob = await this._getJobRowById(db, jobId)
-
-      return updatedJob?.status === "completed" && updatedJob.handoffId === job.handoffId
+      if (affectedRows !== 1) return false
+      await this._releaseConcurrency(db, job.concurrencyKey)
+      return true
     }))
   }
 
@@ -377,8 +410,10 @@ export default class BackgroundJobsStore {
   async markReturnedToQueue({jobId, handoffId}) {
     await this.ensureReady()
 
-    await this._withDb(async (db) => {
-      await db.update({
+    await this._withDb(async (db) => await db.transaction(async () => {
+      const job = await this._getJobRowById(db, jobId)
+      if (!job || job.handoffId !== handoffId || job.status !== "handed_off") return
+      const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "queued",
@@ -389,7 +424,8 @@ export default class BackgroundJobsStore {
         },
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"}
       })
-    })
+      if (affectedRows === 1) await this._releaseConcurrency(db, job.concurrencyKey)
+    }))
   }
 
   /**
@@ -405,13 +441,14 @@ export default class BackgroundJobsStore {
   async markFailed({jobId, error, handoffId, workerId, handedOffAtMs}) {
     await this.ensureReady()
 
-    return await this._withDb(async (db) => await this._withHandoffLock({db, jobId}, async () => {
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
       const job = await this._getJobRowById(db, jobId)
 
       if (!job) return null
       if (!this._shouldAcceptReport({job, handoffId, workerId, handedOffAtMs})) return null
 
-      return await this._applyFailure({db, job, error, markOrphaned: false})
+      const updatedJob = await this._applyFailure({db, job, error, markOrphaned: false})
+      return updatedJob
     }))
   }
 
@@ -462,9 +499,27 @@ export default class BackgroundJobsStore {
 
     await this._withDb(async (db) => {
       await db.query(`DELETE FROM ${db.quoteTable(JOBS_TABLE)}`)
+      if (await db.tableExists(CONCURRENCY_TABLE)) await db.query(`DELETE FROM ${db.quoteTable(CONCURRENCY_TABLE)}`)
     })
   }
 
+  /**
+   * Cancels a queued or handed-off job and releases any durable concurrency reservation.
+   * @param {string} jobId - Job id.
+   * @returns {Promise<boolean>} - Whether the job was cancelled.
+   */
+  async cancel(jobId) {
+    await this.ensureReady()
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
+      const job = await this._getJobRowById(db, jobId)
+      if (!job || (job.status !== "queued" && job.status !== "handed_off")) return false
+      const affectedRows = await this._updateAffectedRows(db, {tableName: JOBS_TABLE, data: {status: "cancelled"}, conditions: {id: job.id, status: job.status}})
+      if (affectedRows !== 1) return false
+      if (job.status === "handed_off") await this._releaseConcurrency(db, job.concurrencyKey)
+      return true
+    }))
+  }
+
   /**
    * Runs get retry delay ms.
    * @param {number} retryCount - Retry attempt count (1-based).
@@ -506,11 +561,15 @@ export default class BackgroundJobsStore {
       // row alone, otherwise later callers fail with "no such table".
       if (alreadyApplied && await db.tableExists(JOBS_TABLE)) {
         await this._ensureJobsTableColumns(db)
+        await this._ensureConcurrencyTable(db)
+        await this._reconcileConcurrency(db)
         return
       }
 
       await this._applyMigrations(db)
       await this._ensureJobsTableColumns(db)
+      await this._ensureConcurrencyTable(db)
+      await this._reconcileConcurrency(db)
 
       if (alreadyApplied) return
 
@@ -574,6 +633,7 @@ export default class BackgroundJobsStore {
     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})
     table.integer("attempts", {null: false})
     table.string("status", {null: false, index: true})
@@ -586,6 +646,8 @@ export default class BackgroundJobsStore {
     table.bigint("orphaned_at_ms", {null: true, index: true})
     table.string("worker_id", {null: true})
     table.text("last_error", {null: true})
+    table.string("concurrency_key", {null: true, index: true})
+    table.integer("max_concurrency", {null: true})
 
     await db.createTable(table)
   }
@@ -643,6 +705,74 @@ export default class BackgroundJobsStore {
     }
 
     await this._backfillExecutionModesOnce(db)
+
+    const lockName = `${MIGRATION_SCOPE}:concurrency_columns`
+    const acquired = await db.acquireAdvisoryLock(lockName)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs concurrency schema lock")
+
+    try {
+      // SQL Server schema reads can deadlock with a concurrent ALTER TABLE, so
+      // acquire the lock before inspecting either column rather than only
+      // protecting the mutation.
+      db.clearSchemaCache()
+      const lockedTable = await db.getTableByNameOrFail(JOBS_TABLE)
+      const concurrencyColumnNames = ["concurrency_key", "max_concurrency"]
+
+      for (const concurrencyColumnName of concurrencyColumnNames) {
+        if (await lockedTable.getColumnByName(concurrencyColumnName)) continue
+
+        const tableData = new TableData(JOBS_TABLE)
+        if (concurrencyColumnName == "concurrency_key") {
+          tableData.string("concurrency_key", {null: true, index: true})
+        } else {
+          tableData.integer("max_concurrency", {null: true})
+        }
+
+        for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+      }
+
+      db.clearSchemaCache()
+    } finally {
+      await db.releaseAdvisoryLock(lockName)
+    }
+
+    await this._ensureQueueColumn(db)
+  }
+
+  /**
+   * Idempotently adds the `queue` column to an existing jobs table. Existing
+   * rows read back as the default queue (see {@link _normalizeJobRow}), so no
+   * data backfill is required.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when ensured.
+   */
+  async _ensureQueueColumn(db) {
+    const table = await db.getTableByNameOrFail(JOBS_TABLE)
+
+    if (await table.getColumnByName("queue")) return
+
+    const lockName = `${MIGRATION_SCOPE}:queue_column`
+    const acquired = await db.acquireAdvisoryLock(lockName)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs queue schema lock")
+
+    try {
+      db.clearSchemaCache()
+      const lockedTable = await db.getTableByNameOrFail(JOBS_TABLE)
+
+      if (!(await lockedTable.getColumnByName("queue"))) {
+        const tableData = new TableData(JOBS_TABLE)
+
+        tableData.string("queue", {null: true, index: true})
+
+        for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+
+        db.clearSchemaCache()
+      }
+    } finally {
+      await db.releaseAdvisoryLock(lockName)
+    }
   }
 
   /**
@@ -757,19 +887,18 @@ export default class BackgroundJobsStore {
       shouldRetry
     })
 
-    await db.update({
+    const affectedRows = await this._updateAffectedRows(db, {
       tableName: JOBS_TABLE,
       data: update,
       conditions: this._activeHandoffConditions(job)
     })
 
+    if (affectedRows !== 1) return null
+    await this._releaseConcurrency(db, job.concurrencyKey)
+
     const updatedJob = await this._getJobRowById(db, job.id)
 
     if (!updatedJob) return null
-    if (updatedJob.handoffId !== job.handoffId) return null
-    if (updatedJob.attempts !== nextAttempt) return null
-    if (updatedJob.status !== update.status) return null
-
     return updatedJob
   }
 
@@ -855,6 +984,7 @@ export default class BackgroundJobsStore {
       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),
       maxRetries: this._normalizeNumber(row.max_retries),
@@ -866,8 +996,198 @@ export default class BackgroundJobsStore {
       failedAtMs: this._normalizeNumber(row.failed_at_ms),
       orphanedAtMs: this._normalizeNumber(row.orphaned_at_ms),
       workerId: row.worker_id ? String(row.worker_id) : null,
-      lastError: row.last_error ? String(row.last_error) : 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")
+    }
+    return {concurrencyKey: key, maxConcurrency: Number(cap)}
+  }
+
+  /**
+   * Normalizes a job's queue name, defaulting to "default".
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {string} - Queue name.
+   */
+  _normalizeQueue(options) {
+    const queue = options?.queue
+
+    if (typeof queue === "string" && queue.trim().length > 0) return queue.trim()
+
+    return DEFAULT_QUEUE
+  }
+
+  /**
+   * Resolves a job's durable concurrency. An explicit concurrencyKey/maxConcurrency
+   * pair always wins. Otherwise, when the job's queue has a configured cap
+   * (`backgroundJobs.queues[queue].maxConcurrent`), derive a queue-scoped
+   * concurrency key so the queue cap is enforced cluster-wide through the
+   * existing durable concurrency mechanism.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @param {string} queue - Normalized queue name.
+   * @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}
+  }
+
+  /**
+   * Reads the configured max concurrency for a queue from the background-jobs config.
+   * @param {string} queue - Queue name.
+   * @returns {number | null} - Positive integer cap, or null when the queue has no configured cap.
+   */
+  _queueMaxConcurrency(queue) {
+    const queues = this.configuration.getBackgroundJobsConfig().queues
+    const cap = queues?.[queue]?.maxConcurrent
+
+    if (Number.isInteger(cap) && Number(cap) > 0) return Number(cap)
+
+    return null
+  }
+
+  /**
+   * Like {@link _ensureConcurrencyKey}, but for queue-derived keys the configured
+   * queue cap is the source of truth: if it changed, update the stored cap
+   * instead of throwing on conflict (config-driven caps must be tunable).
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {{concurrencyKey: string, maxConcurrency: number}} concurrency - Concurrency configuration.
+   * @returns {Promise<void>} - Resolves when ensured.
+   */
+  async _ensureQueueConcurrencyKey(db, {concurrencyKey, maxConcurrency}) {
+    const rows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+
+    if (!rows[0]) {
+      try {
+        await db.insert({tableName: CONCURRENCY_TABLE, data: {active_count: 0, concurrency_key: concurrencyKey, max_concurrency: maxConcurrency}})
+
+        return
+      } catch (error) {
+        const racedRows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+
+        if (!racedRows[0]) throw error
+
+        rows[0] = racedRows[0]
+      }
     }
+
+    const configured = /** @type {{max_concurrency?: number | string}} */ (rows[0])
+
+    if (this._normalizeNumber(configured.max_concurrency) !== maxConcurrency) {
+      const table = db.quoteTable(CONCURRENCY_TABLE)
+
+      await db.query(`UPDATE ${table} SET ${db.quoteColumn("max_concurrency")} = ${Number(maxConcurrency)} WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)}`)
+    }
+  }
+
+  /**
+   * Ensures the concurrency state table exists.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when ready.
+   */
+  async _ensureConcurrencyTable(db) {
+    if (await db.tableExists(CONCURRENCY_TABLE)) return
+    const table = new TableData(CONCURRENCY_TABLE, {ifNotExists: true})
+    table.string("concurrency_key", {primaryKey: true})
+    table.integer("max_concurrency", {null: false})
+    table.integer("active_count", {null: false})
+    await db.createTable(table)
+  }
+
+  /**
+   * Registers or verifies a stable key configuration.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {object} concurrency - Concurrency configuration.
+   * @param {string} concurrency.concurrencyKey - Concurrency key.
+   * @param {number} concurrency.maxConcurrency - Stable cap.
+   * @returns {Promise<void>} - Resolves when verified.
+   */
+  async _ensureConcurrencyKey(db, {concurrencyKey, maxConcurrency}) {
+    const rows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+    if (!rows[0]) {
+      try {
+        await db.insert({tableName: CONCURRENCY_TABLE, data: {active_count: 0, concurrency_key: concurrencyKey, max_concurrency: maxConcurrency}})
+        return
+      } catch (error) {
+        const racedRows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+        if (!racedRows[0]) throw error
+        rows[0] = racedRows[0]
+      }
+    }
+    const configured = /** @type {{max_concurrency?: number | string}} */ (rows[0])
+    if (this._normalizeNumber(configured.max_concurrency) !== maxConcurrency) throw new Error(`Conflicting maxConcurrency for background job concurrencyKey: ${concurrencyKey}`)
+  }
+
+  /**
+   * Atomically reserves capacity for a key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} concurrencyKey - Concurrency key.
+   * @returns {Promise<boolean>} - Whether capacity was reserved.
+   */
+  async _reserveConcurrency(db, concurrencyKey) {
+    const table = db.quoteTable(CONCURRENCY_TABLE)
+    const count = db.quoteColumn("active_count")
+    const affectedRows = await db.affectedRows(`UPDATE ${table} SET ${count} = ${count} + 1 WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)} AND ${count} < ${db.quoteColumn("max_concurrency")}`)
+    return affectedRows === 1
+  }
+
+  /**
+   * Runs a portable update and returns its affected-row count.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {import("../database/drivers/base.js").UpdateSqlArgsType} args - Update options.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _updateAffectedRows(db, args) {
+    return await db.affectedRows(db.updateSql(args))
+  }
+
+  /**
+   * Releases capacity for a key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string | null} concurrencyKey - Concurrency key.
+   * @returns {Promise<void>} - Resolves when released.
+   */
+  async _releaseConcurrency(db, concurrencyKey) {
+    if (!concurrencyKey) return
+    const table = db.quoteTable(CONCURRENCY_TABLE)
+    const count = db.quoteColumn("active_count")
+    await db.query(`UPDATE ${table} SET ${count} = ${count} - 1 WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)} AND ${count} > 0`)
+  }
+
+  /**
+   * Rebuilds durable counts from active handoffs after startup.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when reconciled.
+   */
+  async _reconcileConcurrency(db) {
+    if (!(await db.tableExists(CONCURRENCY_TABLE))) return
+    const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
+    const jobsTable = db.quoteTable(JOBS_TABLE)
+    await db.query(
+      `UPDATE ${concurrencyTable} SET ${db.quoteColumn("active_count")} = (` +
+      `SELECT COUNT(*) FROM ${jobsTable} WHERE ${jobsTable}.${db.quoteColumn("status")} = ${db.quote("handed_off")} AND ` +
+      `${jobsTable}.${db.quoteColumn("concurrency_key")} = ${concurrencyTable}.${db.quoteColumn("concurrency_key")})`
+    )
   }
 
   /**
@@ -973,25 +1293,22 @@ export default class BackgroundJobsStore {
   }
 
   /**
-   * Serializes reports for one job so duplicate reports cannot both appear accepted.
+   * Runs a value-returning callback inside the driver's void-typed transaction API.
    * @template T
-   * @param {object} args - Options.
-   * @param {import("../database/drivers/base.js").default} args.db - Database connection.
-   * @param {string} args.jobId - Job id.
-   * @param {() => Promise<T>} callback - Locked callback.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {() => Promise<T>} callback - Transaction callback.
    * @returns {Promise<T>} - Callback result.
    */
-  async _withHandoffLock({db, jobId}, callback) {
-    const lockName = `background-job:${jobId}`
-    const acquired = await db.acquireAdvisoryLock(lockName)
-
-    if (!acquired) throw new Error(`Failed to acquire background job handoff lock: ${jobId}`)
-
-    try {
-      return await callback()
-    } finally {
-      await db.releaseAdvisoryLock(lockName)
-    }
+  async _transactionResult(db, callback) {
+    let completed = false
+    /** @type {T | undefined} */
+    let result
+    await db.transaction(async () => {
+      result = await callback()
+      completed = true
+    })
+    if (!completed) throw new Error("Background jobs transaction callback was not invoked")
+    return /** @type {T} */ (result)
   }
 
   /**

package/build/background-jobs/types.js

@@ -13,6 +13,9 @@
  * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"forked"`.
  * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`.
  * @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.
+ * @property {number} [maxConcurrency] - Positive integer cap; must be paired with `concurrencyKey`.
  */
 /**
  * @typedef {object} BackgroundJobPayload
@@ -31,6 +34,7 @@
  * @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.
  * @property {number | null} maxRetries - Max retry attempts.
@@ -43,6 +47,8 @@
  * @property {number | null} orphanedAtMs - Orphaned time in ms.
  * @property {string | null} workerId - Worker id handling the job.
  * @property {string | null} lastError - Last failure message.
+ * @property {string | null} concurrencyKey - Durable concurrency key.
+ * @property {number | null} maxConcurrency - Durable per-key cap.
  */
 /**
  * @typedef {object} BackgroundJobFailureEvent