tina4-nodejs 3.13.104 → 3.13.105

package/packages/core/src/queue.ts

@@ -144,7 +144,13 @@ export interface QueueBackendInterface {
   // persistent-connection rewrite lands.
   complete?(queue: string, id: string): void;
   fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
-  retry?(queue: string, id: string, delaySeconds?: number): void;
+  /**
+   * Explicit manual re-queue: returns true if the id was found and revived,
+   * false otherwise (parity with Python's backend.retry_job()). A backend may
+   * legacy-return void; callers coerce a void return to true so nothing that
+   * used to be reported as success silently flips to failure.
+   */
+  retry?(queue: string, id: string, delaySeconds?: number): boolean | void;
   deadLetters?(queue: string, maxRetries?: number): QueueJob[];
   failed?(queue: string, maxRetries?: number): QueueJob[];
   retryFailed?(queue: string, maxRetries?: number): number;
@@ -400,7 +406,19 @@ export class Queue {
   }
 
   /**
-   * Count jobs filtered by status. Defaults to "pending".
+   * Count jobs by status. Defaults to "pending".
+   *
+   * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+   * but-attempted ones, because they live in the pending queue under the
+   * auto-retry lifecycle (see failed()).
+   * ``"reserved"`` counts jobs a consumer has popped but not yet
+   * completed/failed (in-flight against the visibility timeout).
+   * ``"completed"`` counts jobs the consumer has finished successfully.
+   * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+   * the dead-letter store -- jobs whose attempts >= maxRetries and that
+   * have given up. Use deadLetters() to list them. Retryable-but-attempted
+   * jobs are NOT counted by size("failed"); use failed() to list them or
+   * size("pending") to include them in a total.
    */
   size(status: string = "pending"): number {
     const q = this.topic;
@@ -455,13 +473,21 @@ export class Queue {
   /**
    * Get jobs that failed at least once but are still being retried
    * (0 < attempts < maxRetries). These live in the pending queue under the
-   * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+   * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+   * count and a retryBackoff delay) so pop() picks them up again. They are
+   * NOT counted by size("failed") -- that alias counts the dead-letter store,
+   * matching deadLetters(). To include retryable-failed jobs in a total, use
+   * size("pending"). Terminal failures are returned by deadLetters().
    */
   failed(): QueueJob[] {
-    if (this.externalBackend?.failed) {
-      return this.externalBackend.failed(this.topic, this._maxRetries);
-    }
-    return this.liteBackend.failed(this.topic, this._maxRetries);
+    const raw = this.externalBackend?.failed
+      ? this.externalBackend.failed(this.topic, this._maxRetries)
+      : this.liteBackend.failed(this.topic, this._maxRetries);
+    // Wrap so callers get the full Job lifecycle (parity with deadLetters()
+    // and Python's failed()).
+    return raw.map((data) =>
+      createJob({ ...(data as JobData), topic: (data as JobData).topic ?? this.topic }, this),
+    );
   }
 
   /**
@@ -473,21 +499,31 @@ export class Queue {
    */
   retry(jobId?: string, delaySeconds?: number): boolean {
     if (jobId) {
-      // Retry a specific job by ID
+      // Retry a specific job by ID. Honour whatever the external backend
+      // returns (a boolean) so an unknown id reports false; only coerce a
+      // legacy void return to true to preserve the pre-3.13.105 contract on
+      // a backend that hasn't been updated (LiteBackend already returns bool).
       if (this.externalBackend?.retry) {
-        this.externalBackend.retry(this.topic, jobId, delaySeconds);
-        return true;
+        const result = this.externalBackend.retry(this.topic, jobId, delaySeconds);
+        return result === undefined ? true : Boolean(result);
       }
       return this.liteBackend.retry(this.topic, jobId, delaySeconds);
     }
-    // Retry all dead-letter jobs
+    // Retry ALL dead-letter jobs -- an explicit for...of iterates every
+    // entry rather than a reducer like .some() that would short-circuit on
+    // the first truthy result (PY-12-04 parity: Python's generator-inside-
+    // any() had exactly that bug pre-3.13.105 and left the remaining
+    // dead letters silently in the store).
     const deadJobs = this.deadLetters();
     if (deadJobs.length === 0) return false;
     let retried = false;
     for (const job of deadJobs) {
       if (this.externalBackend?.retry) {
-        this.externalBackend.retry(this.topic, job.id, delaySeconds);
-        retried = true;
+        const result = this.externalBackend.retry(this.topic, job.id, delaySeconds);
+        // A modern backend returns bool; a legacy backend returns void which
+        // we optimistically treat as revived (parity with the pre-3.13.105
+        // pathway that never had a way to know otherwise).
+        if (result === undefined || Boolean(result)) retried = true;
       } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
         retried = true;
       }
@@ -496,13 +532,34 @@ export class Queue {
   }
 
   /**
-   * Get dead letter jobs — failed jobs that exceeded max retries.
+   * Get jobs that exceeded max_retries -- terminal failures.
+   *
+   * Same set counted by size("failed") / size("dead") / size("dead_letter")
+   * (three aliases for the dead-letter store). To LIST retryable-but-
+   * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+   * being auto-retried, use failed() -- those live in the pending queue and
+   * are NOT dead letters.
+   *
+   * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+   * so callers can iterate uniformly with the rest of the queue API and, in
+   * particular, call ``.retry()`` on each to manually revive it:
+   *
+   *     for (const job of queue.deadLetters()) {
+   *       Log.warn(`revived ${job.id}: ${job.error}`);
+   *       job.retry();
+   *     }
    */
   deadLetters(maxRetries?: number): QueueJob[] {
-    if (this.externalBackend?.deadLetters) {
-      return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
-    }
-    return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    const raw = this.externalBackend?.deadLetters
+      ? this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries)
+      : this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    // Wrap so ``job.retry()`` / ``job.fail()`` / ``job.complete()`` work
+    // uniformly (parity with pop() and the Python master). Preserves the
+    // job's own topic so the lifecycle methods route back to THIS queue's
+    // backend even on a job that dead-lettered on a different topic.
+    return raw.map((data) =>
+      createJob({ ...(data as JobData), topic: (data as JobData).topic ?? this.topic }, this),
+    );
   }
 
   /**

package/packages/core/src/queueBackends/liteBackend.ts

@@ -677,11 +677,27 @@ export class LiteBackend {
    * Explicit re-queue requested by the caller (job.retry()).
    *
    * Always re-enqueues regardless of the retry limit — manual override,
-   * distinct from the automatic failJob() path.
+   * distinct from the automatic failJob() path. Cleans up BOTH the
+   * reservation record AND any dead-letter file for this id, so a caller
+   * that iterates deadLetters() and calls .retry() on each doesn't leave
+   * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+   * Aligns with retry(queue, jobId) which had always unlinked the
+   * dead-letter file -- two spellings of the same intent that previously
+   * diverged.
    */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
     // Clear the reservation — the consumer acknowledged (with an explicit retry).
     this.clearReservation(queue, job.id);
+    // Drop any dead-letter file for this id BEFORE the re-queue -- if this
+    // job came from deadLetters() it lives in failed/ and would otherwise
+    // stay on disk while a fresh pending file appears in the queue dir, so
+    // the next deadLetters() call reports the job again and a consumer
+    // processes it twice.
+    try {
+      unlinkSync(join(this.ensureFailedDir(queue), `${job.id}.queue-data`));
+    } catch {
+      // ENOENT is fine (the job never dead-lettered or was already cleared).
+    }
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
     this.requeue(queue, job, delaySeconds ?? 0, undefined);

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -343,17 +343,67 @@ export class MongoBackend implements QueueBackend {
             process.stdout.write("__OK__");
           }
           else if (operation === "retry") {
-            // Explicit manual re-queue (always re-enqueues). data = JSON
-            // { id, delaySeconds }.
+            // Explicit manual re-queue. Serves BOTH Queue.retry(id) (revive
+            // a dead-letter job) AND job.retry() (manual re-queue of a live
+            // reserved/pending job) so the Mongo backend matches
+            // LiteBackend's dual behaviour.
+            //
+            // 1) DL revival (Queue.retry(id) after fail exhausted retries).
+            //    Pre-3.13.105 this branch was BROKEN: the search filter was
+            //    { queue: queueName, id, status: "failed" } -- three separate
+            //    reasons it could never match. dead_letter() inserts under
+            //    queueName + ".dead_letter" (not queueName), carries
+            //    status "dead" (not "failed"), and the original under
+            //    queueName was already acked to "completed" by the time the
+            //    DL was written. Now we look up in the DL namespace by id,
+            //    delete the DL doc first (so an interrupted retry never
+            //    leaves both a DL and a fresh pending doc), and upsert the
+            //    original back to pending -- re-hydrating if the original
+            //    was purged (housekeeping) so a retry always works.
+            // 2) Live-doc manual re-queue (job.retry() on a job the caller
+            //    just popped and wants back in pending). The live-doc path
+            //    is preserved from before 3.13.105.
+            //
+            // Returns __OK__ when either path acted; __NOT_FOUND__ when
+            // neither the DL nor the live doc existed, so Queue.retry(id)
+            // can now report the pre-3.13.105 blanket-true as false for
+            // unknown ids. data = JSON { id, delaySeconds }.
             const info = JSON.parse(data);
+            const dlTopic = queueName + ".dead_letter";
+            const now = new Date().toISOString();
             const avail = info.delaySeconds > 0
               ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
-              : new Date().toISOString();
-            await col.updateOne(
-              { queue: queueName, id: info.id },
-              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
-            );
-            process.stdout.write("__OK__");
+              : now;
+            const dlDoc = await col.findOne({ queue: dlTopic, id: info.id });
+            if (dlDoc !== null) {
+              await col.deleteOne({ _id: dlDoc._id });
+              const payload = dlDoc.payload ?? {};
+              const priority = dlDoc.priority ?? 0;
+              await col.updateOne(
+                { queue: queueName, id: info.id },
+                {
+                  $set: {
+                    status: "pending",
+                    availableAt: avail,
+                    reservedAt: null,
+                    error: null,
+                    payload,
+                    priority,
+                    id: info.id,
+                    createdAt: dlDoc.createdAt ?? now,
+                  },
+                  $inc: { attempts: 1 },
+                },
+                { upsert: true },
+              );
+              process.stdout.write("__OK__");
+            } else {
+              const result = await col.updateOne(
+                { queue: queueName, id: info.id },
+                { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+              );
+              process.stdout.write(result.matchedCount > 0 ? "__OK__" : "__NOT_FOUND__");
+            }
           }
           else if (operation === "deadLetters") {
             const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
@@ -398,10 +448,20 @@ export class MongoBackend implements QueueBackend {
             process.stdout.write(String(revived));
           }
           else if (operation === "purge") {
-            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            // Delete docs by status (default: every doc for the topic).
+            // Pre-3.13.105 this filtered by { queue: queueName, status } for
+            // EVERY status -- correct for pending/reserved/completed, wrong
+            // for the dead-letter states (dead/failed/dead_letter) which
+            // live under queueName + ".dead_letter" and carry status "dead".
+            // A purge("dead") therefore deleted nothing and returned 0.
+            // data = JSON { status }.
             const info = data ? JSON.parse(data) : {};
-            const filter = { queue: queueName };
-            if (info.status) filter.status = info.status;
+            const isDead = info.status && ["dead", "failed", "dead_letter"].includes(info.status);
+            const filter = isDead
+              ? { queue: queueName + ".dead_letter" }
+              : (info.status
+                ? { queue: queueName, status: info.status }
+                : { queue: queueName });
             const res = await col.deleteMany(filter);
             process.stdout.write(String(res.deletedCount || 0));
           }
@@ -513,9 +573,15 @@ export class MongoBackend implements QueueBackend {
     this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
   }
 
-  /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
-  retry(queue: string, id: string, delaySeconds: number = 0): void {
-    this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+  /**
+   * Revive a specific dead-letter job by id. Returns true if the DL was found
+   * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+   * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+   * and Queue.retry(id) reported success for every call, even for unknown ids.
+   */
+  retry(queue: string, id: string, delaySeconds: number = 0): boolean {
+    const out = this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+    return out.includes("__OK__");
   }
 
   /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */

package/packages/orm/dist/index.js

@@ -17249,17 +17249,67 @@ var init_mongoBackend = __esm({
             process.stdout.write("__OK__");
           }
           else if (operation === "retry") {
-            // Explicit manual re-queue (always re-enqueues). data = JSON
-            // { id, delaySeconds }.
+            // Explicit manual re-queue. Serves BOTH Queue.retry(id) (revive
+            // a dead-letter job) AND job.retry() (manual re-queue of a live
+            // reserved/pending job) so the Mongo backend matches
+            // LiteBackend's dual behaviour.
+            //
+            // 1) DL revival (Queue.retry(id) after fail exhausted retries).
+            //    Pre-3.13.105 this branch was BROKEN: the search filter was
+            //    { queue: queueName, id, status: "failed" } -- three separate
+            //    reasons it could never match. dead_letter() inserts under
+            //    queueName + ".dead_letter" (not queueName), carries
+            //    status "dead" (not "failed"), and the original under
+            //    queueName was already acked to "completed" by the time the
+            //    DL was written. Now we look up in the DL namespace by id,
+            //    delete the DL doc first (so an interrupted retry never
+            //    leaves both a DL and a fresh pending doc), and upsert the
+            //    original back to pending -- re-hydrating if the original
+            //    was purged (housekeeping) so a retry always works.
+            // 2) Live-doc manual re-queue (job.retry() on a job the caller
+            //    just popped and wants back in pending). The live-doc path
+            //    is preserved from before 3.13.105.
+            //
+            // Returns __OK__ when either path acted; __NOT_FOUND__ when
+            // neither the DL nor the live doc existed, so Queue.retry(id)
+            // can now report the pre-3.13.105 blanket-true as false for
+            // unknown ids. data = JSON { id, delaySeconds }.
             const info = JSON.parse(data);
+            const dlTopic = queueName + ".dead_letter";
+            const now = new Date().toISOString();
             const avail = info.delaySeconds > 0
               ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
-              : new Date().toISOString();
-            await col.updateOne(
-              { queue: queueName, id: info.id },
-              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
-            );
-            process.stdout.write("__OK__");
+              : now;
+            const dlDoc = await col.findOne({ queue: dlTopic, id: info.id });
+            if (dlDoc !== null) {
+              await col.deleteOne({ _id: dlDoc._id });
+              const payload = dlDoc.payload ?? {};
+              const priority = dlDoc.priority ?? 0;
+              await col.updateOne(
+                { queue: queueName, id: info.id },
+                {
+                  $set: {
+                    status: "pending",
+                    availableAt: avail,
+                    reservedAt: null,
+                    error: null,
+                    payload,
+                    priority,
+                    id: info.id,
+                    createdAt: dlDoc.createdAt ?? now,
+                  },
+                  $inc: { attempts: 1 },
+                },
+                { upsert: true },
+              );
+              process.stdout.write("__OK__");
+            } else {
+              const result = await col.updateOne(
+                { queue: queueName, id: info.id },
+                { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+              );
+              process.stdout.write(result.matchedCount > 0 ? "__OK__" : "__NOT_FOUND__");
+            }
           }
           else if (operation === "deadLetters") {
             const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
@@ -17304,10 +17354,20 @@ var init_mongoBackend = __esm({
             process.stdout.write(String(revived));
           }
           else if (operation === "purge") {
-            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            // Delete docs by status (default: every doc for the topic).
+            // Pre-3.13.105 this filtered by { queue: queueName, status } for
+            // EVERY status -- correct for pending/reserved/completed, wrong
+            // for the dead-letter states (dead/failed/dead_letter) which
+            // live under queueName + ".dead_letter" and carry status "dead".
+            // A purge("dead") therefore deleted nothing and returned 0.
+            // data = JSON { status }.
             const info = data ? JSON.parse(data) : {};
-            const filter = { queue: queueName };
-            if (info.status) filter.status = info.status;
+            const isDead = info.status && ["dead", "failed", "dead_letter"].includes(info.status);
+            const filter = isDead
+              ? { queue: queueName + ".dead_letter" }
+              : (info.status
+                ? { queue: queueName, status: info.status }
+                : { queue: queueName });
             const res = await col.deleteMany(filter);
             process.stdout.write(String(res.deletedCount || 0));
           }
@@ -17404,9 +17464,15 @@ var init_mongoBackend = __esm({
       fail(queue, id, error, maxRetries, retryBackoff = 0) {
         this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
       }
-      /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+      /**
+       * Revive a specific dead-letter job by id. Returns true if the DL was found
+       * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+       * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+       * and Queue.retry(id) reported success for every call, even for unknown ids.
+       */
       retry(queue, id, delaySeconds = 0) {
-        this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        const out = this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+        return out.includes("__OK__");
       }
       /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
       deadLetters(queue, maxRetries) {
@@ -18075,10 +18141,20 @@ var init_liteBackend = __esm({
        * Explicit re-queue requested by the caller (job.retry()).
        *
        * Always re-enqueues regardless of the retry limit — manual override,
-       * distinct from the automatic failJob() path.
+       * distinct from the automatic failJob() path. Cleans up BOTH the
+       * reservation record AND any dead-letter file for this id, so a caller
+       * that iterates deadLetters() and calls .retry() on each doesn't leave
+       * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+       * Aligns with retry(queue, jobId) which had always unlinked the
+       * dead-letter file -- two spellings of the same intent that previously
+       * diverged.
        */
       retryJob(queue, job, delaySeconds) {
         this.clearReservation(queue, job.id);
+        try {
+          unlinkSync6(join17(this.ensureFailedDir(queue), `${job.id}.queue-data`));
+        } catch {
+        }
         job.attempts = (job.attempts || 0) + 1;
         job.error = void 0;
         this.requeue(queue, job, delaySeconds ?? 0, void 0);
@@ -18277,7 +18353,19 @@ var init_queue = __esm({
         }
       }
       /**
-       * Count jobs filtered by status. Defaults to "pending".
+       * Count jobs by status. Defaults to "pending".
+       *
+       * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+       * but-attempted ones, because they live in the pending queue under the
+       * auto-retry lifecycle (see failed()).
+       * ``"reserved"`` counts jobs a consumer has popped but not yet
+       * completed/failed (in-flight against the visibility timeout).
+       * ``"completed"`` counts jobs the consumer has finished successfully.
+       * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+       * the dead-letter store -- jobs whose attempts >= maxRetries and that
+       * have given up. Use deadLetters() to list them. Retryable-but-attempted
+       * jobs are NOT counted by size("failed"); use failed() to list them or
+       * size("pending") to include them in a total.
        */
       size(status2 = "pending") {
         const q = this.topic;
@@ -18327,13 +18415,17 @@ var init_queue = __esm({
       /**
        * Get jobs that failed at least once but are still being retried
        * (0 < attempts < maxRetries). These live in the pending queue under the
-       * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+       * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+       * count and a retryBackoff delay) so pop() picks them up again. They are
+       * NOT counted by size("failed") -- that alias counts the dead-letter store,
+       * matching deadLetters(). To include retryable-failed jobs in a total, use
+       * size("pending"). Terminal failures are returned by deadLetters().
        */
       failed() {
-        if (this.externalBackend?.failed) {
-          return this.externalBackend.failed(this.topic, this._maxRetries);
-        }
-        return this.liteBackend.failed(this.topic, this._maxRetries);
+        const raw = this.externalBackend?.failed ? this.externalBackend.failed(this.topic, this._maxRetries) : this.liteBackend.failed(this.topic, this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Retry all dead letter jobs for this queue's topic.
@@ -18345,8 +18437,8 @@ var init_queue = __esm({
       retry(jobId, delaySeconds) {
         if (jobId) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, jobId, delaySeconds);
-            return true;
+            const result = this.externalBackend.retry(this.topic, jobId, delaySeconds);
+            return result === void 0 ? true : Boolean(result);
           }
           return this.liteBackend.retry(this.topic, jobId, delaySeconds);
         }
@@ -18355,8 +18447,8 @@ var init_queue = __esm({
         let retried = false;
         for (const job of deadJobs) {
           if (this.externalBackend?.retry) {
-            this.externalBackend.retry(this.topic, job.id, delaySeconds);
-            retried = true;
+            const result = this.externalBackend.retry(this.topic, job.id, delaySeconds);
+            if (result === void 0 || Boolean(result)) retried = true;
           } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
             retried = true;
           }
@@ -18364,13 +18456,28 @@ var init_queue = __esm({
         return retried;
       }
       /**
-       * Get dead letter jobs — failed jobs that exceeded max retries.
+       * Get jobs that exceeded max_retries -- terminal failures.
+       *
+       * Same set counted by size("failed") / size("dead") / size("dead_letter")
+       * (three aliases for the dead-letter store). To LIST retryable-but-
+       * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+       * being auto-retried, use failed() -- those live in the pending queue and
+       * are NOT dead letters.
+       *
+       * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+       * so callers can iterate uniformly with the rest of the queue API and, in
+       * particular, call ``.retry()`` on each to manually revive it:
+       *
+       *     for (const job of queue.deadLetters()) {
+       *       Log.warn(`revived ${job.id}: ${job.error}`);
+       *       job.retry();
+       *     }
        */
       deadLetters(maxRetries) {
-        if (this.externalBackend?.deadLetters) {
-          return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
-        }
-        return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        const raw = this.externalBackend?.deadLetters ? this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries) : this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+        return raw.map(
+          (data) => createJob({ ...data, topic: data.topic ?? this.topic }, this)
+        );
       }
       /**
        * Delete messages by status (e.g. "completed", "failed", "dead").
@@ -38322,7 +38429,9 @@ function buildAddColumnSql(adapter, table2, colName, def) {
   return sql;
 }
 function mt(db) {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+  if (engine === "firebird") return MIGRATION_TABLE;
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 function deriveDescription(name) {
   return name.replace(/^\d+_/, "").replace(/_/g, " ");
@@ -38345,9 +38454,9 @@ async function ensureMigrationTableOn(db) {
         id INTEGER NOT NULL PRIMARY KEY,
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
-        batch INTEGER NOT NULL DEFAULT 1,
+        batch INTEGER DEFAULT 1 NOT NULL,
         executed_at VARCHAR(50) NOT NULL,
-        passed INTEGER NOT NULL DEFAULT 1
+        passed INTEGER DEFAULT 1 NOT NULL
       )`);
     } else {
       const idCol = migrationIdColumn(db);
@@ -38444,7 +38553,7 @@ async function recordApplied(db, name, batch, passed = 1) {
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE"
     );
     insertCols.unshift("id");
-    values.unshift(rows[0]?.NEXT_ID ?? 1);
+    values.unshift(rows[0]?.next_id ?? 1);
   }
   const placeholders = insertCols.map(() => "?").join(", ");
   await adapterExecute(
@@ -40858,15 +40967,25 @@ var init_baseModel = __esm({
       /**
        * Invalidate every cached query that touches this model's table.
        *
-       * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-       * this table is busted too (it carries this table's tag), while a query that
-       * never touches this table is left intact. Called after every ORM write
-       * (save/delete/forceDelete/restore) so a read-after-write never serves a
-       * stale/deleted row (CACHE-DEC-01).
+       * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+       * this table is busted too because it carries this table's tag; a query
+       * that never touches this table is left intact), then cascaded to the
+       * DB layer on this model's bound connection so an out-of-band write /
+       * deliberate refresh / race-with-another-process cannot leave stale rows
+       * in db.fetch()'s persistent cache. Called after every ORM write
+       * (save/delete/forceDelete/restore) so a read-after-write never serves
+       * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+       * DB-layer cascade -- previously the two cache layers disagreed under
+       * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
        */
       static clearCache() {
         const ModelClass = this;
         modelQueryCache.clearTag((ModelClass.tableName ?? "").toLowerCase());
+        try {
+          const db = ModelClass.getDb();
+          if (typeof db?.cacheClear === "function") db.cacheClear();
+        } catch {
+        }
       }
       /**
        * Execute a raw SQL SELECT and return results as model instances.

package/packages/orm/src/baseModel.ts

@@ -1385,15 +1385,28 @@ export class BaseModel {
   /**
    * Invalidate every cached query that touches this model's table.
    *
-   * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-   * this table is busted too (it carries this table's tag), while a query that
-   * never touches this table is left intact. Called after every ORM write
-   * (save/delete/forceDelete/restore) so a read-after-write never serves a
-   * stale/deleted row (CACHE-DEC-01).
+   * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+   * this table is busted too because it carries this table's tag; a query
+   * that never touches this table is left intact), then cascaded to the
+   * DB layer on this model's bound connection so an out-of-band write /
+   * deliberate refresh / race-with-another-process cannot leave stale rows
+   * in db.fetch()'s persistent cache. Called after every ORM write
+   * (save/delete/forceDelete/restore) so a read-after-write never serves
+   * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+   * DB-layer cascade -- previously the two cache layers disagreed under
+   * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
    */
   static clearCache(): void {
     const ModelClass = this as unknown as typeof BaseModel;
     modelQueryCache.clearTag((ModelClass.tableName ?? "").toLowerCase());
+    try {
+      const db: any = ModelClass.getDb();
+      if (typeof db?.cacheClear === "function") db.cacheClear();
+    } catch {
+      // A resolvable DB is not guaranteed at every clearCache() call site
+      // (module-import time in odd bootstraps, tests that mutate bindings);
+      // never let a cache-clear crash a save/delete.
+    }
   }
 
   /**