@purposeinplay/payload-ai-translate 0.1.0

package/dist/hooks/after-change-global.js

@@ -0,0 +1,109 @@
+import { translateGlobal } from '../api.js';
+import { REENTRY_FLAG, SKIP_FLAG } from '../defaults.js';
+import { getDocAutoLocaleOverride, getDocOptOut, getEffectiveAutoLocales, getGlobalKillSwitches } from '../lib/effective-locales.js';
+import { completeJobNow, getActiveJobForDoc, getOrCreateJobForDoc } from '../lib/progress-store.js';
+// ---------------------------------------------------------------------------
+// Hook factory
+// ---------------------------------------------------------------------------
+export function createTranslateGlobalAfterChangeHook(globalSlug, pluginOptions, queue) {
+    const diffOnly = pluginOptions.automation?.diffOnly !== false; // default true
+    return async ({ req, doc, previousDoc })=>{
+        // Re-entrancy guard — plugin's own writes and bulk imports skip translation
+        const ctx = req.context ?? {};
+        if (ctx[REENTRY_FLAG] || ctx[SKIP_FLAG]) {
+            return doc;
+        }
+        // Only translate source-locale saves
+        if (req.locale && req.locale !== pluginOptions.sourceLocale) {
+            return doc;
+        }
+        // Plugin-wide auto-translate kill switch (v1.2.8). See after-change.ts
+        // for the full reasoning; same gate, mirrored for globals.
+        const killSwitches = await getGlobalKillSwitches(req.payload, pluginOptions);
+        if (!killSwitches.autoEnabled) {
+            return doc;
+        }
+        // Early-return helper that closes out any stranded job seeded by a
+        // parent flow. Mirrors the pattern in after-change.ts.
+        const earlyReturn = ()=>{
+            const stranded = getActiveJobForDoc(globalSlug, globalSlug);
+            if (stranded) completeJobNow(stranded.jobId);
+            return doc;
+        };
+        // Per-doc opt-out gate. Editor explicitly checked "skip
+        // auto-translate for this global save" — bail before any other work.
+        if (getDocOptOut(doc)) {
+            return earlyReturn();
+        }
+        // Layered locale resolution: plugin → site-wide → per-global →
+        // per-doc narrow. Empty result skips dispatch entirely. See
+        // `getEffectiveAutoLocales` for the full stack.
+        const decision = await getEffectiveAutoLocales(req.payload, pluginOptions, globalSlug);
+        if (decision.skipAutoOnPublish || decision.locales.length === 0) {
+            return earlyReturn();
+        }
+        // Per-doc widget narrows further when set. Empty array = inherit;
+        // opt-out is the separate boolean flag handled above.
+        const docOverride = getDocAutoLocaleOverride(doc);
+        let effectiveLocales = decision.locales;
+        if (docOverride !== undefined) {
+            const allowed = new Set(docOverride);
+            effectiveLocales = effectiveLocales.filter((l)=>allowed.has(l));
+        }
+        if (effectiveLocales.length === 0) {
+            return earlyReturn();
+        }
+        // Atomic get-or-create — see after-change.ts for the rationale.
+        // When `created: false`, another fire is already dispatching the
+        // translation; this fire returns early to avoid duplicate LLM
+        // calls and locale-write races.
+        const { jobId, created } = getOrCreateJobForDoc(globalSlug, globalSlug, effectiveLocales);
+        if (!created) {
+            return doc;
+        }
+        // Honor diffOnly:false — don't pass previousDoc downstream, so the
+        // per-unit diff filter in translateGlobal stays disabled.
+        const previousDocForTranslate = diffOnly ? previousDoc : undefined;
+        // When async mode is configured, route through the coalescing queue so a
+        // burst of saves on the same global collapses into one translation pass.
+        // Without the queue (inline mode, or queue not provided), fire-and-forget.
+        //
+        // Wrap dispatch in try/catch so a queue/translate failure can never
+        // propagate up to Payload and 500 the original save. Mirrors the
+        // pattern in after-change.ts.
+        try {
+            if (queue) {
+                queue.enqueue({
+                    payload: req.payload,
+                    kind: 'global',
+                    collection: globalSlug,
+                    id: globalSlug,
+                    doc: doc,
+                    previousDoc: previousDocForTranslate ?? {},
+                    jobId,
+                    req,
+                    targetLocales: effectiveLocales
+                });
+                return doc;
+            }
+            // Fire-and-forget: never block the save.
+            // Awaiting here would deadlock the request transaction against the
+            // hook's own payload.updateGlobal calls on the locale rows we just
+            // wrote. Let the request commit, then translate in the background.
+            void translateGlobal(req.payload, {
+                global: globalSlug,
+                previousDoc: previousDocForTranslate,
+                jobId,
+                req,
+                targetLocales: effectiveLocales
+            }).catch((err)=>{
+                const msg = err instanceof Error ? err.message : 'Unknown error';
+                req.payload.logger.error(`[ai-translate] Auto-translation failed for global "${globalSlug}": ${msg}`);
+            });
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            req.payload.logger.error(`[ai-translate] Auto-translation dispatch failed for global "${globalSlug}": ${msg}`);
+        }
+        return doc;
+    };
+}

