tina4-nodejs 3.13.104 → 3.13.105

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.104)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.105)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.104 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.105 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -309,6 +309,20 @@ queue.consume(topic?, id?, pollInterval=1000): AsyncGenerator<QueueJob>
 // Usage: for await (const job of queue.consume("emails")) { ... }
 ```
 
+**size / failed / deadLetters — three surfaces, one distinction (3.13.105 parity).**
+- `queue.size(status)` — `"pending"` counts jobs waiting to be popped AND retryable-
+  but-attempted ones (they live in the pending queue under the auto-retry lifecycle).
+  `"reserved"` counts in-flight jobs against the visibility timeout. `"completed"`
+  counts finished jobs. `"failed"` / `"dead"` / `"dead_letter"` are ALIASES — all
+  three count the dead-letter store (== `queue.deadLetters().length`).
+- `queue.failed()` — retryable-but-attempted jobs (0 < attempts < maxRetries) that
+  live in the pending queue and are still being auto-retried. They are counted under
+  `size("pending")`, NOT `size("failed")`. Use this to LIST them; use
+  `size("pending")` to include them in a total.
+- `queue.deadLetters()` — terminal failures (attempts >= maxRetries). Same set that
+  `size("failed")` / `size("dead")` / `size("dead_letter")` count. Returns wrapped
+  `Job` objects so callers can iterate uniformly and call `.retry()` on each.
+
 ### @tina4/swagger (`packages/swagger/`)
 Auto-generates OpenAPI 3.0.3 docs.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.104",
+  "version": "3.13.105",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -12352,7 +12352,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, " ");
@@ -12375,9 +12377,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);
@@ -12474,7 +12476,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(
@@ -14888,15 +14890,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.
@@ -28115,17 +28127,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();
@@ -28170,10 +28232,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));
           }
@@ -28270,9 +28342,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) {
@@ -28941,10 +29019,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 {
+          unlinkSync7(join23(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);
@@ -29143,7 +29231,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;
@@ -29193,13 +29293,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.
@@ -29211,8 +29315,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);
         }
@@ -29221,8 +29325,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;
           }
@@ -29230,13 +29334,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").

package/packages/core/dist/index.js

@@ -12351,7 +12351,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, " ");
@@ -12374,9 +12376,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);
@@ -12473,7 +12475,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(
@@ -14887,15 +14889,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.
@@ -28094,17 +28106,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();
@@ -28149,10 +28211,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));
           }
@@ -28249,9 +28321,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) {
@@ -28920,10 +28998,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 {
+          unlinkSync7(join22(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);
@@ -29122,7 +29210,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;
@@ -29172,13 +29272,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.
@@ -29190,8 +29294,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);
         }
@@ -29200,8 +29304,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;
           }
@@ -29209,13 +29313,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").