velocious 1.0.644 → 1.0.645

package/src/authorization/ability.js

@@ -189,9 +189,10 @@ export default class VelociousAuthorizationAbility {
    * @param {string} args.action - Requested action.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional factory for the queries that evaluate individual conditional rules.
    * @returns {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} - Authorized query.
    */
-  applyToQuery({action, modelClass, query}) {
+  applyToQuery({action, modelClass, query, ruleQueryFactory}) {
     this.loadAbilitiesForModelClass(modelClass)
 
     const applicableRules = this.rulesFor({action, modelClass})
@@ -203,18 +204,18 @@ export default class VelociousAuthorizationAbility {
     }
 
     if (allowRules.some((rule) => !rule.conditions)) {
-      this.applyDenyRules({action, denyRules, modelClass, query})
+      this.applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory})
       return query
     }
 
-    const allowSqlParts = this.conditionSqlParts({action, modelClass, query, rules: allowRules})
+    const allowSqlParts = this.conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules: allowRules})
 
     if (allowSqlParts.length === 0) {
       return query.where("1=0")
     }
 
     query.where(`(${allowSqlParts.join(" OR ")})`)
-    this.applyDenyRules({action, denyRules, modelClass, query})
+    this.applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory})
 
     return query
   }
@@ -240,19 +241,20 @@ export default class VelociousAuthorizationAbility {
    * @param {string} args.action - Action.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Base query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional conditional-rule query factory.
    * @param {AbilityRuleType[]} args.rules - Rules.
    * @returns {string[]} - SQL condition parts.
    */
-  conditionSqlParts({action, modelClass, query, rules}) {
-    const pk = modelClass.primaryKey()
-    const quotedBaseTable = query.driver.quoteTable(modelClass.tableName())
-    const quotedPk = query.driver.quoteColumn(pk)
+  conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules}) {
+    const primaryKey = modelClass.primaryKey()
+    const primaryKeyAttributes = Array.isArray(primaryKey) ? primaryKey : [primaryKey]
+    const quotedBaseTable = query.driver.quoteTable(query.getTableReferenceForJoin())
     const sqlParts = []
 
     for (const rule of rules) {
       if (!rule.conditions) continue
 
-      const scopedQuery = modelClass._newQuery()
+      const scopedQuery = ruleQueryFactory ? ruleQueryFactory() : modelClass._newQuery()
       const resultQuery = this.applyRuleCondition({
         action,
         conditions: rule.conditions,
@@ -260,7 +262,16 @@ export default class VelociousAuthorizationAbility {
         query: scopedQuery
       })
       const finalQuery = resultQuery || scopedQuery
-      const selectedPkSql = `${quotedBaseTable}.${quotedPk}`
+
+      if (ruleQueryFactory && finalQuery !== scopedQuery) {
+        const finalFroms = finalQuery.getFroms()
+
+        finalFroms.splice(0, finalFroms.length, ...scopedQuery.getFroms())
+      }
+
+      const quotedScopedTable = query.driver.quoteTable(finalQuery.getTableReferenceForJoin())
+      const primaryKeyColumns = primaryKeyAttributes.map((attributeName) => modelClass.getColumnNameForAttributeName(attributeName))
+      const selectedPkSql = primaryKeyColumns.map((columnName) => `${quotedScopedTable}.${query.driver.quoteColumn(columnName)}`)
 
       if (finalQuery._distinct) {
         query.distinct(true)
@@ -268,7 +279,18 @@ export default class VelociousAuthorizationAbility {
 
       finalQuery.select(selectedPkSql)
 
-      sqlParts.push(`${quotedBaseTable}.${quotedPk} IN (${finalQuery.toSql()})`)
+      if (Array.isArray(primaryKey)) {
+        const authorizedRowsAlias = query.driver.quoteTable("velocious_authorized_rows")
+        const identitySql = primaryKeyColumns.map((columnName) => {
+          const quotedColumn = query.driver.quoteColumn(columnName)
+
+          return `${authorizedRowsAlias}.${quotedColumn} = ${quotedBaseTable}.${quotedColumn}`
+        }).join(" AND ")
+
+        sqlParts.push(`EXISTS (SELECT 1 FROM (${finalQuery.toSql()}) AS ${authorizedRowsAlias} WHERE ${identitySql})`)
+      } else {
+        sqlParts.push(`${quotedBaseTable}.${query.driver.quoteColumn(primaryKeyColumns[0])} IN (${finalQuery.toSql()})`)
+      }
     }
 
     return sqlParts
@@ -281,9 +303,10 @@ export default class VelociousAuthorizationAbility {
    * @param {AbilityRuleType[]} args.denyRules - Deny rules.
    * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
    * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @param {() => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} [args.ruleQueryFactory] - Optional conditional-rule query factory.
    * @returns {void} - No return value.
    */
-  applyDenyRules({action, denyRules, modelClass, query}) {
+  applyDenyRules({action, denyRules, modelClass, query, ruleQueryFactory}) {
     if (denyRules.length === 0) return
 
     if (denyRules.some((rule) => !rule.conditions)) {
@@ -291,7 +314,7 @@ export default class VelociousAuthorizationAbility {
       return
     }
 
-    const denySqlParts = this.conditionSqlParts({action, modelClass, query, rules: denyRules})
+    const denySqlParts = this.conditionSqlParts({action, modelClass, query, ruleQueryFactory, rules: denyRules})
 
     if (denySqlParts.length > 0) {
       query.where(`NOT (${denySqlParts.join(" OR ")})`)

package/src/background-jobs/adapter.js

@@ -48,6 +48,15 @@ export default class BackgroundJobsAdapter {
    */
   async reconcileQueueConcurrency() { throw new Error("BackgroundJobsAdapter#reconcileQueueConcurrency is not implemented") }
 
+  /**
+   * Repairs drift in adapter-owned durable active concurrency counts. Adapters
+   * without duplicate active-count persistence can keep this no-op result.
+   * @returns {Promise<import("./types.js").BackgroundJobConcurrencyReconciliation>} - Repair summary.
+   */
+  async reconcileActiveConcurrency() {
+    return {candidateCount: 0, checkedCount: 0, repairedCount: 0, repairs: [], repairsTruncatedCount: 0}
+  }
+
   /**
    * Enqueues a job.
    * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Job request.

package/src/background-jobs/main.js

@@ -2063,23 +2063,25 @@ export default class BackgroundJobsMain {
       handoffs.set(job.id, handoff.handoffId)
 
       try {
+        const dispatchedJob = handoff.job || job
+
         worker.send({
           type: "job",
           payload: {
-            id: job.id,
-            jobName: job.jobName,
-            args: job.args,
+            id: dispatchedJob.id,
+            jobName: dispatchedJob.jobName,
+            args: dispatchedJob.args,
             handoffId: handoff.handoffId,
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
-              concurrencyKey: job.concurrencyKey || undefined,
-              executionMode: job.executionMode,
-              maxConcurrency: job.maxConcurrency ?? undefined,
-              maxRetries: job.maxRetries ?? undefined,
-              queue: job.queue,
-              scheduledAtMs: job.scheduledAtMs ?? undefined,
-              ...(job.timeoutMs === null ? {} : {timeoutMs: job.timeoutMs})
+              concurrencyKey: dispatchedJob.concurrencyKey || undefined,
+              executionMode: dispatchedJob.executionMode,
+              maxConcurrency: dispatchedJob.maxConcurrency ?? undefined,
+              maxRetries: dispatchedJob.maxRetries ?? undefined,
+              queue: dispatchedJob.queue,
+              scheduledAtMs: dispatchedJob.scheduledAtMs ?? undefined,
+              ...(dispatchedJob.timeoutMs === null ? {} : {timeoutMs: dispatchedJob.timeoutMs})
             }
           }
         })
@@ -2354,6 +2356,29 @@ export default class BackgroundJobsMain {
       errorEvents.emit("framework-error", payload)
       errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
     }
+
+    if (this.lifecycleState === "active") await this._reconcileActiveConcurrency()
+  }
+
+  /**
+   * Repairs durable admission counters on the active main's maintenance cadence
+   * and immediately retries dispatch when capacity was recovered.
+   * @returns {Promise<void>} - Resolves after repair and any resulting drain.
+   */
+  async _reconcileActiveConcurrency() {
+    try {
+      const result = await this.store.reconcileActiveConcurrency()
+
+      if (result.repairedCount > 0) await this._drain()
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      const payload = {context: {generationId: this.generationId, stage: "background-job-concurrency-reconciliation"}, error: normalizedError}
+      const errorEvents = this.configuration.getErrorEvents()
+
+      this.logger.error(() => ["Failed to reconcile background job active-concurrency counts:", normalizedError])
+      errorEvents.emit("framework-error", payload)
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    }
   }
 
   /**

package/src/background-jobs/store.js

@@ -56,6 +56,20 @@ import {
  * @property {{failureMessage: string, name: string}} [advisoryLock] - Session lock held around the transaction.
  */
 
+/**
+ * BackgroundJobConcurrencyCountRow type.
+ * @typedef {object} BackgroundJobConcurrencyCountRow
+ * @property {number | string} active_count - Persisted or aggregated active count.
+ * @property {string} concurrency_key - Durable cap identity.
+ */
+
+/**
+ * BackgroundJobQueuedConcurrency type.
+ * @typedef {object} BackgroundJobQueuedConcurrency
+ * @property {string | null} concurrencyKey - Current concurrency key for queued work.
+ * @property {number | null} maxConcurrency - Current concurrency cap for queued work.
+ */
+
 const MIGRATIONS_TABLE = "velocious_internal_migrations"
 const MIGRATION_SCOPE = "background_jobs"
 const MIGRATION_VERSION = "20250215000000"
@@ -89,6 +103,8 @@ const SCHEDULE_KEYS_TABLE = "background_job_schedule_keys"
 const CONCURRENCY_TABLE = "background_job_concurrency"
 const COUNTS_REVISION_TABLE = "background_job_count_revisions"
 const COUNTS_REVISION_KEY = "counts"
+const CONCURRENCY_RECONCILIATION_LOCK = "background-jobs:queue-concurrency-reconcile"
+const CONCURRENCY_REPAIR_SAMPLE_LIMIT = 10
 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)
@@ -222,8 +238,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     await this.ensureReady()
 
     await this._withDb(async (db) => {
-      const lockName = "background-jobs:queue-concurrency-reconcile"
-      const acquired = await db.acquireAdvisoryLock(lockName)
+      const acquired = await db.acquireAdvisoryLock(CONCURRENCY_RECONCILIATION_LOCK)
 
       if (!acquired) throw new Error("Failed to acquire background job queue-concurrency reconcile lock")
 
@@ -236,7 +251,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         // the counts (adoption itself is idempotent).
         this._queueConcurrencyReconciled = true
       } finally {
-        await db.releaseAdvisoryLock(lockName)
+        await db.releaseAdvisoryLock(CONCURRENCY_RECONCILIATION_LOCK)
       }
     })
 
@@ -246,6 +261,44 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     ])
   }
 
+  /**
+   * Repairs durable active-count drift while a main process remains live. The
+   * initial snapshot is read-only; only suspected mismatches take their
+   * counter lock and re-count inside the serialized transaction path.
+   * @returns {Promise<import("./types.js").BackgroundJobConcurrencyReconciliation>} - Repair summary.
+   */
+  async reconcileActiveConcurrency() {
+    const databaseIdentifier = this.getDatabaseIdentifier()
+    const startedAtMs = Date.now()
+
+    await this.ensureReady()
+
+    const result = await this._serializedConnectionMutation(
+      async (db) => await this._reconcileConcurrency(db),
+      {
+        advisoryLock: {
+          failureMessage: "Failed to acquire background job active-concurrency reconcile lock",
+          name: CONCURRENCY_RECONCILIATION_LOCK
+        }
+      }
+    )
+
+    if (result.repairedCount > 0) {
+      await this.logger.warn(() => [
+        "Repaired background jobs active-concurrency count drift",
+        {
+          databaseIdentifier,
+          durationMs: Date.now() - startedAtMs,
+          repairedCount: result.repairedCount,
+          repairs: result.repairs,
+          repairsTruncatedCount: result.repairsTruncatedCount
+        }
+      ])
+    }
+
+    return result
+  }
+
   /**
    * Runs enqueue.
    * @param {object} args - Options.
@@ -949,8 +1002,11 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     const handedOffAtMs = Date.now()
 
     return await this._serializedCountMutation(async (db) => {
-      const queuedJob = await this._getJobRowById(db, jobId)
-      if (!queuedJob || queuedJob.status !== "queued") return null
+      const selectedJob = await this._getJobRowById(db, jobId)
+      if (!selectedJob || selectedJob.status !== "queued") return null
+      const queuedJob = await this._reconcileQueuedJobConcurrency(db, selectedJob)
+
+      if (!queuedJob) return null
       if (queuedJob.concurrencyKey && !(await this._reserveConcurrency(db, queuedJob.concurrencyKey))) return null
       const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
@@ -960,7 +1016,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
           handoff_id: handoffId,
           worker_id: workerId || null
         },
-        conditions: {id: jobId, status: "queued"}
+        conditions: {concurrency_key: queuedJob.concurrencyKey, id: jobId, status: "queued"}
       })
 
       if (affectedRows !== 1) {
@@ -969,7 +1025,16 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       }
 
       await this._recordStatusTransition(db, "queued", "handed_off")
-      return {handedOffAtMs, handoffId}
+      /** @type {import("./types.js").BackgroundJobRow} */
+      const handedOffJob = {
+        ...queuedJob,
+        handedOffAtMs,
+        handoffId,
+        status: "handed_off",
+        workerId: workerId || null
+      }
+
+      return {handedOffAtMs, handoffId, job: handedOffJob}
     })
   }
 
@@ -2355,6 +2420,41 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     })
   }
 
