tina4-nodejs 3.13.104 → 3.13.108

package/packages/orm/dist/index.js

@@ -8337,6 +8337,31 @@ var init_router = __esm({
         this.route.noAuth = true;
         return this;
       }
+      /**
+       * RBAC: require ONE of the named roles (OR). Reads the verified JWT `roles`
+       * claim. Chain .role()/.can() for AND. Implies auth. Feature 138 / ADR-0058.
+       */
+      role(...names) {
+        const clean = names.filter((n) => n !== "");
+        if (clean.length > 0) {
+          (this.route.requiredRoles ??= []).push(clean);
+          this.route.secure = true;
+        }
+        return this;
+      }
+      /**
+       * RBAC: require ONE of the named permissions (OR). Reads the verified JWT
+       * `permissions` claim; granted-side wildcards (`posts.*`, `*`) satisfy a
+       * concrete requirement. Chain for AND. Implies auth. Feature 138.
+       */
+      can(...permissions) {
+        const clean = permissions.filter((p) => p !== "");
+        if (clean.length > 0) {
+          (this.route.requiredPerms ??= []).push(clean);
+          this.route.secure = true;
+        }
+        return this;
+      }
       /** Mark this route's response as cacheable. */
       cache() {
         this.route.cached = true;
@@ -8404,7 +8429,9 @@ var init_router = __esm({
           secure: secureDefault,
           cached: definition.cached,
           noAuth: definition.noAuth,
-          template: definition.template
+          template: definition.template,
+          requiredRoles: definition.requiredRoles,
+          requiredPerms: definition.requiredPerms
         };
         routes.push(compiled);
         return new RouteRef(compiled);
@@ -8551,7 +8578,9 @@ var init_router = __esm({
               template: route.template,
               secure: route.secure,
               cached: route.cached,
-              noAuth: route.noAuth
+              noAuth: route.noAuth,
+              requiredRoles: route.requiredRoles,
+              requiredPerms: route.requiredPerms
             };
           }
         }
@@ -8574,7 +8603,9 @@ var init_router = __esm({
               template: route.template,
               secure: route.secure,
               cached: route.cached,
-              noAuth: route.noAuth
+              noAuth: route.noAuth,
+              requiredRoles: route.requiredRoles,
+              requiredPerms: route.requiredPerms
             });
           }
         }
@@ -8936,7 +8967,7 @@ function enforceRouteAuth(req2, res, match, isDevAdmin) {
     const identity = sso?.identity;
     if (identity?.issuer && identity?.subject) {
       req2.user = identity;
-      return false;
+      return rbacForbidden(match, identity, res);
     }
     const sessionToken = req2.session?.get?.("token");
     if (sessionToken && validToken(sessionToken)) {
@@ -8956,8 +8987,45 @@ function enforceRouteAuth(req2, res, match, isDevAdmin) {
       res.header("FreshToken", fresh);
     }
   }
+  return rbacForbidden(match, req2.user, res);
+}
+function rbacClaimList(subject, key, legacy) {
+  const coerce = (v) => {
+    if (typeof v === "string") return v === "" ? [] : [v];
+    if (Array.isArray(v)) return v.map((x) => String(x)).filter((x) => x !== "");
+    return [];
+  };
+  let out = coerce(subject[key]);
+  if (out.length === 0 && legacy) out = coerce(subject[legacy]);
+  return out;
+}
+function rbacPermGranted(granted, required) {
+  return granted.some(
+    (g) => g === "*" || g === required || g.endsWith(".*") && required.startsWith(g.slice(0, -1))
+  );
+}
+function rbacForbidden(match, payload, res) {
+  const requiredRoles = match.requiredRoles ?? [];
+  const requiredPerms = match.requiredPerms ?? [];
+  if (requiredRoles.length === 0 && requiredPerms.length === 0) {
+    return false;
+  }
+  const subject = payload && typeof payload === "object" ? payload : {};
+  const roles = rbacClaimList(subject, "roles", "role");
+  for (const group of requiredRoles) {
+    if (!group.some((r) => roles.includes(r))) return writeForbidden(res);
+  }
+  const perms = rbacClaimList(subject, "permissions");
+  for (const group of requiredPerms) {
+    if (!group.some((p) => rbacPermGranted(perms, p))) return writeForbidden(res);
+  }
   return false;
 }