package/dist/hooks/after-change.d.ts

@@ -0,0 +1,16 @@
+import type { CollectionAfterChangeHook } from 'payload';
+import type { CoalescingQueue } from '../lib/coalescing-queue.js';
+import type { AITranslatePluginConfig } from '../types.js';
+export type CreateAfterChangeHookOptions = {
+    collectionSlug: string;
+    pluginOptions: AITranslatePluginConfig;
+    queue: CoalescingQueue | null;
+    /**
+     * Whether the collection has draft/publish versioning. When false the
+     * `_status` field doesn't exist on the doc, so the on-publish trigger gate
+     * is skipped and every source-locale save is translated.
+     */
+    hasDrafts: boolean;
+};
+export declare function createTranslateAfterChangeHook(options: CreateAfterChangeHookOptions): CollectionAfterChangeHook;
+export declare function createTranslateAfterChangeHook(collectionSlug: string, pluginOptions: AITranslatePluginConfig, queue: CoalescingQueue | null): CollectionAfterChangeHook;

package/dist/hooks/after-change.js

@@ -0,0 +1,205 @@
+import { translateDocument } from '../api.js';
+import { REENTRY_FLAG, SKIP_FLAG } from '../defaults.js';
+import { getDocAutoLocaleOverride, getDocOptOut, getEffectiveAutoLocales, getGlobalKillSwitches } from '../lib/effective-locales.js';
+import { diffFields } from '../lib/field-diff.js';
+import { resolveTranslatableFields } from '../lib/field-resolver.js';
+import { completeJobNow, getActiveJobForDoc, getOrCreateJobForDoc } from '../lib/progress-store.js';
+export function createTranslateAfterChangeHook(arg1, pluginOptionsArg, queueArg) {
+    const opts = typeof arg1 === 'string' ? {
+        collectionSlug: arg1,
+        pluginOptions: pluginOptionsArg,
+        queue: queueArg ?? null,
+        hasDrafts: true
+    } : arg1;
+    const { collectionSlug, pluginOptions, queue, hasDrafts } = opts;
+    const automation = pluginOptions.automation;
+    const trigger = automation?.trigger ?? 'on-change';
+    const diffOnly = automation?.diffOnly !== false; // default true
+    return async ({ req, doc, previousDoc, operation })=>{
+        // Re-entrancy guard — plugin's own writes and bulk imports skip translation
+        const ctx = req.context ?? {};
+        if (ctx[REENTRY_FLAG] || ctx[SKIP_FLAG]) {
+            return doc;
+        }
+        // Only translate source-locale saves
+        if (req.locale && req.locale !== pluginOptions.sourceLocale) {
+            return doc;
+        }
+        // Plugin-wide auto-translate kill switch (v1.2.8). When admin flipped
+        // `globalAutoTranslateEnabled` off in the settings global, this hook
+        // short-circuits before any other work — no progress job, no LLM
+        // dispatch, no restore-version recovery. Manual Translate and Bulk
+        // Translate still work because they don't route through this hook.
+        // Fail-safe-CLOSED on settings read failure: skip auto. See
+        // `getGlobalKillSwitches` for the per-flag reasoning.
+        const killSwitches = await getGlobalKillSwitches(req.payload, pluginOptions);
+        if (!killSwitches.autoEnabled) {
+            return doc;
+        }
+        // BUG-23 fix: when Payload's restoreVersion fires, target-locale rows
+        // get reset because the version snapshot only captured source content.
+        // Detect this via the `operation` hook arg (Payload sets it to
+        // 'restoreVersion' for restore writes) and FORCE auto-translate to
+        // re-populate target locales — even if `trigger: 'on-publish'` and
+        // the restore landed on a draft. Without this, editors lose all
+        // target-locale content silently and must remember to click Translate.
+        const isRestoreVersion = operation === 'restoreVersion';
+        if (isRestoreVersion) {
+            req.payload.logger?.warn?.(`[ai-translate] Version restore detected for ${collectionSlug}/${doc?.id}. Target-locale rows are being reset by Payload — the plugin will auto-translate to repopulate them. Editors who had manually refined target content should review after the auto-translate completes.`);
+        }
+        // On-publish trigger: only enforced when the collection actually has
+        // drafts. Without versioning, _status doesn't exist on the doc and we
+        // would gate forever, never translating. Treat non-versioned collections
+        // as on-change.
+        //
+        // BUG-23: restoreVersion bypasses the publish gate. Target locales
+        // get wiped regardless of whether the restored version was a draft
+        // or published — recovery must run either way.
+        let isPublishTransition = false;
+        if (trigger === 'on-publish' && hasDrafts && !isRestoreVersion) {
+            const currStatus = doc?._status;
+            if (currStatus !== 'published') {
+                return doc;
+            }
+            const prevStatus = previousDoc?._status;
+            isPublishTransition = prevStatus !== 'published';
+        }
+        // Field diff: skip if no translatable fields changed.
+        // EXCEPT on a publish-transition (draft → published) where the autosave
+        // baseline already matches the published content. In that case the diff
+        // is empty but the document was never translated yet — force translation
+        // by clearing previousDoc downstream.
+        //
+        // ALSO except on restoreVersion (BUG-23): the restore reset target
+        // locales so we MUST re-translate everything to recover. The diff
+        // path would skip because the source content matches a past version.
+        let forceTranslateAll = isRestoreVersion;
+        if (diffOnly && previousDoc && !isRestoreVersion) {
+            const fields = getCollectionFields(req.payload, collectionSlug);
+            if (fields) {
+                const translatableFields = resolveTranslatableFields(fields);
+                const fieldPaths = translatableFields.map((f)=>f.path);
+                const changedPaths = diffFields(previousDoc, doc, fieldPaths);
+                if (changedPaths.length === 0) {
+                    if (!isPublishTransition) {
+                        return doc;
+                    }
+                    // Publish-transition with identical content → translate all
+                    forceTranslateAll = true;
+                }
+            }
+        }
+        const documentId = doc?.id;
+        if (!documentId) {
+            return doc;
+        }
+        // Helper: an early-return path that ALSO closes out any active job
+        // a parent flow may have seeded. Without this, a stranded `running`
+        // job hangs in the UI for ~2 minutes (TTL sweep) showing
+        // "Translating…" that never completes.
+        const earlyReturn = ()=>{
+            const stranded = getActiveJobForDoc(collectionSlug, documentId);
+            if (stranded) completeJobNow(stranded.jobId);
+            return doc;
+        };
+        // Per-doc opt-out gate. When the editor explicitly checked
+        // "skip auto-translate for this doc," bail before any other work.
+        // Manual Translate from the dialog is NOT gated by this — same
+        // scope as the collection-level `enabled` flag.
+        if (getDocOptOut(doc)) {
+            return earlyReturn();
+        }
+        // Resolve effective locales via the layered stack:
+        //   plugin config → site-wide → per-collection → per-doc narrow
+        // Empty result = admin opted out of every locale (or the per-collection
+        // widget unchecked everything), so skip dispatch entirely (no ghost
+        // progress job, no LLM cost). Manual Translate button still works
+        // against config.targetLocales unaffected — these gates apply to the
+        // automation path only.
+        const decision = await getEffectiveAutoLocales(req.payload, pluginOptions, collectionSlug);
+        if (decision.skipAutoOnPublish || decision.locales.length === 0) {
+            return earlyReturn();
+        }
+        // Per-doc widget narrows the effective set further when set:
+        //   - undefined / empty → inherit collection-level decision (no narrow)
+        //   - [...]             → restrict to these locales (intersected with decision)
+        // Opt-out is expressed via the separate `_aiTranslateOptOut` flag
+        // (checked above) — not via empty array here.
+        // Stale locales (codes no longer in plugin config) are silently
+        // dropped here so a stored ['de','fr','XX-removed'] still narrows
+        // to ['de','fr'] rather than failing the intersection.
+        const docOverride = getDocAutoLocaleOverride(doc);
+        let effectiveLocales = decision.locales;
+        if (docOverride !== undefined) {
+            const allowed = new Set(docOverride);
+            effectiveLocales = effectiveLocales.filter((l)=>allowed.has(l));
+        }
+        if (effectiveLocales.length === 0) {
+            return earlyReturn();
+        }
+        // When diffOnly is OFF, force a full retranslation by passing undefined —
+        // otherwise translateDocument's per-unit diff filter would still narrow
+        // to changed fields, which is the opposite of what diffOnly:false means.
+        const previousDocForTranslate = forceTranslateAll || !diffOnly ? undefined : previousDoc;
+        // Reuse an active job for this doc if one exists (e.g. queued
+        // translation still running) — otherwise create a fresh one so the
+        // UI can show "Translating..." immediately. The same jobId is
+        // threaded through to translateDocument so updateJob ticks land on
+        // the job the UI is polling.
+        //
+        // `getOrCreateJobForDoc` is atomic from the event-loop's
+        // perspective: two concurrent fires for the same doc can't both
+        // pass the existence check and both create a job. When `created`
+        // is false the second caller joins the in-flight job and the
+        // duplicate dispatch below becomes a redundant no-op
+        // (translateDocument is idempotent w.r.t. an already-completed
+        // job because updateJob silently no-ops on terminal status).
+        const { jobId, created } = getOrCreateJobForDoc(collectionSlug, documentId, effectiveLocales);
+        if (!created) {
+            // Another fire already created the job and is dispatching the
+            // translation. Don't fire again — the second LLM call would
+            // double-bill and race on locale writes.
+            return doc;
+        }
+        // Dispatch translation — never block the save
+        try {
+            if (queue) {
+                // Async mode: coalesce rapid saves
+                queue.enqueue({
+                    payload: req.payload,
+                    collection: collectionSlug,
+                    id: documentId,
+                    doc: doc,
+                    previousDoc: previousDocForTranslate ?? {},
+                    jobId,
+                    req,
+                    targetLocales: effectiveLocales
+                });
+            } else {
+                // Inline mode: fire-and-forget to avoid transaction deadlock
+                // (the hook holds a DB transaction, and translateDocument reads the same doc)
+                void translateDocument(req.payload, {
+                    collection: collectionSlug,
+                    id: documentId,
+                    previousDoc: previousDocForTranslate,
+                    jobId,
+                    req,
+                    targetLocales: effectiveLocales
+                }).catch((err)=>{
+                    req.payload.logger.error(`[ai-translate] Inline translation failed for ${collectionSlug}/${String(documentId)}: ${err instanceof Error ? err.message : 'Unknown'}`);
+                });
+            }
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            req.payload.logger.error(`[ai-translate] Auto-translation failed for ${collectionSlug}/${String(documentId)}: ${msg}`);
+        }
+        return doc;
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getCollectionFields(payload, slug) {
+    const collection = payload.config?.collections?.find((c)=>c.slug === slug);
+    return collection?.fields;
+}

package/dist/hooks/after-delete.d.ts

@@ -0,0 +1,30 @@
+import type { CollectionAfterDeleteHook } from 'payload';
+import type { AITranslatePluginConfig } from '../types.js';
+/**
+ * After-delete cleanup hook (BUG-20 + BUG-26).
+ *
+ * When a tracked-collection document is deleted, two plugin-owned tables
+ * still hold rows referencing the doc:
+ *
+ *   - `ai_translate_jobs` — visible "Translating..." rows in the admin
+ *     Jobs page. Without cleanup, deleted docs leave ghost-running jobs
+ *     here that the UI shows forever (BUG-26 stuck-running on bulk
+ *     delete during active translation).
+ *
+ *   - `ai_translate_meta` — manual-edit fingerprints. Without cleanup,
+ *     stale fingerprints accumulate across the table's lifetime; if a
+ *     new doc reuses the same numeric id (rare but possible on
+ *     short-cycle test DBs), the stale fingerprint blocks the first
+ *     translation. Storage just keeps growing unboundedly (BUG-20).
+ *
+ * The hook runs AFTER Payload's delete operation completes — best-
+ * effort. If cleanup fails the doc deletion still succeeded; we log
+ * but don't throw. Brief orphan windows are tolerated; the next save
+ * on a different doc isn't affected.
+ *
+ * In-memory progress-store cleanup: also marks any active in-memory
+ * job for this doc as completed (with reason: 'document deleted')
+ * so SSE subscribers see the terminal state immediately rather than
+ * waiting for the 2-minute TTL sweep.
+ */
+export declare function createAiTranslateAfterDeleteHook(collectionSlug: string, pluginOptions: AITranslatePluginConfig): CollectionAfterDeleteHook;

package/dist/hooks/after-delete.js

@@ -0,0 +1,95 @@
+import { DEFAULT_JOBS_COLLECTION_SLUG } from '../jobs-collection.js';
+import { completeJobNow, getActiveJobForDoc } from '../lib/progress-store.js';
+import { DEFAULT_MANUAL_EDIT_COLLECTION_SLUG } from '../manual-edit-collection.js';
+/**
+ * After-delete cleanup hook (BUG-20 + BUG-26).
+ *
+ * When a tracked-collection document is deleted, two plugin-owned tables
+ * still hold rows referencing the doc:
+ *
+ *   - `ai_translate_jobs` — visible "Translating..." rows in the admin
+ *     Jobs page. Without cleanup, deleted docs leave ghost-running jobs
+ *     here that the UI shows forever (BUG-26 stuck-running on bulk
+ *     delete during active translation).
+ *
+ *   - `ai_translate_meta` — manual-edit fingerprints. Without cleanup,
+ *     stale fingerprints accumulate across the table's lifetime; if a
+ *     new doc reuses the same numeric id (rare but possible on
+ *     short-cycle test DBs), the stale fingerprint blocks the first
+ *     translation. Storage just keeps growing unboundedly (BUG-20).
+ *
+ * The hook runs AFTER Payload's delete operation completes — best-
+ * effort. If cleanup fails the doc deletion still succeeded; we log
+ * but don't throw. Brief orphan windows are tolerated; the next save
+ * on a different doc isn't affected.
+ *
+ * In-memory progress-store cleanup: also marks any active in-memory
+ * job for this doc as completed (with reason: 'document deleted')
+ * so SSE subscribers see the terminal state immediately rather than
+ * waiting for the 2-minute TTL sweep.
+ */ export function createAiTranslateAfterDeleteHook(collectionSlug, pluginOptions) {
+    return async ({ id, req })=>{
+        if (id === undefined || id === null) return;
+        // 1. Close out the in-memory progress-store job (UI feedback)
+        try {
+            const active = getActiveJobForDoc(collectionSlug, id);
+            if (active) {
+                completeJobNow(active.jobId);
+            }
+        } catch (err) {
+            req.payload.logger?.warn?.(`[ai-translate] In-memory job cleanup failed for ${collectionSlug}/${String(id)}: ${err instanceof Error ? err.message : 'Unknown'}`);
+        }
+        // 2. Delete persisted `ai_translate_jobs` rows for this doc
+        if (pluginOptions.persistJobs) {
+            const jobsSlug = pluginOptions.jobsCollectionSlug ?? DEFAULT_JOBS_COLLECTION_SLUG;
+            try {
+                await req.payload.delete({
+                    collection: jobsSlug,
+                    where: {
+                        and: [
+                            {
+                                collection: {
+                                    equals: collectionSlug
+                                }
+                            },
+                            {
+                                documentId: {
+                                    equals: String(id)
+                                }
+                            }
+                        ]
+                    },
+                    overrideAccess: true
+                });
+            } catch (err) {
+                req.payload.logger?.warn?.(`[ai-translate] ai_translate_jobs cleanup failed for ${collectionSlug}/${String(id)}: ${err instanceof Error ? err.message : 'Unknown'}`);
+            }
+        }
+        // 3. Delete `ai_translate_meta` fingerprints for this doc
+        if (pluginOptions.preserveManualEdits) {
+            const metaSlug = pluginOptions.manualEditCollectionSlug ?? DEFAULT_MANUAL_EDIT_COLLECTION_SLUG;
+            try {
+                await req.payload.delete({
+                    collection: metaSlug,
+                    where: {
+                        and: [
+                            {
+                                collection: {
+                                    equals: collectionSlug
+                                }
+                            },
+                            {
+                                documentId: {
+                                    equals: String(id)
+                                }
+                            }
+                        ]
+                    },
+                    overrideAccess: true
+                });
+            } catch (err) {
+                req.payload.logger?.warn?.(`[ai-translate] ai_translate_meta cleanup failed for ${collectionSlug}/${String(id)}: ${err instanceof Error ? err.message : 'Unknown'}`);
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { translateDocument } from './api.js';
+export { ensureBulkTranslateSchema, migrateBatchStatusVocabulary, migrateHashesToV1Prefix, } from './lib/bulk-translate-migrations.js';
+export { createScopedLogger, type LogContext, type LogEventFields, type LogLevel, type ScopedLogger, type SerializedError, serializeErr, } from './lib/logger.js';
+export { type AcquireTokenResult, acquireToken, getBucketStatus, type TokenBucketOptions, } from './lib/translation-token-bucket.js';
+export { aiTranslatePlugin } from './plugin.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { translateDocument } from './api.js';
+export { ensureBulkTranslateSchema, migrateBatchStatusVocabulary, migrateHashesToV1Prefix } from './lib/bulk-translate-migrations.js';
+export { createScopedLogger, serializeErr } from './lib/logger.js';
+export { acquireToken, getBucketStatus } from './lib/translation-token-bucket.js';
+export { aiTranslatePlugin } from './plugin.js';

package/dist/jobs-collection.d.ts

@@ -0,0 +1,17 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare const DEFAULT_JOBS_COLLECTION_SLUG = "ai-translate-jobs";
+/**
+ * Optional sidecar collection used by `persistJobs`. Mirrors the in-
+ * memory progress-store state so admin views, debug pages, or post-
+ * restart inspection can see which translations were in flight.
+ *
+ * NOT a full work-queue — the actual translation closures (req, doc,
+ * previousDoc) stay in process memory. A server restart still loses
+ * the in-flight LLM call. This collection persists the STATUS only so
+ * admins can spot "ghost" jobs that stopped progressing and re-trigger
+ * them manually.
+ *
+ * For full work resumption, see the follow-up ticket on migrating to
+ * Payload's native jobs queue (`payload.jobs.queue`).
+ */
+export declare function createJobsCollection(readAccess?: Access, slug?: string, deleteAccess?: Access): CollectionConfig;

package/dist/jobs-collection.js

@@ -0,0 +1,139 @@
+export const DEFAULT_JOBS_COLLECTION_SLUG = 'ai-translate-jobs';
+/**
+ * Optional sidecar collection used by `persistJobs`. Mirrors the in-
+ * memory progress-store state so admin views, debug pages, or post-
+ * restart inspection can see which translations were in flight.
+ *
+ * NOT a full work-queue — the actual translation closures (req, doc,
+ * previousDoc) stay in process memory. A server restart still loses
+ * the in-flight LLM call. This collection persists the STATUS only so
+ * admins can spot "ghost" jobs that stopped progressing and re-trigger
+ * them manually.
+ *
+ * For full work resumption, see the follow-up ticket on migrating to
+ * Payload's native jobs queue (`payload.jobs.queue`).
+ */ export function createJobsCollection(readAccess, slug = DEFAULT_JOBS_COLLECTION_SLUG, deleteAccess) {
+    const isAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (Array.isArray(roles) && roles.includes('admin')) return true;
+        return false;
+    };
+    return {
+        slug,
+        // System rows are never edited in the admin document view, so
+        // Payload's document-locking buys nothing here — and its lock check
+        // costs a second pool connection inside every update transaction
+        // (core's checkDocumentLockStatus runs a find without `req`). Under
+        // concurrent updates (e.g. dismiss-all on alerts) that exhausted the
+        // pool and deadlocked a consumer in prod on 2026-06-10.
+        lockDocuments: false,
+        labels: {
+            singular: 'AI Translate Job (in-flight)',
+            plural: 'AI Translate Jobs — in-flight queue'
+        },
+        admin: {
+            group: 'System',
+            useAsTitle: 'jobId',
+            defaultColumns: [
+                'jobId',
+                'collection',
+                'documentId',
+                'status',
+                'startedAt'
+            ],
+            hidden: ({ user })=>{
+                const roles = user?.roles;
+                return !Array.isArray(roles) || !roles.includes('admin');
+            },
+            description: 'IN-FLIGHT QUEUE ONLY — not a permanent log. Each row mirrors a currently-running or just-finished translation job. Rows auto-expire ~2 minutes after the job completes. If this view is EMPTY, no translations are currently running — that is the normal idle state. For permanent translation history + cost data, see "Translation Usage".'
+        },
+        access: {
+            read: readAccess ?? isAdminDefault,
+            create: ()=>false,
+            update: ()=>false,
+            delete: deleteAccess ?? isAdminDefault
+        },
+        fields: [
+            {
+                name: 'jobId',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'collection',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'documentId',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'status',
+                type: 'select',
+                required: true,
+                options: [
+                    {
+                        label: 'Running',
+                        value: 'running'
+                    },
+                    {
+                        label: 'Completed',
+                        value: 'completed'
+                    },
+                    {
+                        label: 'Failed',
+                        value: 'failed'
+                    }
+                ],
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'totalLocales',
+                type: 'number',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'completedLocales',
+                type: 'json',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'failedLocales',
+                type: 'json',
+                admin: {
+                    readOnly: true,
+                    description: 'Array of `{ locale, error }` for failed locales.'
+                }
+            },
+            {
+                name: 'startedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            }
+        ]
+    };
+}

package/dist/lexical/classifier.d.ts

@@ -0,0 +1,3 @@
+import type { LexicalNodeRegistration } from '../types.js';
+import type { ClassifiedNode, LexicalNode } from './types.js';
+export declare function classifyNode(node: LexicalNode, registeredNodes?: LexicalNodeRegistration[]): ClassifiedNode;