+  /**
+   * Applies the active generation's queue policy immediately before handoff.
+   * Explicit concurrency remains owned by the enqueue request.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {import("./types.js").BackgroundJobRow} job - Queued job snapshot.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Reconciled job, or null when its queued-state fence lost.
+   */
+  async _reconcileQueuedJobConcurrency(db, job) {
+    if (job.concurrencyKey && !job.concurrencyKey.startsWith(QUEUE_CONCURRENCY_KEY_PREFIX)) {
+      return job
+    }
+
+    const concurrency = this._resolveConcurrency({}, job.queue)
+    /** @type {BackgroundJobQueuedConcurrency} */
+    const current = concurrency
+      ? {concurrencyKey: concurrency.concurrencyKey, maxConcurrency: concurrency.maxConcurrency}
+      : {concurrencyKey: null, maxConcurrency: null}
+
+    if (concurrency) await this._ensureQueueConcurrencyKey(db, concurrency)
+    if (job.concurrencyKey === current.concurrencyKey && job.maxConcurrency === current.maxConcurrency) return job
+
+    const affectedRows = await this._updateAffectedRows(db, {
+      tableName: JOBS_TABLE,
+      data: {
+        concurrency_key: current.concurrencyKey,
+        max_concurrency: current.maxConcurrency
+      },
+      conditions: {concurrency_key: job.concurrencyKey, id: job.id, status: "queued"}
+    })
+
+    if (affectedRows !== 1) return null
+
+    return {...job, concurrencyKey: current.concurrencyKey, maxConcurrency: current.maxConcurrency}
+  }
+
   /**
    * Reads the configured max concurrency for a queue from the background-jobs config.
    * @param {string} queue - Queue name.
@@ -2763,14 +2863,19 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   /**
    * Rebuilds durable counts from active handoffs.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
-   * @returns {Promise<void>} - Resolves when reconciled.
+   * @param {{insideTransaction?: boolean}} [options] - Reuse an enclosing transaction.
+   * @returns {Promise<import("./types.js").BackgroundJobConcurrencyReconciliation>} - Repair summary.
    */