+function writeForbidden(res) {
+  res.raw.writeHead(403, { "Content-Type": "application/json" });
+  res.raw.end(JSON.stringify({ error: "Forbidden" }));
+  return true;
+}
 var init_authGate = __esm({
   "../core/src/authGate.ts"() {
     "use strict";
@@ -17249,17 +17317,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 +17422,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 +17532,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 +18209,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 +18421,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 +18483,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 +18505,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 +18515,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 +18524,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").
@@ -24927,6 +25102,9 @@ function asHtmlString(chunk) {
   if (Buffer.isBuffer(chunk)) return chunk.toString("utf-8");
   return null;
 }
+function isInjectableHtml(res) {
+  return isHtmlResponse(res) && !res.raw.getHeader("content-encoding");
+}
 function injectIntoHtml(ctx, devToolbar, html) {
   if (!devToolbar) return injectFeedbackWidget(ctx.req, html);
   const toolbarCtx = {
@@ -24954,7 +25132,7 @@ function wrapResponseEnd(ctx) {
         Date.now() - ctx.reqStartTime
       );
     }
-    if (isHtmlResponse(res)) {
+    if (isInjectableHtml(res)) {
       const html = asHtmlString(chunk);
       if (html !== null) chunk = injectIntoHtml(ctx, devToolbar, html);
       if (!res.raw.headersSent) res.raw.removeHeader("content-length");
@@ -38322,7 +38500,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 +38525,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 +38624,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 +41038,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.
+    }
   }
 
   /**

package/packages/orm/src/migration.ts

@@ -297,7 +297,16 @@ const MIGRATION_TABLE = "tina4_migration";
  * sql_mode, so they are always correct there.
  */
 function mt(db: DatabaseAdapter): string {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+
+  // Firebird: leave it UNQUOTED so it folds to the upper-case TINA4_MIGRATION
+  // that the PHP and Python masters create. A quoted lower-case identifier is a
+  // DIFFERENT, case-sensitive table there, so a quoted spelling cannot see a
+  // ledger written by another Tina4 language — while tableExists() matches
+  // case-insensitively and reports it present, so the INSERT fails alone.
+  if (engine === "firebird") return MIGRATION_TABLE;
+
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 
 /**
@@ -347,9 +356,9 @@ async function ensureMigrationTableOn(db: DatabaseAdapter): Promise<void> {
         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 {
       // Engine-aware bookkeeping DDL (non-Firebird). Each engine spells an
@@ -517,11 +526,11 @@ async function recordApplied(
 
   if (isFirebirdAdapter(db)) {
     // Firebird: generate the id from the sequence.
-    const rows = await adapterQuery<{ NEXT_ID: number }>(db,
+    const rows = await adapterQuery<{ next_id: number }>(db,
       "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(", ");

package/types/core/src/authGate.d.ts

@@ -3,6 +3,9 @@ import type { Tina4Request, Tina4Response } from "./types.js";
 export interface AuthGateRoute {
     secure?: boolean;
     noAuth?: boolean;
+    /** RBAC guard groups (Feature 138): OR within a group, AND across groups. */
+    requiredRoles?: string[][];
+    requiredPerms?: string[][];
 }
 /**
  * Enforce auth for a matched route.

package/types/core/src/queue.d.ts

@@ -74,7 +74,13 @@ export interface QueueBackendInterface {
     close(): void;
     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;
@@ -137,7 +143,19 @@ export declare class Queue {
      */
     process(handler: (job: QueueJob | QueueJob[]) => Promise<void> | void, options?: ProcessOptions): void;
     /**
-     * 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): number;
     /**
@@ -172,7 +190,11 @@ export declare 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[];
     /**
@@ -184,7 +206,22 @@ export declare class Queue {
      */
     retry(jobId?: string, delaySeconds?: number): boolean;
     /**
-     * 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[];
     /**

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -122,7 +122,13 @@ export declare 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;
 }

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -87,8 +87,13 @@ export declare class MongoBackend implements QueueBackend {
      * retries remain, else dead-letter. Mirrors the file/lite backend.
      */
     fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff?: number): void;
-    /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
-    retry(queue: string, id: string, delaySeconds?: number): void;
+    /**
+     * 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): boolean;
     /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
     deadLetters(queue: string, maxRetries?: number): QueueJob[];
     /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */