@focus-reactive/payload-plugin-translator 0.2.1 → 0.4.0

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.d.ts

@@ -15,80 +15,75 @@ export declare class PayloadJobsTaskRunner implements TaskRunner {
     cancel(taskIds: string[]): Promise<void>;
     run(taskId: string): Promise<RunResult>;
     /**
-     * Find translation jobs for a collection, optionally narrowed by document IDs.
+     * Reset stale processing locks so abandoned jobs become eligible for the
+     * autorun picker again. The picker requires processing:false, no error, and
+     * no pending waitUntil; a job abandoned mid-run (no error, no waitUntil)
+     * satisfies the rest, so clearing processing is sufficient for that case.
+     * A job that already exhausted retries (hasError:true) stays excluded from
+     * autorun and is only recoverable via a manual run().
      *
-     * IMPORTANT — why we filter `collection.value` in memory instead of in WHERE
-     * ------------------------------------------------------------------------
-     * The "natural" implementation would be a single `payload.find` with the
-     * full where clause:
+     * A job is stale when it is still `processing: true`, not yet completed, and
+     * its `updatedAt` is older than `staleJobTimeoutMs` — i.e. a process was
+     * killed mid-run (deploy/crash/timeout). Threshold-based, so a job genuinely
+     * in flight on another live instance (fresh `updatedAt`) is left alone.
+     * Filters on real `payload-jobs` columns only (no JSON-path traversal), so
+     * the drizzle SQLite issue in `findByCollection` does not apply here.
+     * @returns the number of jobs reclaimed.
+     */
+    reclaimStaleJobs(): Promise<number>;
+    /**
+     * Clear the `processing` lock on every job matching `where`, returning how
+     * many were reset. Shared by the per-job reset in `run()` (a stale lock) and
+     * the bulk boot/recovery reset in `reclaimStaleJobs()`. `depth: 0` because
+     * only the count is needed — no relationships to populate.
+     */
+    private resetProcessing;
+    /**
+     * A processing lock is stale once `updatedAt` is older than the configured
+     * timeout — the owning run is presumed dead.
+     */
+    private isStale;
+    /**
+     * Find translation jobs for a collection, optionally narrowed by document IDs.
      *
-     *     where: {
-     *       and: [
-     *         { 'input.collection.relationTo': { equals: collectionSlug } },
-     *         { 'input.collection.value':      { in: documentIds } },
-     *       ],
-     *     }
+     * Narrowing is by `taskSlug` only in SQL; the collection slug and document
+     * IDs are matched in memory (via the normalized `Task`, which reads both the
+     * current flat-text shape and the legacy relationship shape). This is the
+     * one path that must transparently span both stored shapes during the
+     * ID-agnostic migration — see docs/DEPRECATIONS.md#jobs-input-collection-field.
      *
-     * This DOES NOT work on SQLite (and is unreliable on any adapter) because
-     * of two compounding bugs in Payload's drizzle layer.
+     * IMPORTANT — why slug/id are matched in memory, not in the SQL WHERE
+     * ------------------------------------------------------------------------
+     * The "natural" implementation would push `input.collection_id` into the
+     * where clause. This DOES NOT work on SQLite (and is unreliable on any
+     * adapter) because of two compounding bugs in Payload's drizzle layer.
      *
      * 1. The `input` field on `payload-jobs` is declared `type: 'json'`. The
      *    drizzle path resolver (`@payloadcms/drizzle/queries/getTableColumnFromPath`)
      *    has no `case 'json'` branch, so the value is left as a raw column and
      *    the path segments are passed through to `parseParams.js`, which on
      *    SQLite builds raw SQL using `convertPathToJSONTraversal` — generating
-     *    expressions like `input->>'collection'->>'value'`.
+     *    expressions like `input->>'collection_id'`.
      *
      * 2. When `parseParams.js` formats the right-hand side of `in`/`not_in`
      *    (and even `equals` when `!isNaN(val)`), it inlines values via JS
      *    template literals WITHOUT wrapping strings in quotes. The string
      *    `'1'` from our WHERE becomes raw `1` in the SQL. Drizzle therefore
-     *    emits queries like:
-     *
-     *        WHERE input->>'collection'->>'value' IN (1)
-     *
-     *    even though the caller passed `['1']` (an array of strings).
-     *
-     * On SQLite, `->>` preserves the JSON value's type — if the stored JSON
-     * has `"value": "1"` (a JSON string), `->>` returns SQLite TEXT `'1'`;
-     * if the JSON has `"value": 1` (a JSON number), `->>` returns INTEGER `1`.
-     * SQLite's `IN (...)` does NOT coerce between TEXT and INTEGER. So:
+     *    emits queries like `WHERE input->>'collection_id' IN (1)` even though
+     *    the caller passed `['1']` (an array of strings).
      *
-     *     TEXT '1'    IN (1)    → false   (text vs integer, no match)
-     *     INTEGER 1   IN ('1')  → false   (integer vs text, no match)
-     *
-     * Combined with bug #2 above, any value passed by the caller — even if
-     * we normalize it to a string on write — gets re-coerced to a number in
-     * the generated SQL and never matches the stored JSON.
-     *
-     * Postgres avoids most of this because `jsonb_path_query` returns text
-     * uniformly and PG's type coercion is more permissive, but the same
-     * un-quoted-string bug technically affects it too.
-     *
-     * Why we don't fix it upstream / patch the dep
-     * --------------------------------------------
-     * - This plugin is published to npm. Consumers install it with their own
-     *   Payload version and would not receive any local `bun patch` /
-     *   `patch-package` overrides on `@payloadcms/drizzle`. The plugin must
-     *   work against vanilla Payload.
-     * - A PR to Payload core is the proper long-term fix, but the plugin
-     *   cannot block on its merge/release cycle.
-     * - Forcing a non-numeric prefix on the stored ID (e.g., `"id:1"`) would
-     *   work around bug #2, but bloats the data shape and breaks anything
-     *   that reads `input.collection.value` expecting a plain id.
+     * On SQLite, `->>` preserves the JSON value's type and `IN (...)` does NOT
+     * coerce between TEXT and INTEGER, so a numeric-looking string id never
+     * matches once bug #2 strips its quotes. Storing the id as text (this
+     * migration) does not fix the SQL path — drizzle re-numbers it anyway — so
+     * we keep matching in memory.
      *
      * Why in-memory filtering is acceptable here
      * ------------------------------------------
-     * We narrow the SQL query to `taskSlug + relationTo` (both string
-     * equality, which Payload quotes correctly), then filter the result set
-     * by `collection.value` in JavaScript. Per-collection job sets are
-     * small (typically <100 rows; the plugin actively cancels superseded
-     * jobs so they don't accumulate), so a Set-membership check in JS is
-     * effectively free.
-     *
-     * If/when the upstream drizzle bug is fixed (or this plugin gains a
-     * mirror collection with indexed flat columns), this method can collapse
-     * back to a single SQL query.
+     * Per-task job sets are small (typically <100 rows; the plugin actively
+     * cancels superseded jobs so they don't accumulate), so the JS filtering
+     * is effectively free. If/when the upstream drizzle bug is fixed, this can
+     * collapse back to a single SQL query.
      */
     findByCollection(collectionSlug: CollectionSlug, documentIds?: Array<string | number>): Promise<Task[]>;
     /**

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.js

@@ -13,7 +13,7 @@ import { normalizeJob } from "./normalizeJob";
     async enqueue(tasks) {
         const byCollection = this.groupByCollection(tasks);
         for (const [collectionSlug, items] of byCollection){
-            const documentIds = items.map((t)=>String(t.collectionId));
+            const documentIds = items.map((t)=>t.collectionId);
             const existing = await this.findByCollection(collectionSlug, documentIds);
             if (existing.length > 0) {
                 await this.cancelInternal(existing.map((t)=>t.id));
@@ -23,19 +23,13 @@ import { normalizeJob } from "./normalizeJob";
                 task: this.config.taskName,
                 queue: this.config.queueName,
                 input: {
-                    collection: {
-                        // Pass `value` through verbatim. The Payload Jobs `input` schema
-                        // declares this as a `relationship` field, which validates the
-                        // value's type against the target collection's ID type (number
-                        // for autoincrement, string for uuid). Coercing to string here
-                        // would silently fail validation for number-id collections and
-                        // leave jobs stuck in processing without ever invoking the
-                        // task handler. `findByCollection` reads back via in-memory
-                        // filtering and normalizes both sides with String(...) for the
-                        // comparison, so it does not need write-side normalization.
-                        relationTo: task.collectionSlug,
-                        value: task.collectionId
-                    },
+                    // Flat text reference (ID-agnostic). Stored as a string — no
+                    // relationship type validation against the collection's ID type,
+                    // which is what previously left number-id jobs stuck in processing.
+                    // This is the single write boundary, so `String(...)` here is the
+                    // one place IDs are normalized for storage.
+                    collection_slug: task.collectionSlug,
+                    collection_id: String(task.collectionId),
                     source_lng: task.sourceLng,
                     target_lng: task.targetLng,
                     strategy: task.strategy,
@@ -69,104 +63,164 @@ import { normalizeJob } from "./normalizeJob";
             };
         }
         if (task.status === "running") {
-            return {
-                success: false,
-                error: "already_running"
-            };
+            // A genuinely in-flight job is refused. A stale processing lock (left by
+            // a process killed mid-run) is reclaimable: clear it first so the queue
+            // picker below — which only selects `processing: false` — can re-run it.
+            if (!this.isStale(task.updatedAt)) {
+                return {
+                    success: false,
+                    error: "already_running"
+                };
+            }
+            await this.resetProcessing({
+                id: {
+                    equals: taskId
+                }
+            });
         }
-        this.payload.jobs.runByID({
-            id: taskId
+        // Execute synchronously via the queue + `where` picker so the job runs to
+        // completion within this request (nothing is abandoned after the HTTP
+        // response — reliable on serverless too).
+        //
+        // NOT `payload.jobs.runByID({ id })`: on the drizzle adapter the id-path
+        // (`db.updateJobs({ id })`) writes `processing: true` but returns no rows,
+        // so `runJobs` reports `noJobsRemaining` and the handler never runs —
+        // leaving the job stuck at `processing: true` forever. The `where`-based
+        // picker selects, runs, and finalizes the job correctly (verified against
+        // sqlite). The picker also enforces processing:false / no-error / no
+        // pending waitUntil, so a failed (max-retries) job is not re-run here.
+        await this.payload.jobs.run({
+            queue: this.config.queueName,
+            where: {
+                id: {
+                    equals: taskId
+                }
+            },
+            limit: 1
         });
         return {
             success: true
         };
     }
     /**
-   * Find translation jobs for a collection, optionally narrowed by document IDs.
+   * Reset stale processing locks so abandoned jobs become eligible for the
+   * autorun picker again. The picker requires processing:false, no error, and
+   * no pending waitUntil; a job abandoned mid-run (no error, no waitUntil)
+   * satisfies the rest, so clearing processing is sufficient for that case.
+   * A job that already exhausted retries (hasError:true) stays excluded from
+   * autorun and is only recoverable via a manual run().
    *
-   * IMPORTANT — why we filter `collection.value` in memory instead of in WHERE
-   * ------------------------------------------------------------------------
-   * The "natural" implementation would be a single `payload.find` with the
-   * full where clause:
+   * A job is stale when it is still `processing: true`, not yet completed, and
+   * its `updatedAt` is older than `staleJobTimeoutMs` — i.e. a process was
+   * killed mid-run (deploy/crash/timeout). Threshold-based, so a job genuinely
+   * in flight on another live instance (fresh `updatedAt`) is left alone.
+   * Filters on real `payload-jobs` columns only (no JSON-path traversal), so
+   * the drizzle SQLite issue in `findByCollection` does not apply here.
+   * @returns the number of jobs reclaimed.
+   */ async reclaimStaleJobs() {
+        const cutoff = new Date(Date.now() - this.config.staleJobTimeoutMs).toISOString();
+        return this.resetProcessing({
+            and: [
+                {
+                    taskSlug: {
+                        equals: this.config.taskName
+                    }
+                },
+                {
+                    processing: {
+                        equals: true
+                    }
+                },
+                {
+                    completedAt: {
+                        exists: false
+                    }
+                },
+                {
+                    updatedAt: {
+                        less_than: cutoff
+                    }
+                }
+            ]
+        });
+    }
+    /**
+   * Clear the `processing` lock on every job matching `where`, returning how
+   * many were reset. Shared by the per-job reset in `run()` (a stale lock) and
+   * the bulk boot/recovery reset in `reclaimStaleJobs()`. `depth: 0` because
+   * only the count is needed — no relationships to populate.
+   */ async resetProcessing(where) {
+        const result = await this.payload.update({
+            collection: this.config.jobsCollection,
+            depth: 0,
+            where,
+            data: {
+                processing: false
+            }
+        });
+        return result.docs.length;
+    }
+    /**
+   * A processing lock is stale once `updatedAt` is older than the configured
+   * timeout — the owning run is presumed dead.
+   */ isStale(updatedAt) {
+        const parsed = Date.parse(updatedAt);
+        // Unknown/corrupt timestamp → treat as stale so the job can be recovered
+        // rather than permanently refused as already-running.
+        if (Number.isNaN(parsed)) return true;
+        return Date.now() - parsed > this.config.staleJobTimeoutMs;
+    }
+    /**
+   * Find translation jobs for a collection, optionally narrowed by document IDs.
    *
-   *     where: {
-   *       and: [
-   *         { 'input.collection.relationTo': { equals: collectionSlug } },
-   *         { 'input.collection.value':      { in: documentIds } },
-   *       ],
-   *     }
+   * Narrowing is by `taskSlug` only in SQL; the collection slug and document
+   * IDs are matched in memory (via the normalized `Task`, which reads both the
+   * current flat-text shape and the legacy relationship shape). This is the
+   * one path that must transparently span both stored shapes during the
+   * ID-agnostic migration — see docs/DEPRECATIONS.md#jobs-input-collection-field.
    *
-   * This DOES NOT work on SQLite (and is unreliable on any adapter) because
-   * of two compounding bugs in Payload's drizzle layer.
+   * IMPORTANT — why slug/id are matched in memory, not in the SQL WHERE
+   * ------------------------------------------------------------------------
+   * The "natural" implementation would push `input.collection_id` into the
+   * where clause. This DOES NOT work on SQLite (and is unreliable on any
+   * adapter) because of two compounding bugs in Payload's drizzle layer.
    *
    * 1. The `input` field on `payload-jobs` is declared `type: 'json'`. The
    *    drizzle path resolver (`@payloadcms/drizzle/queries/getTableColumnFromPath`)
    *    has no `case 'json'` branch, so the value is left as a raw column and
    *    the path segments are passed through to `parseParams.js`, which on
    *    SQLite builds raw SQL using `convertPathToJSONTraversal` — generating
-   *    expressions like `input->>'collection'->>'value'`.
+   *    expressions like `input->>'collection_id'`.
    *
    * 2. When `parseParams.js` formats the right-hand side of `in`/`not_in`
    *    (and even `equals` when `!isNaN(val)`), it inlines values via JS
    *    template literals WITHOUT wrapping strings in quotes. The string
    *    `'1'` from our WHERE becomes raw `1` in the SQL. Drizzle therefore
-   *    emits queries like:
-   *
-   *        WHERE input->>'collection'->>'value' IN (1)
-   *
-   *    even though the caller passed `['1']` (an array of strings).
-   *
-   * On SQLite, `->>` preserves the JSON value's type — if the stored JSON
-   * has `"value": "1"` (a JSON string), `->>` returns SQLite TEXT `'1'`;
-   * if the JSON has `"value": 1` (a JSON number), `->>` returns INTEGER `1`.
-   * SQLite's `IN (...)` does NOT coerce between TEXT and INTEGER. So:
+   *    emits queries like `WHERE input->>'collection_id' IN (1)` even though
+   *    the caller passed `['1']` (an array of strings).
    *
-   *     TEXT '1'    IN (1)    → false   (text vs integer, no match)
-   *     INTEGER 1   IN ('1')  → false   (integer vs text, no match)
-   *
-   * Combined with bug #2 above, any value passed by the caller — even if
-   * we normalize it to a string on write — gets re-coerced to a number in
-   * the generated SQL and never matches the stored JSON.
-   *
-   * Postgres avoids most of this because `jsonb_path_query` returns text
-   * uniformly and PG's type coercion is more permissive, but the same
-   * un-quoted-string bug technically affects it too.
-   *
-   * Why we don't fix it upstream / patch the dep
-   * --------------------------------------------
-   * - This plugin is published to npm. Consumers install it with their own
-   *   Payload version and would not receive any local `bun patch` /
-   *   `patch-package` overrides on `@payloadcms/drizzle`. The plugin must
-   *   work against vanilla Payload.
-   * - A PR to Payload core is the proper long-term fix, but the plugin
-   *   cannot block on its merge/release cycle.
-   * - Forcing a non-numeric prefix on the stored ID (e.g., `"id:1"`) would
-   *   work around bug #2, but bloats the data shape and breaks anything
-   *   that reads `input.collection.value` expecting a plain id.
+   * On SQLite, `->>` preserves the JSON value's type and `IN (...)` does NOT
+   * coerce between TEXT and INTEGER, so a numeric-looking string id never
+   * matches once bug #2 strips its quotes. Storing the id as text (this
+   * migration) does not fix the SQL path — drizzle re-numbers it anyway — so
+   * we keep matching in memory.
    *
    * Why in-memory filtering is acceptable here
    * ------------------------------------------
-   * We narrow the SQL query to `taskSlug + relationTo` (both string
-   * equality, which Payload quotes correctly), then filter the result set
-   * by `collection.value` in JavaScript. Per-collection job sets are
-   * small (typically <100 rows; the plugin actively cancels superseded
-   * jobs so they don't accumulate), so a Set-membership check in JS is
-   * effectively free.
-   *
-   * If/when the upstream drizzle bug is fixed (or this plugin gains a
-   * mirror collection with indexed flat columns), this method can collapse
-   * back to a single SQL query.
+   * Per-task job sets are small (typically <100 rows; the plugin actively
+   * cancels superseded jobs so they don't accumulate), so the JS filtering
+   * is effectively free. If/when the upstream drizzle bug is fixed, this can
+   * collapse back to a single SQL query.
    */ async findByCollection(collectionSlug, documentIds) {
-        const tasks = await this.findJobsInternal({
-            "input.collection.relationTo": {
-                equals: collectionSlug
-            }
-        }, {
+        const all = await this.findJobsInternal(undefined, {
             pagination: false
         });
-        if (!documentIds?.length) return tasks;
+        const bySlug = all.filter((t)=>t.input.collectionSlug === collectionSlug);
+        if (!documentIds?.length) return bySlug;
+        // `documentIds` is the public `Array<string | number>` param, so normalize
+        // it here; `t.input.collectionId` is already `ID` (string) via normalizeJob.
         const wanted = new Set(documentIds.map(String));
-        return tasks.filter((t)=>wanted.has(String(t.input.collectionId)));
+        return bySlug.filter((t)=>wanted.has(t.input.collectionId));
     }
     /**
    * Group tasks by collection slug
@@ -203,19 +257,20 @@ import { normalizeJob } from "./normalizeJob";
     /**
    * Internal method to find jobs with where clause
    */ async findJobsInternal(where, params) {
+        const and = [
+            {
+                taskSlug: {
+                    equals: this.config.taskName
+                }
+            }
+        ];
+        if (where) and.push(where);
         const response = await this.payload.find({
             collection: this.config.jobsCollection,
             limit: params?.limit,
             pagination: params?.pagination,
             where: {
-                and: [
-                    {
-                        taskSlug: {
-                            equals: this.config.taskName
-                        }
-                    },
-                    where
-                ]
+                and
             }
         });
         return response.docs.map(normalizeJob);

package/dist/server/modules/task-runner/payload-jobs-runner/normalizeJob.d.ts

@@ -1,5 +1,5 @@
-import type { Task } from '../types';
-import type { PayloadJob } from './types';
+import type { Task } from "../types";
+import type { PayloadJob } from "./types";
 /**
  * Transform Payload job to normalized Task
  */

package/dist/server/modules/task-runner/payload-jobs-runner/normalizeJob.js

@@ -1,15 +1,17 @@
+import { readCollectionRef } from "./readCollectionRef";
 /**
  * Transform Payload job to normalized Task
  */ export function normalizeJob(job) {
+    const { collectionSlug, collectionId } = readCollectionRef(job.input);
     return {
         id: job.id,
         status: getJobStatus(job),
         input: {
-            collectionSlug: job.input?.collection?.relationTo ?? '',
-            collectionId: job.input?.collection?.value ?? '',
-            sourceLng: job.input?.source_lng ?? '',
-            targetLng: job.input?.target_lng ?? '',
-            strategy: job.input?.strategy ?? 'overwrite',
+            collectionSlug,
+            collectionId,
+            sourceLng: job.input?.source_lng ?? "",
+            targetLng: job.input?.target_lng ?? "",
+            strategy: job.input?.strategy ?? "overwrite",
             publishOnTranslation: job.input?.publish_on_translation ?? false
         },
         createdAt: job.createdAt,
@@ -22,19 +24,19 @@
     };
 }
 function getJobStatus(job) {
-    if (job.completedAt) return 'completed';
-    if (job.processing) return 'running';
-    if (job.error) return 'failed';
-    return 'pending';
+    if (job.completedAt) return "completed";
+    if (job.processing) return "running";
+    if (job.error) return "failed";
+    return "pending";
 }
 function extractErrorMessage(error) {
-    if (error && typeof error === 'object' && 'message' in error && typeof error.message === 'string') {
+    if (error && typeof error === "object" && "message" in error && typeof error.message === "string") {
         return error.message;
     }
-    return 'Unknown error';
+    return "Unknown error";
 }
 function isCancelled(error) {
-    return error !== null && typeof error === 'object' && 'cancelled' in error && typeof error.cancelled === 'boolean' && error.cancelled;
+    return error !== null && typeof error === "object" && "cancelled" in error && typeof error.cancelled === "boolean" && error.cancelled;
 }
 
 //# sourceMappingURL=normalizeJob.js.map

package/dist/server/modules/task-runner/payload-jobs-runner/readCollectionRef.d.ts

@@ -0,0 +1,22 @@
+import type { CollectionSlug } from "payload";
+import type { ID } from "../types";
+import type { PayloadJob } from "./types";
+/**
+ * Normalized, ID-agnostic document reference parsed out of a stored job input.
+ */
+export type CollectionRef = {
+    collectionSlug: CollectionSlug;
+    collectionId: ID;
+};
+/**
+ * Single storage-read boundary for a job's collection reference.
+ *
+ * Reads the current flat-text shape (`collection_slug` / `collection_id`) and
+ * falls back to the legacy relationship shape (`collection.{relationTo,value}`)
+ * for jobs queued before the ID-agnostic migration. This is the one place a
+ * stored id is coerced to string — the coercion exists only because the legacy
+ * relationship `value` is typed `string | number`, and it goes away together
+ * with the legacy field in the next major.
+ * See docs/DEPRECATIONS.md#jobs-input-collection-field
+ */
+export declare function readCollectionRef(input: PayloadJob["input"]): CollectionRef;

package/dist/server/modules/task-runner/payload-jobs-runner/readCollectionRef.js

@@ -0,0 +1,22 @@
+/**
+ * Single storage-read boundary for a job's collection reference.
+ *
+ * Reads the current flat-text shape (`collection_slug` / `collection_id`) and
+ * falls back to the legacy relationship shape (`collection.{relationTo,value}`)
+ * for jobs queued before the ID-agnostic migration. This is the one place a
+ * stored id is coerced to string — the coercion exists only because the legacy
+ * relationship `value` is typed `string | number`, and it goes away together
+ * with the legacy field in the next major.
+ * See docs/DEPRECATIONS.md#jobs-input-collection-field
+ */ export function readCollectionRef(input) {
+    // `??` is intentional: `collection_slug` / `collection_id` are `required: true`
+    // in the inputSchema, so they are never an empty string for any job this plugin
+    // writes. The fallback to the legacy shape therefore only fires when the new
+    // field is genuinely absent (i.e. a job queued before the ID-agnostic migration).
+    return {
+        collectionSlug: input?.collection_slug ?? input?.collection?.relationTo ?? "",
+        collectionId: String(input?.collection_id ?? input?.collection?.value ?? "")
+    };
+}
+
+//# sourceMappingURL=readCollectionRef.js.map

package/dist/server/modules/task-runner/payload-jobs-runner/types.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionSlug } from 'payload';
+import type { CollectionSlug } from "payload";
 /**
  * Configuration for automatic job processing.
  */
@@ -32,7 +32,7 @@ export type PayloadJobsRunnerOptions = {
      * Name of the Payload jobs collection.
      * @default 'payload-jobs'
      */
-    jobsCollection?: string;
+    jobsCollection?: CollectionSlug;
     /**
      * Automatic job processing configuration.
      * Set to `false` to disable (for Vercel/serverless deployments).
@@ -40,6 +40,22 @@ export type PayloadJobsRunnerOptions = {
      * @default { cron: '* * * * *', limit: 50 }
      */
     autoRun?: false | AutoRunConfig;
+    /**
+     * How long (ms) a job may stay `processing: true` before its lock is
+     * considered stale and the job becomes eligible to be re-run.
+     *
+     * A process killed mid-run (deploy, crash, request timeout) leaves a job
+     * stuck at `processing: true`; the autorun picker only takes
+     * `processing: false`, so without recovery such a job would hang forever.
+     * On boot the runner resets stale locks, and manual `run()` will re-claim a
+     * stale-locked job instead of refusing it as already-running.
+     *
+     * MUST be larger than the longest a single document translation can
+     * legitimately take, otherwise a genuinely in-flight job could be reclaimed
+     * and run twice (safe under the idempotent `overwrite` strategy, but wasteful).
+     * @default 300000 (5 minutes)
+     */
+    staleJobTimeoutMs?: number;
     /**
      * Retry configuration for failed jobs.
      */
@@ -47,7 +63,7 @@ export type PayloadJobsRunnerOptions = {
         attempts?: number;
         backoff?: {
             delay?: number;
-            type: 'exponential' | 'fixed';
+            type: "exponential" | "fixed";
         };
     };
 };
@@ -57,9 +73,10 @@ export type PayloadJobsRunnerOptions = {
 export type PayloadJobsRunnerConfig = {
     taskName: string;
     queueName: string;
-    jobsCollection: string;
+    jobsCollection: CollectionSlug;
     autoRun: false | Required<AutoRunConfig>;
-    retries?: PayloadJobsRunnerOptions['retries'];
+    staleJobTimeoutMs: number;
+    retries?: PayloadJobsRunnerOptions["retries"];
 };
 /**
  * Raw Payload job structure
@@ -72,6 +89,14 @@ export type PayloadJob = {
     error?: unknown;
     processing?: boolean | null;
     input?: {
+        /** Document reference (flat text, ID-agnostic). Current shape. */
+        collection_slug?: string;
+        collection_id?: string;
+        /**
+         * @deprecated Legacy relationship shape, read-only fallback for jobs queued
+         * before the ID-agnostic migration. Removed in next major.
+         * See docs/DEPRECATIONS.md#jobs-input-collection-field
+         */
         collection?: {
             relationTo: CollectionSlug;
             value: string | number;

package/dist/server/modules/task-runner/sync-runner/SyncTaskRunner.d.ts

@@ -1,8 +1,8 @@
-import type { Payload, CollectionSlug } from 'payload';
-import type { TaskRunner } from '../TaskRunner.interface';
-import type { TaskHandler } from '../TaskRunnerProvider.interface';
-import type { Task, TaskInput, RunResult } from '../types';
-import type { LazyMap } from '../../../shared/utils';
+import type { Payload, CollectionSlug } from "payload";
+import type { TaskRunner } from "../TaskRunner.interface";
+import type { TaskHandler } from "../TaskRunnerProvider.interface";
+import type { Task, TaskInput, RunResult } from "../types";
+import type { LazyMap } from "../../../shared/utils";
 /**
  * Synchronous TaskRunner implementation.
  *