velocious 1.0.525 → 1.0.526

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.525",
+  "version": "1.0.526",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/main.js

@@ -784,6 +784,37 @@ export default class BackgroundJobsMain {
     errorEvents.emit("all-error", {...payload, errorType: "background-job-failed"})
   }
 
+  /**
+   * Emits `background-job-orphaned` (mirrored to `all-error`) for a job the time-based orphan sweep
+   * reclaimed after its worker died mid-run. Unlike `background-job-failed`, which fires on a
+   * worker's failure report, this fires from the main process's sweep, so applications can react to
+   * a dead worker's specific job — recover the work it left behind — without polling. `willRetry`
+   * reflects whether the reclaim returned the job to the queue for another attempt.
+   * @param {{job: import("./types.js").BackgroundJobRow}} args - The orphaned job.
+   * @returns {void}
+   */
+  _emitBackgroundJobOrphaned({job}) {
+    const normalizedError = this._normalizeFailureError(job.lastError ?? "Job orphaned after timeout")
+    const payload = {
+      context: {
+        attempts: job.attempts,
+        jobArgs: job.args,
+        jobId: job.id,
+        jobName: job.jobName,
+        maxRetries: job.maxRetries,
+        stage: "background-job-orphaned",
+        status: job.status,
+        terminal: job.status === "failed" || job.status === "orphaned",
+        willRetry: job.status === "queued"
+      },
+      error: normalizedError
+    }
+    const errorEvents = this.configuration.getErrorEvents()
+
+    errorEvents.emit("background-job-orphaned", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "background-job-orphaned"})
+  }
+
   /**
    * Runs normalize failure error.
    * @param {?} error - Reported failure value.
@@ -1170,14 +1201,26 @@ export default class BackgroundJobsMain {
 
   async _sweepOrphans() {
     try {
-      const count = await this.store.markOrphanedJobs()
+      const orphanedJobs = await this.store.markOrphanedJobs()
 
-      if (count > 0) {
-        this.logger.warn(() => ["Marked orphaned background jobs", count])
-        // Reclaimed orphans become `queued` again — wake the dispatcher
-        // so they aren't stranded until the next external signal.
+      if (orphanedJobs.length > 0) {
+        this.logger.warn(() => ["Marked orphaned background jobs", orphanedJobs.length])
+        // Reclaimed orphans become `queued` again — wake the dispatcher first so
+        // an application event handler that throws below cannot strand them
+        // queued until the next external enqueue/reconnect.
         this._notifyEnqueued()
         await this._drain()
+        // Emit an event per orphaned job so applications can react to a dead
+        // worker's specific job (e.g. targeted recovery) instead of only polling
+        // for its aftermath. Isolate each so one throwing handler can't suppress
+        // the events for the rest.
+        for (const job of orphanedJobs) {
+          try {
+            this._emitBackgroundJobOrphaned({job})
+          } catch (error) {
+            this.logger.error(() => ["A background-job-orphaned event handler threw:", error])
+          }
+        }
       }
     } catch (error) {
       this.logger.error(() => ["Failed to mark orphaned jobs:", error])

package/src/background-jobs/store.js

@@ -547,7 +547,7 @@ export default class BackgroundJobsStore {
    * Runs mark orphaned jobs.
    * @param {object} [args] - Options.
    * @param {number} [args.orphanedAfterMs] - Mark jobs orphaned after this duration.
-   * @returns {Promise<number>} - Count of orphaned jobs.
+   * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - The jobs this sweep marked orphaned.
    */
   async markOrphanedJobs({orphanedAfterMs = ORPHANED_AFTER_MS} = {}) {
     await this.ensureReady()
@@ -562,7 +562,8 @@ export default class BackgroundJobsStore {
 
       const rows = await query.results()
 
-      let orphanedCount = 0
+      /** @type {import("./types.js").BackgroundJobRow[]} */
+      const orphanedJobs = []
 
       for (const row of rows) {
         const job = this._normalizeJobRow(row)
@@ -588,10 +589,10 @@ export default class BackgroundJobsStore {
           conditions: {id: job.id, status: "handed_off", handed_off_at_ms: job.handedOffAtMs}
         })
 
-        if (orphanedJob) orphanedCount += 1
+        if (orphanedJob) orphanedJobs.push(orphanedJob)
       }
 
-      return orphanedCount
+      return orphanedJobs
     })
   }
 
@@ -1075,10 +1076,30 @@ export default class BackgroundJobsStore {
     if (affectedRows !== 1) return null
     await this._releaseConcurrency(db, job.concurrencyKey)
 
-    const updatedJob = await this._getJobRowById(db, job.id)
+    // Return a snapshot of the transition this update just applied rather than re-reading the row.
+    // We won the conditional update (affectedRows === 1), so this state is authoritative; re-reading
+    // could instead observe a newer state if another dispatcher reclaims a requeued job between the
+    // update and the read (overlapping mains / polling dispatch), which would misreport the
+    // status/terminal/willRetry of this transition to failure/orphan event listeners.
+    const status = shouldRetry ? "queued" : (markOrphaned ? "orphaned" : "failed")
+    /** @type {import("./types.js").BackgroundJobRow} */
+    const transitionedJob = {
+      ...job,
+      attempts: nextAttempt,
+      handedOffAtMs: null,
+      lastError: failureMessage,
+      status,
+      workerId: null
+    }
+
+    if (markOrphaned) transitionedJob.orphanedAtMs = now
+    if (shouldRetry) {
+      transitionedJob.scheduledAtMs = scheduledAt
+    } else if (!markOrphaned) {
+      transitionedJob.failedAtMs = now
+    }
 
-    if (!updatedJob) return null
-    return updatedJob
+    return transitionedJob
   }
 
   /**