@purposeinplay/payload-ai-translate 0.1.0

package/dist/tasks/bulk-translate-coordinator.js

@@ -0,0 +1,708 @@
+import { DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG } from '../bulk-translate-batches-collection.js';
+import { DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG } from '../bulk-translate-units-collection.js';
+import { resolveTranslatableFields } from '../lib/field-resolver.js';
+import { createScopedLogger } from '../lib/logger.js';
+import { hashLocalizedSchema } from '../lib/snapshot-select.js';
+export const BULK_TRANSLATE_COORDINATOR_SLUG = 'bulk-translate-coordinator';
+export const BULK_TRANSLATE_DOC_TASK_SLUG = 'bulk-translate-doc';
+// ---------------------------------------------------------------------------
+// Task config
+// ---------------------------------------------------------------------------
+const taskInputSchema = [
+    {
+        name: 'batchId',
+        type: 'text',
+        required: true
+    }
+];
+/**
+ * Coordinator task that enumerates every (doc, locale) under
+ * `batch.scope`, inserts a `bulk-translate-units` row per unit and
+ * queues a `bulk-translate-doc` task per unit. Both ops are wrapped
+ * in a single transaction per (doc, locale) tuple to close F-DA-TOCTOU
+ * scenario A — the worker can never dequeue before the unit row has
+ * committed.
+ *
+ * Long enumerations trampoline: the task self-re-enqueues with the
+ * same `batchId` and a persisted `lastEnumerationCursor` once it hits
+ * `tickBudgetMs`. Resume from the cursor is exact (collection +
+ * pagination page), not approximate.
+ *
+ * For `mode: 'canary'`, the coordinator performs full enumeration
+ * (so the candidate pool is the same as `mode: 'changed'` would
+ * scope) and selects N units via random-stratified sampling keyed
+ * on `batchId` for reproducibility.
+ */ export function buildBulkTranslateCoordinator(options = {}) {
+    const batchesSlug = options.batchesCollectionSlug ?? DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG;
+    const unitsSlug = options.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+    const tickBudgetMs = options.tickBudgetMs ?? 25_000;
+    const pageSize = options.pageSize ?? 100;
+    const workerSlug = options.workerTaskSlug ?? BULK_TRANSLATE_DOC_TASK_SLUG;
+    return {
+        slug: BULK_TRANSLATE_COORDINATOR_SLUG,
+        label: 'Bulk translate — coordinator',
+        inputSchema: taskInputSchema,
+        // Coordinator runs are idempotent at the unit level via the partial
+        // unique index. A retry that picks up where the previous tick left
+        // off is fine; a retry from scratch deduplicates via the index.
+        retries: 0,
+        handler: async ({ input, req })=>{
+            const typed = input;
+            const result = await runCoordinatorTick({
+                payload: req.payload,
+                batchId: typed.batchId,
+                batchesSlug,
+                unitsSlug,
+                tickBudgetMs,
+                pageSize,
+                workerSlug
+            });
+            return {
+                output: {
+                    ok: true,
+                    cursor: result.cursor
+                }
+            };
+        }
+    };
+}
+export async function runCoordinatorTick(params) {
+    const { payload, batchId, batchesSlug, unitsSlug, tickBudgetMs, pageSize, workerSlug } = params;
+    const now = params.now ?? (()=>Date.now());
+    const startedAt = now();
+    const batch = await payload.findByID({
+        collection: batchesSlug,
+        id: batchId,
+        overrideAccess: true,
+        depth: 0
+    });
+    if (!batch) {
+        return {
+            cursor: emptyCursor(),
+            unitsCreated: 0,
+            finished: true
+        };
+    }
+    // Terminal states short-circuit. Anything other than `queued` /
+    // `running` means a cancel / completion already happened and the
+    // coordinator must not resurrect it.
+    if (batch.status !== 'queued' && batch.status !== 'running') {
+        return {
+            cursor: batch.lastEnumerationCursor ?? emptyCursor(),
+            unitsCreated: 0,
+            finished: true
+        };
+    }
+    // Soft lease lock (round-5 pr-reviewer blocker #1). Without this
+    // guard, a duplicate coordinator delivery (admin retry, queue
+    // at-least-once semantics, two parallel cron ticks all enqueueing
+    // a trampoline) caused exponential coordinator fan-out: each tick
+    // re-enqueues another, and 2^K coordinators eventually pile up.
+    //
+    // Mechanism: each tick refreshes `coordinatorActiveAt`. A second
+    // coordinator finding the timestamp fresh within the lease window
+    // exits — it assumes the live one will handle the work. The lease
+    // is best-effort, not absolute: worst case two coordinators run
+    // for the lease window, but the partial unique index on units +
+    // the trampoline-skip below prevent duplicate row creation.
+    const COORDINATOR_LEASE_MS = 60_000;
+    const coordinatorActiveAt = batch.coordinatorActiveAt ? new Date(batch.coordinatorActiveAt).getTime() : Number.NEGATIVE_INFINITY;
+    // Lease is "fresh" only when a real timestamp exists AND it's
+    // within the lease window. Unset (`NEGATIVE_INFINITY`) always
+    // fails the check — first tick proceeds normally.
+    if (coordinatorActiveAt > now() - COORDINATOR_LEASE_MS) {
+        payload.logger?.debug?.(`[ai-translate] coordinator: lease still held for batch ${batchId} (last tick ${Math.round((now() - coordinatorActiveAt) / 1000)}s ago) — exiting to avoid fan-out`);
+        return {
+            cursor: batch.lastEnumerationCursor ?? emptyCursor(),
+            unitsCreated: 0,
+            finished: false
+        };
+    }
+    // First-tick transition: queued → running, stamp startedAt.
+    // Same call also refreshes coordinatorActiveAt under the new lease.
+    if (batch.status === 'queued') {
+        await payload.update({
+            collection: batchesSlug,
+            id: batchId,
+            data: {
+                status: 'running',
+                startedAt: new Date().toISOString(),
+                coordinatorActiveAt: new Date().toISOString()
+            },
+            overrideAccess: true
+        });
+    } else {
+        // Already running — just refresh the lease.
+        await payload.update({
+            collection: batchesSlug,
+            id: batchId,
+            data: {
+                coordinatorActiveAt: new Date().toISOString()
+            },
+            overrideAccess: true
+        });
+    }
+    const scope = batch.scope;
+    const cursor = batch.lastEnumerationCursor ?? emptyCursor();
+    let unitsCreated = 0;
+    const overBudget = ()=>now() - startedAt >= tickBudgetMs;
+    // -------------------------------------------------------------------
+    // Phase 1 — collections
+    // -------------------------------------------------------------------
+    if (cursor.phase === 'collections') {
+        const collectionSlugs = filterCollectionSlugs(scope);
+        while(cursor.collectionIndex < collectionSlugs.length){
+            if (overBudget()) {
+                return finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, false, unitsCreated);
+            }
+            const slug = collectionSlugs[cursor.collectionIndex];
+            const fields = getCollectionFields(payload, slug);
+            if (!fields) {
+                cursor.collectionIndex += 1;
+                cursor.page = 1;
+                continue;
+            }
+            const localizedFields = resolveTranslatableFields(fields);
+            // Pagination loop. `documentIds` override short-circuits to a
+            // single targeted read per id rather than walking every page.
+            if (scope.documentIds && scope.documentIds.length > 0) {
+                // Documents-explicit mode: iterate the provided id list. Treat
+                // the same `page` cursor as an index into that list.
+                while(cursor.page <= scope.documentIds.length){
+                    if (overBudget()) {
+                        return finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, false, unitsCreated);
+                    }
+                    const docId = scope.documentIds[cursor.page - 1];
+                    try {
+                        const doc = await payload.findByID({
+                            collection: slug,
+                            id: docId,
+                            locale: scope.sourceLocale,
+                            fallbackLocale: null,
+                            depth: 0,
+                            overrideAccess: true,
+                            draft: true
+                        });
+                        if (doc) {
+                            const created = await enqueueUnitsForDoc({
+                                payload,
+                                batchId,
+                                unitsSlug,
+                                workerSlug,
+                                collection: slug,
+                                doc,
+                                docId: String(doc.id ?? docId),
+                                localizedFields,
+                                scope
+                            });
+                            unitsCreated += created;
+                        }
+                    } catch (err) {
+                        const log = createScopedLogger(payload, {
+                            component: 'bulk.coord',
+                            batchId,
+                            collection: slug,
+                            documentId: docId
+                        });
+                        log.event('warn', 'bulk.coord.docId.fetch.failed', {
+                            err,
+                            collection: slug,
+                            docId
+                        });
+                    // Missing doc id — skip silently. The bulk run records the
+                    // failure as no units for that id rather than aborting the
+                    // entire run on one bad id.
+                    }
+                    cursor.page += 1;
+                }
+                cursor.collectionIndex += 1;
+                cursor.page = 1;
+                continue;
+            }
+            // Standard pagination mode.
+            // eslint-disable-next-line no-constant-condition
+            while(true){
+                if (overBudget()) {
+                    return finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, false, unitsCreated);
+                }
+                const page = await payload.find({
+                    collection: slug,
+                    page: cursor.page,
+                    limit: pageSize,
+                    depth: 0,
+                    locale: scope.sourceLocale,
+                    overrideAccess: true,
+                    draft: true
+                });
+                const docs = page.docs ?? [];
+                for (const doc of docs){
+                    // Skip docs without a usable id. Payload normally guarantees
+                    // `id` for every persisted row, but findMany has been observed
+                    // returning rows with `null` / `undefined` id under specific
+                    // adapter quirks (e.g. soft-deleted drafts). Without this
+                    // guard, `String(null)` becomes the literal string `"null"`
+                    // and the worker later fails the unit with "Not Found".
+                    if (doc.id === null || doc.id === undefined || doc.id === '') {
+                        continue;
+                    }
+                    const created = await enqueueUnitsForDoc({
+                        payload,
+                        batchId,
+                        unitsSlug,
+                        workerSlug,
+                        collection: slug,
+                        doc,
+                        docId: String(doc.id),
+                        localizedFields,
+                        scope
+                    });
+                    unitsCreated += created;
+                }
+                if (!page.hasNextPage) break;
+                cursor.page += 1;
+            }
+            cursor.collectionIndex += 1;
+            cursor.page = 1;
+        }
+        cursor.phase = 'globals';
+        cursor.globalIndex = 0;
+    }
+    // -------------------------------------------------------------------
+    // Phase 2 — globals
+    // -------------------------------------------------------------------
+    if (cursor.phase === 'globals') {
+        const globalSlugs = scope.globals ?? [];
+        while(cursor.globalIndex < globalSlugs.length){
+            if (overBudget()) {
+                return finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, false, unitsCreated);
+            }
+            const slug = globalSlugs[cursor.globalIndex];
+            const fields = getGlobalFields(payload, slug);
+            if (!fields) {
+                cursor.globalIndex += 1;
+                continue;
+            }
+            const localizedFields = resolveTranslatableFields(fields);
+            let doc = null;
+            try {
+                doc = await payload.findGlobal({
+                    slug: slug,
+                    locale: scope.sourceLocale,
+                    fallbackLocale: null,
+                    depth: 0,
+                    overrideAccess: true
+                });
+            } catch (err) {
+                const log = createScopedLogger(payload, {
+                    component: 'bulk.coord',
+                    batchId,
+                    collection: slug
+                });
+                log.event('warn', 'bulk.coord.global.fetch.failed', {
+                    err,
+                    globalSlug: slug
+                });
+                doc = null;
+            }
+            if (doc) {
+                const created = await enqueueUnitsForDoc({
+                    payload,
+                    batchId,
+                    unitsSlug,
+                    workerSlug,
+                    collection: slug,
+                    doc,
+                    // Globals have a fixed identity — use the slug as the
+                    // documentId for the partial unique index. Workers branch
+                    // on collection-vs-global by checking whether the slug
+                    // resolves to a registered global at execution time.
+                    docId: slug,
+                    localizedFields,
+                    scope
+                });
+                unitsCreated += created;
+            }
+            cursor.globalIndex += 1;
+        }
+        cursor.phase = scope.mode === 'canary' ? 'canary' : 'done';
+    }
+    // -------------------------------------------------------------------
+    // Phase 3 — canary sampling
+    // -------------------------------------------------------------------
+    if (cursor.phase === 'canary') {
+        const limit = scope.canaryLimit ?? 10;
+        await applyCanarySampling(payload, batchId, unitsSlug, limit);
+        cursor.phase = 'done';
+    }
+    // -------------------------------------------------------------------
+    // Phase 4 — done: stamp totalUnits.
+    // -------------------------------------------------------------------
+    return finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, true, unitsCreated);
+}
+function emptyCursor() {
+    return {
+        phase: 'collections',
+        collectionIndex: 0,
+        page: 1,
+        globalIndex: 0
+    };
+}
+function filterCollectionSlugs(scope) {
+    const slugs = scope.collections ?? [];
+    const excluded = new Set(scope.excludeCollections ?? []);
+    return slugs.filter((s)=>!excluded.has(s));
+}
+function getCollectionFields(payload, slug) {
+    const collections = payload.config?.collections ?? [];
+    const collection = collections.find((c)=>c.slug === slug);
+    return collection?.fields;
+}
+function getGlobalFields(payload, slug) {
+    const globals = payload.config?.globals ?? [];
+    const global = globals.find((g)=>g.slug === slug);
+    return global?.fields;
+}
+/**
+ * Insert a unit row and queue its worker task for every target locale.
+ * Both ops share a single Payload transaction to close F-DA-TOCTOU
+ * scenario A — the partial unique index commits before the queue is
+ * told to dequeue.
+ *
+ * Returns the number of units actually inserted. Duplicates (already
+ * pending/running for the same (collection, doc, locale)) silently
+ * short-circuit thanks to the partial unique index — a unique-violation
+ * error from the DB is caught and the locale is skipped.
+ */ async function enqueueUnitsForDoc(params) {
+    const { payload, batchId, unitsSlug, workerSlug, collection, doc, docId, localizedFields, scope } = params;
+    let created = 0;
+    // Schema hash ONCE per doc; locale loop reuses. NOTE (v1.2.12): the
+    // coordinator no longer captures `preRunSnapshot` — `doc` here is the
+    // SOURCE-locale enumeration read, and storing its values as "the
+    // pre-run state" for every target-locale unit meant Revert replayed
+    // source-language content over translations (2026-06-11 prod
+    // incident). The worker now captures a true per-locale snapshot just
+    // before its first write (see bulk-translate-doc-task step 3c).
+    let schemaHash;
+    try {
+        schemaHash = hashLocalizedSchema(localizedFields);
+    } catch (err) {
+        payload.logger?.warn?.(`[ai-translate] coordinator: schema hash failed for ${collection}/${docId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    for (const locale of scope.locales){
+        // Same-locale-as-source is a no-op — coordinator skips it to keep
+        // worker logic free of the special case.
+        if (locale === scope.sourceLocale) continue;
+        // Transactional insert + enqueue. Payload's transaction primitive is
+        // `payload.db.beginTransaction()` returning a transactionID; pass
+        // it via `req: { transactionID, ... }` on every op inside the block.
+        // Fall back to non-transactional inserts when the DB adapter doesn't
+        // surface beginTransaction (some adapters return undefined here).
+        const transactionID = await tryBeginTransaction(payload);
+        // Payload's typed Payload.create/update/find APIs accept a `req`
+        // shaped as Partial<PayloadRequest>; we only need `transactionID`
+        // on it for the operations inside this transaction. Construct as
+        // Pick to avoid the double-cast prohibited by CLAUDE.md.
+        const txReq = transactionID ? {
+            transactionID
+        } : undefined;
+        try {
+            // Payload's relationship-field validator expects the FK value in
+            // the same primitive type as the target collection's `id` column.
+            // Our batches table uses `serial` (integer), so the unit's
+            // `batchId` must be a number. The coordinator receives `batchId`
+            // as a string via task input — coerce here to avoid "field is
+            // invalid: Batch Id".
+            const batchIdNumeric = Number.parseInt(batchId, 10);
+            await payload.create({
+                collection: unitsSlug,
+                data: {
+                    batchId: Number.isFinite(batchIdNumeric) ? batchIdNumeric : batchId,
+                    collection,
+                    documentId: docId,
+                    locale,
+                    status: 'pending',
+                    attempts: 0,
+                    schemaHash: schemaHash ?? null
+                },
+                overrideAccess: true,
+                ...txReq ? {
+                    req: txReq
+                } : {}
+            });
+            // The unit row's id is the worker's input. Re-find the row we
+            // just created so we have a stable id to pass through the queue
+            // (Payload's `create` returns the row, but the typings here are
+            // loose — defensive read keeps the call site future-proof).
+            const refind = await payload.find({
+                collection: unitsSlug,
+                where: {
+                    and: [
+                        {
+                            batchId: {
+                                equals: batchId
+                            }
+                        },
+                        {
+                            collection: {
+                                equals: collection
+                            }
+                        },
+                        {
+                            documentId: {
+                                equals: docId
+                            }
+                        },
+                        {
+                            locale: {
+                                equals: locale
+                            }
+                        }
+                    ]
+                },
+                limit: 1,
+                sort: '-createdAt',
+                overrideAccess: true,
+                ...txReq ? {
+                    req: txReq
+                } : {}
+            });
+            const newRow = refind.docs[0];
+            const unitId = newRow?.id ? String(newRow.id) : undefined;
+            if (unitId) {
+                await payload.jobs.queue({
+                    task: workerSlug,
+                    input: {
+                        unitId
+                    },
+                    ...txReq ? {
+                        req: txReq
+                    } : {}
+                });
+            }
+            if (transactionID) {
+                await commitTransaction(payload, transactionID);
+            }
+            // Only count the unit toward `created` if its worker task was
+            // actually queued. If `refind` returned empty (race: row deleted
+            // between create + refind, or adapter quirk returning stale
+            // data), the unit row exists in the DB without a worker task —
+            // it's an orphan that the janitor will eventually rescue, but
+            // the local counter must NOT claim it was enqueued. Without
+            // this guard, totalUnits stamped from the source-of-truth count
+            // would include the orphan and maybeTransitionBatch would
+            // permanently block on the pending row.
+            if (unitId) {
+                created += 1;
+            } else {
+                payload.logger?.error?.(`[ai-translate] coordinator: orphan unit row created for ${collection}/${docId}/${locale} (refind returned empty after create) — janitor will rescue at lease expiry`);
+            }
+        } catch (err) {
+            if (transactionID) {
+                await rollbackTransaction(payload, transactionID).catch(()=>{
+                // Rollback failure logs but doesn't escalate — the partial
+                // unique index keeps us correct even if the rollback was a
+                // no-op against a closed connection.
+                });
+            }
+            // Unique-violation on the partial index is the F-DA-TOCTOU
+            // expected outcome when a concurrent batch already owns this
+            // (collection, doc, locale). Log at debug level only.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/duplicate key|unique constraint|UNIQUE/i.test(msg)) {
+                payload.logger?.debug?.(`[ai-translate] coordinator: skipped duplicate unit ${collection}/${docId}/${locale} (already pending or running)`);
+            } else {
+                payload.logger?.error?.(`[ai-translate] coordinator: failed to enqueue unit ${collection}/${docId}/${locale}: ${msg}`);
+            }
+        }
+    }
+    return created;
+}
+async function tryBeginTransaction(payload) {
+    const db = payload.db;
+    if (typeof db?.beginTransaction === 'function') {
+        try {
+            return await db.beginTransaction();
+        } catch (err) {
+            const log = createScopedLogger(payload, {
+                component: 'bulk.coord'
+            });
+            log.event('error', 'bulk.coord.txn-begin.failed', {
+                err
+            });
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function commitTransaction(payload, transactionID) {
+    const db = payload.db;
+    if (typeof db?.commitTransaction === 'function') {
+        await db.commitTransaction(transactionID);
+    }
+}
+async function rollbackTransaction(payload, transactionID) {
+    const db = payload.db;
+    if (typeof db?.rollbackTransaction === 'function') {
+        await db.rollbackTransaction(transactionID);
+    }
+}
+/**
+ * Random-stratified sampling for canary mode (Decision #26 +
+ * F-DA-CANARY). After full enumeration we have N units across M
+ * collections; we want a `limit`-sized sample with proportional
+ * representation per collection. Selection is deterministic per
+ * `batchId` — re-running the coordinator yields the same canary
+ * sample, which makes the run reproducible for debugging.
+ *
+ * Implementation: bucket the units by collection, sort within each
+ * bucket by a seeded hash, take ceil(limit / M) per bucket up to
+ * the global limit, mark unselected units as `skipped` with reason
+ * `canary_not_sampled` so they don't burn LLM tokens.
+ */ async function applyCanarySampling(payload, batchId, unitsSlug, limit) {
+    // Read all pending units for this batch (post-enumeration). Limit
+    // 10_000 — beyond that the canary semantics don't make sense.
+    const result = await payload.find({
+        collection: unitsSlug,
+        where: {
+            and: [
+                {
+                    batchId: {
+                        equals: batchId
+                    }
+                },
+                {
+                    status: {
+                        equals: 'pending'
+                    }
+                }
+            ]
+        },
+        limit: 10_000,
+        depth: 0,
+        overrideAccess: true
+    });
+    const units = result.docs;
+    // Bucket by collection.
+    const buckets = new Map();
+    for (const u of units){
+        const list = buckets.get(u.collection) ?? [];
+        list.push(u);
+        buckets.set(u.collection, list);
+    }
+    // Seeded shuffle per bucket using a deterministic hash of
+    // `${batchId}:${unitId}`. We don't need cryptographic randomness,
+    // just stable ordering across coordinator retries.
+    const sortedBuckets = [];
+    for (const [collection, list] of buckets){
+        const sorted = [
+            ...list
+        ].sort((a, b)=>{
+            const ha = seededHash(`${batchId}:${a.id}`);
+            const hb = seededHash(`${batchId}:${b.id}`);
+            return ha - hb;
+        });
+        sortedBuckets.push({
+            collection,
+            units: sorted
+        });
+    }
+    sortedBuckets.sort((a, b)=>a.collection.localeCompare(b.collection));
+    if (sortedBuckets.length === 0) return;
+    // Round-robin pull from each bucket until limit reached.
+    const selected = new Set();
+    let cursor = 0;
+    while(selected.size < limit){
+        let pickedThisRound = false;
+        for (const b of sortedBuckets){
+            if (selected.size >= limit) break;
+            if (cursor < b.units.length) {
+                selected.add(b.units[cursor].id);
+                pickedThisRound = true;
+            }
+        }
+        if (!pickedThisRound) break;
+        cursor += 1;
+    }
+    // Mark unselected as skipped.
+    for (const u of units){
+        if (selected.has(u.id)) continue;
+        try {
+            await payload.update({
+                collection: unitsSlug,
+                id: u.id,
+                data: {
+                    status: 'skipped',
+                    failureCode: null,
+                    failureMessage: 'canary_not_sampled',
+                    completedAt: new Date().toISOString()
+                },
+                overrideAccess: true
+            });
+        } catch (err) {
+            payload.logger?.warn?.(`[ai-translate] coordinator: canary skip failed for unit ${u.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function seededHash(s) {
+    // Tiny xorshift-style hash. Deterministic per input string.
+    let h = 2166136261;
+    for(let i = 0; i < s.length; i++){
+        h ^= s.charCodeAt(i);
+        h = h * 16777619 >>> 0;
+    }
+    return h;
+}
+/**
+ * Final step in every tick: persist the cursor + totalUnits, optionally
+ * re-enqueue self if not finished. Returns the cursor state for tests.
+ */ async function finishTick(payload, batchesSlug, unitsSlug, batchId, cursor, finished, unitsCreated) {
+    const update = {
+        lastEnumerationCursor: cursor
+    };
+    if (finished) {
+        // Stamp totalUnits from the source of truth (units collection)
+        // rather than the local counter — the local counter wouldn't
+        // account for duplicates the partial unique index rejected.
+        const countResult = await payload.count({
+            collection: unitsSlug,
+            where: {
+                batchId: {
+                    equals: batchId
+                }
+            },
+            overrideAccess: true
+        });
+        update.totalUnits = countResult.totalDocs;
+        // Release the coordinator lease when we're done — no further
+        // ticks should run for this batch.
+        update.coordinatorActiveAt = null;
+    }
+    await payload.update({
+        collection: batchesSlug,
+        id: batchId,
+        data: update,
+        overrideAccess: true
+    });
+    if (!finished) {
+        // Trampoline: re-enqueue the coordinator for the same batch.
+        // The lease lock at the start of the next tick is what actually
+        // prevents duplicate fan-out — if two trampolines land in the
+        // queue (admin retry, at-least-once delivery), the second one
+        // to run will see the lease still fresh and exit immediately.
+        try {
+            await payload.jobs.queue({
+                task: BULK_TRANSLATE_COORDINATOR_SLUG,
+                input: {
+                    batchId
+                }
+            });
+        } catch (err) {
+            payload.logger?.error?.(`[ai-translate] coordinator: failed to trampoline batch ${batchId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        cursor,
+        unitsCreated,
+        finished
+    };
+}