@focus-reactive/payload-plugin-translator 0.3.0 → 0.5.0

package/dist/server/features/get-collection-status/handler.d.ts

@@ -1,12 +1,12 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type GetCollectionStatusConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
+import type { GetCollectionStatusConfig } from "./model";
 /**
  * Gets translation status for all documents in a collection
  */
 export declare class GetCollectionStatusHandler {
     private readonly config;
     private readonly taskRunnerFactory;
-    constructor(config: GetCollectionStatusConfig, taskRunnerFactory: TaskRunnerProvider);
+    constructor(config: GetCollectionStatusConfig, taskRunnerFactory: TaskRunnerFactory);
     handle(req: PayloadRequest): Promise<Response>;
 }

package/dist/server/features/get-collection-status/handler.js

@@ -1,6 +1,6 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable } from '../_lib/collection-utils';
-import { GetCollectionStatusInputSchema } from './model';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { GetCollectionStatusInputSchema } from "./model";
 /**
  * Gets translation status for all documents in a collection
  */ export class GetCollectionStatusHandler {
@@ -12,9 +12,9 @@ import { GetCollectionStatusInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = GetCollectionStatusInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const collectionSlug = isCollectionAvailable(validationResult.data.collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Collection not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = await runner.findByCollection(collectionSlug);
         return ServerResponse.success({

package/dist/server/features/get-collection-status/route.d.ts

@@ -1,8 +1,8 @@
-import type { Endpoint } from 'payload';
-import type { AccessGuard } from '../../shared';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import type { GetCollectionStatusConfig } from './model';
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
+import type { GetCollectionStatusConfig } from "./model";
 /**
  * Creates the get collection status endpoint
  */
-export declare function createGetCollectionStatusRoute(config: GetCollectionStatusConfig, taskRunnerFactory: TaskRunnerProvider, access?: AccessGuard, basePath?: string): Endpoint;
+export declare function createGetCollectionStatusRoute(config: GetCollectionStatusConfig, taskRunnerFactory: TaskRunnerFactory, access?: AccessGuard, basePath?: string): Endpoint;

package/dist/server/features/get-collection-status/route.js

@@ -1,12 +1,12 @@
-import { withErrorHandler, withAccessCheck } from '../../shared';
-import { GetCollectionStatusHandler } from './handler';
+import { withErrorHandler, withAccessCheck } from "../../shared";
+import { GetCollectionStatusHandler } from "./handler";
 /**
  * Creates the get collection status endpoint
- */ export function createGetCollectionStatusRoute(config, taskRunnerFactory, access, basePath = '/translate') {
+ */ export function createGetCollectionStatusRoute(config, taskRunnerFactory, access, basePath = "/translate") {
     const handler = new GetCollectionStatusHandler(config, taskRunnerFactory);
     return {
         path: `${basePath}/collection/:collection_slug`,
-        method: 'get',
+        method: "get",
         handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
     };
 }

package/dist/server/features/get-document-status/handler.d.ts

@@ -1,12 +1,12 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import { type GetDocumentStatusConfig } from './model';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
+import type { GetDocumentStatusConfig } from "./model";
 /**
  * Gets the translation status for a specific document
  */
 export declare class GetDocumentStatusHandler {
     private readonly config;
     private readonly taskRunnerFactory;
-    constructor(config: GetDocumentStatusConfig, taskRunnerFactory: TaskRunnerProvider);
+    constructor(config: GetDocumentStatusConfig, taskRunnerFactory: TaskRunnerFactory);
     handle(req: PayloadRequest): Promise<Response>;
 }

package/dist/server/features/get-document-status/handler.js

@@ -1,6 +1,6 @@
-import { ServerResponse } from '../../shared';
-import { isCollectionAvailable } from '../_lib/collection-utils';
-import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from './model';
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from "./model";
 /**
  * Gets the translation status for a specific document
  */ export class GetDocumentStatusHandler {
@@ -12,10 +12,10 @@ import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from './model';
     }
     async handle(req) {
         const validationResult = GetDocumentStatusInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { collection_slug, collection_id } = validationResult.data;
         const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
-        if (!collectionSlug) return ServerResponse.badRequest('Collection not available for translation');
+        if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
         const tasks = await runner.findByCollection(collectionSlug, [
             collection_id

package/dist/server/features/get-document-status/route.d.ts

@@ -1,8 +1,8 @@
-import type { Endpoint } from 'payload';
-import type { AccessGuard } from '../../shared';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
-import type { GetDocumentStatusConfig } from './model';
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
+import type { GetDocumentStatusConfig } from "./model";
 /**
  * Creates the get document status endpoint
  */
-export declare function createGetDocumentStatusRoute(config: GetDocumentStatusConfig, taskRunnerFactory: TaskRunnerProvider, access?: AccessGuard, basePath?: string): Endpoint;
+export declare function createGetDocumentStatusRoute(config: GetDocumentStatusConfig, taskRunnerFactory: TaskRunnerFactory, access?: AccessGuard, basePath?: string): Endpoint;

package/dist/server/features/get-document-status/route.js

@@ -1,12 +1,12 @@
-import { withErrorHandler, withAccessCheck } from '../../shared';
-import { GetDocumentStatusHandler } from './handler';
+import { withErrorHandler, withAccessCheck } from "../../shared";
+import { GetDocumentStatusHandler } from "./handler";
 /**
  * Creates the get document status endpoint
- */ export function createGetDocumentStatusRoute(config, taskRunnerFactory, access, basePath = '/translate') {
+ */ export function createGetDocumentStatusRoute(config, taskRunnerFactory, access, basePath = "/translate") {
     const handler = new GetDocumentStatusHandler(config, taskRunnerFactory);
     return {
         path: `${basePath}/document/:collection_slug/:collection_id`,
-        method: 'get',
+        method: "get",
         handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
     };
 }

package/dist/server/features/index.d.ts

@@ -1,6 +1,7 @@
-export * from './translate-document';
-export * from './enqueue-translation';
-export * from './run-translation';
-export * from './cancel';
-export * from './get-document-status';
-export * from './get-collection-status';
+export * from "./createTranslationRoutes";
+export * from "./translate-document";
+export * from "./enqueue-translation";
+export * from "./run-translation";
+export * from "./cancel";
+export * from "./get-document-status";
+export * from "./get-collection-status";

package/dist/server/features/index.js

@@ -1,8 +1,9 @@
-export * from './translate-document';
-export * from './enqueue-translation';
-export * from './run-translation';
-export * from './cancel';
-export * from './get-document-status';
-export * from './get-collection-status';
+export * from "./createTranslationRoutes";
+export * from "./translate-document";
+export * from "./enqueue-translation";
+export * from "./run-translation";
+export * from "./cancel";
+export * from "./get-document-status";
+export * from "./get-collection-status";
 
 //# sourceMappingURL=index.js.map

package/dist/server/features/run-translation/handler.d.ts

@@ -1,10 +1,10 @@
-import type { PayloadRequest } from 'payload';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
+import type { PayloadRequest } from "payload";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
 /**
  * Runs a translation task by ID
  */
 export declare class RunTranslationHandler {
     private readonly taskRunnerFactory;
-    constructor(taskRunnerFactory: TaskRunnerProvider);
+    constructor(taskRunnerFactory: TaskRunnerFactory);
     handle(req: PayloadRequest): Promise<Response>;
 }

package/dist/server/features/run-translation/handler.js

@@ -1,5 +1,5 @@
-import { ServerResponse } from '../../shared';
-import { RunInputSchema } from './model';
+import { ServerResponse } from "../../shared";
+import { RunInputSchema } from "./model";
 /**
  * Runs a translation task by ID
  */ export class RunTranslationHandler {
@@ -9,16 +9,16 @@ import { RunInputSchema } from './model';
     }
     async handle(req) {
         const validationResult = RunInputSchema.safeParse(req.routeParams);
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.errors);
+        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
         const { id } = validationResult.data;
         const runner = this.taskRunnerFactory.create(req.payload);
         const result = await runner.run(id);
         if (!result.success) {
-            if (result.error === 'not_found' || result.error === 'already_completed') {
-                return ServerResponse.notFound('Queued task not found');
+            if (result.error === "not_found" || result.error === "already_completed") {
+                return ServerResponse.notFound("Queued task not found");
             }
-            if (result.error === 'already_running') {
-                return ServerResponse.tooManyRequests('Translation task is already in progress');
+            if (result.error === "already_running") {
+                return ServerResponse.tooManyRequests("Translation task is already in progress");
             }
         }
         return ServerResponse.noContent();

package/dist/server/features/run-translation/route.d.ts

@@ -1,7 +1,7 @@
-import type { Endpoint } from 'payload';
-import type { AccessGuard } from '../../shared';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
 /**
  * Creates the run translation endpoint
  */
-export declare function createRunRoute(taskRunnerFactory: TaskRunnerProvider, access?: AccessGuard, basePath?: string): Endpoint;
+export declare function createRunRoute(taskRunnerFactory: TaskRunnerFactory, access?: AccessGuard, basePath?: string): Endpoint;

package/dist/server/features/run-translation/route.js

@@ -1,12 +1,12 @@
-import { withErrorHandler, withAccessCheck } from '../../shared';
-import { RunTranslationHandler } from './handler';
+import { withErrorHandler, withAccessCheck } from "../../shared";
+import { RunTranslationHandler } from "./handler";
 /**
  * Creates the run translation endpoint
- */ export function createRunRoute(taskRunnerFactory, access, basePath = '/translate') {
+ */ export function createRunRoute(taskRunnerFactory, access, basePath = "/translate") {
     const handler = new RunTranslationHandler(taskRunnerFactory);
     return {
         path: `${basePath}/run/:id`,
-        method: 'post',
+        method: "post",
         handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
     };
 }

package/dist/server/features/translate-document/handler.js

@@ -1,6 +1,5 @@
 import { APIError } from "payload";
-import { TranslationPipeline } from "../../modules/translation-pipeline";
-import { createTranslationStrategy } from "../../modules/translation-pipeline/strategies";
+import { translateContent } from "../../modules/translation-pipeline";
 /**
  * Translates a single document from source language to target language
  */ export class TranslateDocumentHandler {
@@ -28,23 +27,20 @@ import { createTranslationStrategy } from "../../modules/translation-pipeline/st
             fallbackLocale: false,
             depth: 0
         });
-        const translationStrategy = createTranslationStrategy(strategy);
-        const pipeline = new TranslationPipeline({
-            translationProvider: this.translationProvider,
-            translationStrategy
-        });
-        const result = await pipeline.execute({
+        const translatedData = await translateContent({
             schema,
             sourceData,
             targetData,
             sourceLng,
-            targetLng
+            targetLng,
+            translationProvider: this.translationProvider,
+            strategy
         });
-        if (!result) return {
+        if (!translatedData) return {
             success: true
         };
         const collectionConfig = payload.collections[collection].config;
-        await this.saveTranslatedDocument(payload, collection, collectionId, result.translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
+        await this.saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
         return {
             success: true
         };

package/dist/server/modules/task-runner/TaskRunnerProvider.interface.d.ts

@@ -24,6 +24,16 @@ export type TaskRunnerContext = {
     handler: TaskHandler;
     collections: CollectionSlug[];
 };
+/**
+ * The runtime half of a runner: produces a `TaskRunner` for one request.
+ *
+ * Routes depend on this narrow surface — they only ever `create()`, never
+ * `configure()`. The plugin binds the {@link TaskRunnerContext} once at build
+ * time and hands routes a factory, so a `create()` call needs no ambient state.
+ */
+export type TaskRunnerFactory = {
+    create(payload: Payload): TaskRunner;
+};
 /**
  * Main interface for pluggable task runner providers.
  *
@@ -36,11 +46,19 @@ export type TaskRunnerContext = {
 export interface TaskRunnerProvider {
     /**
      * Creates a TaskRunner instance for runtime operations (enqueue, cancel, find).
+     *
+     * `handler` is supplied by the caller at create time (the plugin binds it
+     * into a {@link TaskRunnerFactory}) — so providers hold no mutable per-instance
+     * state and `create()` does not depend on `configure()` having run. It is the
+     * only runtime dependency (collection metadata is a `configure()`-time concern).
+     * `PayloadJobsRunner` ignores it (the handler is baked into the registered
+     * task at configure time); `SyncRunner` uses it to run translations inline.
      */
-    create(payload: Payload): TaskRunner;
+    create(payload: Payload, handler: TaskHandler): TaskRunner;
     /**
      * Configures the runner and returns a Payload config modifier.
      * The modifier adds necessary tasks, jobs, queues to Payload config.
+     * Implementations may also install a `config.onInit` hook for boot-time initialization (e.g. stale-lock recovery).
      */
     configure(context: TaskRunnerContext): (config: Config) => Config;
 }

package/dist/server/modules/task-runner/index.d.ts

@@ -1,6 +1,6 @@
-export type { TaskRunnerProvider } from './TaskRunnerProvider.interface';
-export type { Task, TaskStatus } from './types';
-export { createPayloadJobsRunner } from './payload-jobs-runner';
-export type { PayloadJobsRunnerOptions } from './payload-jobs-runner';
-export { createSyncRunner } from './sync-runner';
-export type { TaskRunner } from './TaskRunner.interface';
+export type { TaskRunnerProvider, TaskRunnerFactory, TaskRunnerContext } from "./TaskRunnerProvider.interface";
+export type { Task, TaskStatus } from "./types";
+export { createPayloadJobsRunner } from "./payload-jobs-runner";
+export type { PayloadJobsRunnerOptions } from "./payload-jobs-runner";
+export { createSyncRunner } from "./sync-runner";
+export type { TaskRunner } from "./TaskRunner.interface";

package/dist/server/modules/task-runner/index.js

@@ -1,4 +1,4 @@
-export { createPayloadJobsRunner } from './payload-jobs-runner';
-export { createSyncRunner } from './sync-runner';
+export { createPayloadJobsRunner } from "./payload-jobs-runner";
+export { createSyncRunner } from "./sync-runner";
 
 //# sourceMappingURL=index.js.map

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

@@ -14,6 +14,21 @@ export declare class PayloadJobsRunnerProvider implements TaskRunnerProvider {
     configure(context: TaskRunnerContext): (config: Config) => Config;
 }
 /**
- * Creates a TaskRunnerProvider that uses Payload Jobs for task execution.
+ * Creates the **recommended** task runner: translations run as Payload Jobs
+ * (queued, executed by autoRun cron or a manual run, with stale-lock recovery).
+ * Durable across restarts and suited to production/serverless. Pass the result
+ * as `translatorPlugin({ runner })`.
+ *
+ * @param options - Queue/task names, `autoRun` cron (or `false` to disable),
+ *   `staleJobTimeoutMs`, and retry policy. See {@link PayloadJobsRunnerOptions}.
+ * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   runner: createPayloadJobsRunner({ autoRun: { cron: '* * * * *' } }),
+ * })
+ * ```
  */
 export declare function createPayloadJobsRunner(options?: PayloadJobsRunnerOptions): TaskRunnerProvider;

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

@@ -4,11 +4,13 @@ const defaultAutoRun = {
     cron: "* * * * *",
     limit: 50
 };
+const DEFAULT_STALE_JOB_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const defaultValues = {
     taskName: "translate_document",
     queueName: "translations",
     jobsCollection: "payload-jobs",
     autoRun: defaultAutoRun,
+    staleJobTimeoutMs: DEFAULT_STALE_JOB_TIMEOUT_MS,
     retries: {
         attempts: 3,
         backoff: {
@@ -28,11 +30,16 @@ const defaultValues = {
             ...defaultAutoRun,
             ...options.autoRun
         } : defaultAutoRun;
+        const staleJobTimeoutMs = options?.staleJobTimeoutMs ?? defaultValues.staleJobTimeoutMs;
+        if (!Number.isFinite(staleJobTimeoutMs) || staleJobTimeoutMs <= 0) {
+            throw new Error(`[payload-plugin-translator] staleJobTimeoutMs must be a positive finite number (got ${staleJobTimeoutMs})`);
+        }
         this.config = {
             taskName: options?.taskName ?? defaultValues.taskName,
             queueName: options?.queueName ?? defaultValues.queueName,
             jobsCollection: options?.jobsCollection ?? defaultValues.jobsCollection,
             autoRun,
+            staleJobTimeoutMs,
             retries: options?.retries ?? defaultValues.retries
         };
     }
@@ -141,12 +148,46 @@ const defaultValues = {
                     ];
                 }
             }
+            // Reset stale locks on boot so jobs abandoned by a killed process
+            // (deploy/crash/timeout) become eligible for the autorun picker again.
+            // The picker requires processing:false, no error, and no pending waitUntil;
+            // a mid-run casualty (no error, no waitUntil) satisfies the rest, so
+            // clearing processing is sufficient for that case. Threshold-based, so a
+            // job genuinely in flight on another live instance (fresh updatedAt) is
+            // left alone. Wrapped so a reclaim failure never blocks startup.
+            const existingOnInit = config.onInit;
+            config.onInit = async (payload)=>{
+                if (existingOnInit) await existingOnInit(payload);
+                try {
+                    await new PayloadJobsTaskRunner(payload, this.config).reclaimStaleJobs();
+                } catch (err) {
+                    payload.logger?.error?.({
+                        err,
+                        msg: "[translator] failed to reclaim stale translation jobs"
+                    });
+                }
+            };
             return config;
         };
     }
 }
 /**
- * Creates a TaskRunnerProvider that uses Payload Jobs for task execution.
+ * Creates the **recommended** task runner: translations run as Payload Jobs
+ * (queued, executed by autoRun cron or a manual run, with stale-lock recovery).
+ * Durable across restarts and suited to production/serverless. Pass the result
+ * as `translatorPlugin({ runner })`.
+ *
+ * @param options - Queue/task names, `autoRun` cron (or `false` to disable),
+ *   `staleJobTimeoutMs`, and retry policy. See {@link PayloadJobsRunnerOptions}.
+ * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
+ *   runner: createPayloadJobsRunner({ autoRun: { cron: '* * * * *' } }),
+ * })
+ * ```
  */ export function createPayloadJobsRunner(options) {
     return new PayloadJobsRunnerProvider(options);
 }

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

@@ -14,6 +14,35 @@ export declare class PayloadJobsTaskRunner implements TaskRunner {
     enqueue(tasks: TaskInput[]): Promise<void>;
     cancel(taskIds: string[]): Promise<void>;
     run(taskId: string): Promise<RunResult>;
+    /**
+     * 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().
+     *
+     * 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.
      *

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

@@ -63,19 +63,114 @@ 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
         };
     }
     /**
+   * 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().
+   *
+   * 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.
    *
    * Narrowing is by `taskSlug` only in SQL; the collection slug and document