-  async _reconcileConcurrency(db) {
-    if (!(await db.tableExists(CONCURRENCY_TABLE))) return
+  async _reconcileConcurrency(db, {insideTransaction = false} = {}) {
+    if (!(await db.tableExists(CONCURRENCY_TABLE))) {
+      return {candidateCount: 0, checkedCount: 0, repairedCount: 0, repairs: [], repairsTruncatedCount: 0}
+    }
+
     const activeRows = await db
       .newQuery()
       .from(JOBS_TABLE)
       .select("concurrency_key")
+      .select("COUNT(*) AS active_count")
       .where({status: "handed_off"})
       .where(`${db.quoteColumn("concurrency_key")} IS NOT NULL`)
       .group("concurrency_key")
@@ -2779,18 +2884,49 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       .newQuery()
       .from(CONCURRENCY_TABLE)
       .select("concurrency_key")
+      .select("active_count")
       .where(`${db.quoteColumn("active_count")} != 0`)
       .results()
-    const concurrencyKeys = new Set(
-      [...activeRows, ...staleRows].map((row) =>
-        String(/** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row).concurrency_key)
-      )
-    )
+    /** @type {Map<string, number>} */
+    const activeCounts = new Map()
+    /** @type {Map<string, number>} */
+    const persistedCounts = new Map()
 
-    for (const concurrencyKey of [...concurrencyKeys].sort()) {
-      await this._transactionResult(db, async () => {
-        await this._reconcileConcurrencyKey(db, concurrencyKey)
-      })
+    for (const rawRow of activeRows) {
+      const row = /** @type {BackgroundJobConcurrencyCountRow} */ (rawRow)
+      activeCounts.set(row.concurrency_key, this._validatedConcurrencyCount(row.active_count, row.concurrency_key))
+    }
+
+    for (const rawRow of staleRows) {
+      const row = /** @type {BackgroundJobConcurrencyCountRow} */ (rawRow)
+      persistedCounts.set(row.concurrency_key, this._validatedConcurrencyCount(row.active_count, row.concurrency_key))
+    }
+
+    const concurrencyKeys = [...new Set([...activeCounts.keys(), ...persistedCounts.keys()])].sort()
+    const candidateKeys = concurrencyKeys.filter((concurrencyKey) => {
+      return (activeCounts.get(concurrencyKey) || 0) !== (persistedCounts.get(concurrencyKey) || 0)
+    })
+    /** @type {import("./types.js").BackgroundJobConcurrencyRepair[]} */
+    const repairs = []
+    let repairedCount = 0
+
+    for (const concurrencyKey of candidateKeys) {
+      const repair = insideTransaction
+        ? await this._reconcileConcurrencyKey(db, concurrencyKey)
+        : await this._transactionResult(db, async () => await this._reconcileConcurrencyKey(db, concurrencyKey))
+
+      if (!repair) continue
+
+      repairedCount++
+      if (repairs.length < CONCURRENCY_REPAIR_SAMPLE_LIMIT) repairs.push(repair)
+    }
+
+    return {
+      candidateCount: candidateKeys.length,
+      checkedCount: concurrencyKeys.length,
+      repairedCount,
+      repairs,
+      repairsTruncatedCount: repairedCount - repairs.length
     }
   }
 
@@ -2799,29 +2935,57 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * lock order used by handoff and completion transitions.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
    * @param {string} concurrencyKey - Counter key.
-   * @returns {Promise<void>} - Resolves when reconciled.
+   * @returns {Promise<import("./types.js").BackgroundJobConcurrencyRepair | null>} - Applied repair.
    */
   async _reconcileConcurrencyKey(db, concurrencyKey) {
     await this._lockConcurrencyRow(db, concurrencyKey)
+    const persistedRows = await db
+      .newQuery()
+      .from(CONCURRENCY_TABLE)
+      .select("active_count")
+      .select("concurrency_key")
+      .where({concurrency_key: concurrencyKey})
+      .limit(1)
+      .results()
+
+    if (!persistedRows[0]) throw new Error(`Missing background job concurrency counter for ${concurrencyKey}`)
+
+    const persistedRow = /** @type {BackgroundJobConcurrencyCountRow} */ (persistedRows[0])
+    const previousActiveCount = this._validatedConcurrencyCount(persistedRow.active_count, concurrencyKey)
     const rows = await db
       .newQuery()
       .from(JOBS_TABLE)
       .select("COUNT(*) AS active_count")
       .where({concurrency_key: concurrencyKey, status: "handed_off"})
       .results()
-    const activeCount = this._normalizeNumber(
-      /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (rows[0] || {}).active_count
-    )
+    const countRow = /** @type {{active_count: number | string}} */ (rows[0])
+    const activeCount = this._validatedConcurrencyCount(countRow.active_count, concurrencyKey)
 
-    if (activeCount === null || !Number.isSafeInteger(activeCount) || activeCount < 0) {
-      throw new Error(`Invalid reconciled background job concurrency count for ${concurrencyKey}: ${activeCount}`)
-    }
+    if (activeCount === previousActiveCount) return null
 
     await db.update({
       tableName: CONCURRENCY_TABLE,
       data: {active_count: activeCount},
       conditions: {concurrency_key: concurrencyKey}
     })
+
+    return {activeCount, concurrencyKey, previousActiveCount}
+  }
+
+  /**
+   * Validates a database count before it participates in reconciliation.
+   * @param {number | string} value - Raw count.
+   * @param {string} concurrencyKey - Counter key for diagnostics.
+   * @returns {number} - Safe non-negative count.
+   */
+  _validatedConcurrencyCount(value, concurrencyKey) {
+    const count = this._normalizeNumber(value)
+
+    if (count === null || !Number.isSafeInteger(count) || count < 0) {
+      throw new Error(`Invalid reconciled background job concurrency count for ${concurrencyKey}: ${count}`)
+    }
+
+    return count
   }
 
   /**
@@ -2836,11 +3000,12 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * while a backlog exists otherwise leaves persisted rows stale: pre-cap jobs
    * keep a null key and bypass the cap, post-removal jobs stay capped under a
    * now-unconfigured key, and a changed numeric cap stays stale until the next
-   * enqueue. Bring the durable state in line with config: sync each configured
-   * queue's stored cap, adopt not-yet-keyed non-terminal jobs onto their queue
-   * key, and release non-terminal jobs from queue keys whose queue is no
-   * longer capped. Runs before {@link _reconcileConcurrency} so the rebuilt
-   * active counts reflect the adopted/released keys.
+   * enqueue. Bring queued durable state in line with config: sync each configured
+   * queue's stored cap, adopt not-yet-keyed queued jobs onto their queue key,
+   * and release queued jobs from queue keys whose queue is no longer capped.
+   * Existing handoffs retain the policy and reservation they started with, so
+   * reconciliation cannot race their completion/retry transitions. Runs before
+   * {@link _reconcileConcurrency} so any pre-existing active counts are exact.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
    * @returns {Promise<void>} - Resolves when reconciled.
    */
@@ -2853,7 +3018,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     const keyColumn = db.quoteColumn("concurrency_key")
     const capColumn = db.quoteColumn("max_concurrency")
     const queueColumn = db.quoteColumn("queue")
-    const nonTerminal = `${db.quoteColumn("status")} IN (${db.quote("queued")}, ${db.quote("handed_off")})`
+    const queued = `${db.quoteColumn("status")} = ${db.quote("queued")}`
     /** @type {Set<string>} */
     const cappedQueues = new Set()
 
@@ -2868,7 +3033,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       await this._ensureQueueConcurrencyKey(db, {concurrencyKey, maxConcurrency: cap})
       await db.query(
         `UPDATE ${jobsTable} SET ${keyColumn} = ${db.quote(concurrencyKey)}, ${capColumn} = ${Number(cap)} ` +
-        `WHERE ${queueColumn} = ${db.quote(queue)} AND ${keyColumn} IS NULL AND ${nonTerminal}`
+        `WHERE ${queueColumn} = ${db.quote(queue)} AND ${keyColumn} IS NULL AND ${queued}`
       )
     }
 
@@ -2887,7 +3052,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
 
       await db.query(
         `UPDATE ${jobsTable} SET ${keyColumn} = NULL, ${capColumn} = NULL ` +
-        `WHERE ${keyColumn} = ${db.quote(concurrencyKey)} AND ${nonTerminal}`
+        `WHERE ${keyColumn} = ${db.quote(concurrencyKey)} AND ${queued}`
       )
     }
   }
@@ -3025,15 +3190,29 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   }
 
   /**
-   * Admits transactions to the process-local FIFO before they check out a
-   * connection. Cross-process ordering remains the responsibility of durable
-   * row/advisory locks and unique constraints acquired around the callback.
+   * Runs a serialized callback inside one transaction.
    * @template T
    * @param {(db: import("../database/drivers/base.js").default) => Promise<T>} callback - Transaction callback.
    * @param {BackgroundJobTransactionSerializationOptions} [options] - Serialization options.
    * @returns {Promise<T>} Callback result.
    */
   async _serializedTransactionMutation(callback, options = {}) {
+    return await this._serializedConnectionMutation(
+      async (db) => await this._transactionResult(db, async () => await callback(db)),
+      options
+    )
+  }
+
+  /**
+   * Admits mutation callbacks to the process-local FIFO before they check out a
+   * connection. Cross-process ordering remains the responsibility of durable
+   * row/advisory locks and unique constraints acquired around the callback.
+   * @template T
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<T>} callback - Connection callback.
+   * @param {BackgroundJobTransactionSerializationOptions} [options] - Serialization options.
+   * @returns {Promise<T>} Callback result.
+   */
+  async _serializedConnectionMutation(callback, options = {}) {
     const identifier = this.getDatabaseIdentifier() || "default"
     const previous = transactionMutationChains.get(identifier) || Promise.resolve()
     let resolveRun = () => {}
@@ -3057,7 +3236,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         }
 
         try {
-          return await this._transactionResult(db, async () => await callback(db))
+          return await callback(db)
         } finally {
           if (advisoryLock) await db.releaseAdvisoryLock(advisoryLock.name)
         }

package/src/background-jobs/types.js

@@ -51,6 +51,20 @@
  * @property {number} maxConcurrency - Positive cap.
  * @property {boolean} queueDerived - Whether queue configuration owns the cap.
  */
+/**
+ * @typedef {object} BackgroundJobConcurrencyRepair
+ * @property {number} activeCount - Exact handed-off job count persisted by the repair.
+ * @property {string} concurrencyKey - Durable cap identity.
+ * @property {number} previousActiveCount - Persisted count replaced by the repair.
+ */
+/**
+ * @typedef {object} BackgroundJobConcurrencyReconciliation
+ * @property {number} candidateCount - Snapshot mismatches rechecked under their counter locks.
+ * @property {number} checkedCount - Active or nonzero durable counters compared in the initial snapshot.
+ * @property {number} repairedCount - Counters whose persisted values were changed.
+ * @property {BackgroundJobConcurrencyRepair[]} repairs - Bounded deterministic sample of applied repairs.
+ * @property {number} repairsTruncatedCount - Applied repairs omitted from the sample.
+ */
 /**
  * @typedef {object} PreparedLocalBackgroundJob
  * @property {string} argsDigest - Fixed-width digest of the serialized arguments.
@@ -78,6 +92,7 @@
  * @typedef {object} BackgroundJobHandoff
  * @property {string} handoffId - Unique handoff lease id.
  * @property {number} handedOffAtMs - Time handed to a worker in ms.
+ * @property {BackgroundJobRow} [job] - Exact committed job snapshot when the adapter changes dispatch data during the claim.
  */
 /**
  * @typedef {object} BackgroundJobHandoffSnapshot

package/src/configuration-types.js

@@ -450,7 +450,7 @@
  * @property {string[]} [builtInMemberCommands] - Built-in member command names (`find`, `update`, `destroy`, `attach`, `download`, `url`).
  * @property {string} [modelName] - Frontend model name override.
  * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
- * @property {string} [primaryKey] - Primary key attribute name.
+ * @property {string | string[]} [primaryKey] - Primary key attribute name or ordered composite primary-key attribute names.
  * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
  * @property {FrontendModelResourceSyncConfiguration | boolean} [sync] - Optional safe local/offline sync policy metadata. `policy` participates in the hash but is not exposed to generated frontend config/manifest.
  */