velocious 1.0.739 → 1.0.741

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "velocious": "build/bin/velocious.js"
4
4
  },
5
5
  "name": "velocious",
6
- "version": "1.0.739",
6
+ "version": "1.0.741",
7
7
  "main": "build/index.js",
8
8
  "types": "build/index.d.ts",
9
9
  "files": [
@@ -153,9 +153,11 @@ export function buildLaneFairnessOrderSql({configuration, db, nowMs, jobsTable,
153
153
 
154
154
  /**
155
155
  * Builds the raw lane-fairness rank used to compose the primary queue rank. A configured capped
156
- * lane without a claim stamp receives the full global ceiling boost as never-served work; a lane
157
- * without a durable queue counter contributes zero and keeps the historical row-age fallback.
158
- * A long-ago claim stamp contributes its full starvation age to the primary rank.
156
+ * lane without a claim stamp contributes no service-age bonus: without a claim there is no
157
+ * lane-service history to rank. Once its row reaches its own cap, its configured priority is
158
+ * retained as a small primary-key tie signal so a deep backlog cannot win solely by row age. A
159
+ * long-ago claim stamp contributes its full starvation age to the primary rank. A lane without a
160
+ * durable queue counter contributes zero and keeps the historical row-age fallback.
159
161
  * @param {object} args - Options.
160
162
  * @param {import("../configuration.js").default} args.configuration - Active configuration.
161
163
  * @param {import("../database/drivers/base.js").default} args.db - Connection.
@@ -170,7 +172,6 @@ export function buildLaneFairnessRankSql({configuration, db, nowMs, jobsTable, c
170
172
 
171
173
  const queues = configuration.getBackgroundJobsConfig().queues || {}
172
174
  const highestPriority = Math.max(0, ...Object.values(queues).map((queueConfig) => Number.isFinite(queueConfig?.priority) ? Number(queueConfig.priority) : 0))
173
- const neverServedBoost = (highestPriority + 1) * unitMs
174
175
  const queueExpression = `COALESCE(${jobsTable}.${db.quoteColumn("queue")}, ${db.quote(DEFAULT_BACKGROUND_JOB_QUEUE)})`
175
176
  const cappedQueues = Object.entries(queues).filter(([, queueConfig]) => Number.isInteger(queueConfig?.maxConcurrent) && Number(queueConfig.maxConcurrent) > 0)
176
177
  // Only queues with a `maxConcurrent` get a durable lane counter. With none configured there is
@@ -181,5 +182,11 @@ export function buildLaneFairnessRankSql({configuration, db, nowMs, jobsTable, c
181
182
  `(SELECT ${concurrencyTable}.${db.quoteColumn("last_claimed_at_ms")} FROM ${concurrencyTable} ` +
182
183
  `WHERE ${concurrencyTable}.${db.quoteColumn("concurrency_key")} = ${laneKeyCase})`
183
184
 
184
- return `(CASE WHEN ${laneKeyCase} IS NULL THEN 0 WHEN ${lastClaimedLookup} IS NULL THEN ${neverServedBoost} ELSE (${Number(nowMs)} - ${lastClaimedLookup}) END)`
185
+ const neverServedTie = `CASE ${queueExpression} ${cappedQueues.map(([queue, queueConfig]) => {
186
+ const priority = Number.isFinite(queueConfig?.priority) ? Number(queueConfig.priority) : 0
187
+ const agingCap = (highestPriority - priority + 1) * unitMs
188
+ return `WHEN ${db.quote(queue)} THEN CASE WHEN ${jobsTable}.${db.quoteColumn("scheduled_at_ms")} <= (${Number(nowMs)} - ${agingCap}) THEN ${priority} ELSE 0 END`
189
+ }).join(" ")} ELSE 0 END`
190
+
191
+ return `(CASE WHEN ${laneKeyCase} IS NULL THEN 0 WHEN ${lastClaimedLookup} IS NULL THEN (${neverServedTie}) ELSE (${Number(nowMs)} - ${lastClaimedLookup}) END)`
185
192
  }
@@ -28,7 +28,7 @@ import {
28
28
  rescheduledBackgroundJobAtMs,
29
29
  retryDelayMs
30
30
  } from "./job-semantics.js"
31
- import {buildLaneFairnessOrderSql, buildLaneFairnessRankSql, buildQueuePriorityOrderSql, laneConcurrencyKey} from "./queue-priority-order.js"
31
+ import {buildLaneFairnessOrderSql, buildLaneFairnessRankSql, buildQueuePriorityOrderSql, laneConcurrencyKey, queuePriorityAgingUnitMs} from "./queue-priority-order.js"
32
32
  import {
33
33
  MAIL_DELIVERY_OPERATIONS_TABLE,
34
34
  mailDeliveryOperationForJob,
@@ -1238,11 +1238,9 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
1238
1238
  if (laneFairnessOrder) query = query.order(laneFairnessOrder)
1239
1239
  }
1240
1240
 
1241
- // Job-level priority applies inside the queue ranking above. A retry is
1242
- // stored at RETRY_BACKGROUND_JOB_PRIORITY (-1), so it sorts behind every
1243
- // first attempt without delaying itself further than the backoff already
1244
- // does. COALESCE covers rows written before the column existed.
1245
- query = query.order(`COALESCE(${db.quoteColumn("priority")}, ${DEFAULT_BACKGROUND_JOB_PRIORITY}) DESC`)
1241
+ // Job-level priority applies inside the queue ranking above, and it buys one aging unit of
1242
+ // queue-jumping — not an unlimited lead. See `_jobPriorityOrderSql`.
1243
+ query = query.order(this._jobPriorityOrderSql(db, now))
1246
1244
  }
1247
1245
 
1248
1246
  query = query
@@ -1312,6 +1310,36 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
1312
1310
  })
1313
1311
  }
1314
1312
 
1313
+ /**
1314
+ * Builds the job-level priority tie-break for the dispatch path, expressed in the same unit the
1315
+ * queue ranking uses: `priority * queuePriorityAgingUnitMs + (now - scheduled_at_ms) DESC`, so a
1316
+ * priority unit buys exactly that many milliseconds of queue-jumping and no more.
1317
+ *
1318
+ * The primary rank caps each lane's age term at the gap to the highest configured priority, so
1319
+ * every lane whose backlog has aged past that cap converges on the identical ceiling and this
1320
+ * tie-break is the only term left that still reflects how long a row has actually waited. Written
1321
+ * as an absolute `priority DESC` the lead never decays: a row demoted to
1322
+ * {@link RETRY_BACKGROUND_JOB_PRIORITY} (-1) cannot outrank any priority-0 row in its lane however
1323
+ * long it waits, because its own age stopped counting once it passed the cap. Measured on
1324
+ * production 2026-11-16 (TensorBuzz tenant `tensorbuzz_project_a2faf595709bee70643b`): 1,299 queued
1325
+ * rows at -1 with the oldest waiting 24 h, against 2,816 claims in the same 10-minute window for
1326
+ * priority 0 — the same lane and the same rank, decided by absolute priority every cycle.
1327
+ *
1328
+ * Opting out of aging (`queuePriorityAgingUnitMs: null`) asks for strict priority ordering, so the
1329
+ * comparison stays absolute there. COALESCE covers rows written before the column existed.
1330
+ * @param {import("../database/drivers/base.js").default} db - Database connection.
1331
+ * @param {number} nowMs - Dispatch instant.
1332
+ * @returns {string} - Raw SQL `ORDER BY … DESC` term.
1333
+ */
1334
+ _jobPriorityOrderSql(db, nowMs) {
1335
+ const priorityExpression = `COALESCE(${db.quoteColumn("priority")}, ${DEFAULT_BACKGROUND_JOB_PRIORITY})`
1336
+ const unitMs = queuePriorityAgingUnitMs(this.configuration)
1337
+
1338
+ if (unitMs === null) return `${priorityExpression} DESC`
1339
+
1340
+ return `(${priorityExpression} * ${Number(unitMs)} + (${Number(nowMs)} - ${db.quoteColumn("scheduled_at_ms")})) DESC`
1341
+ }
1342
+
1315
1343
  /**
1316
1344
  * Reads the per-lane dispatch boundary for every queue holding eligible queued work:
1317
1345
  * backlog depth, the oldest eligible row, and how many jobs that lane actually claimed