@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/per-doc-claim.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Per-document serialization via atomic unit claim.
+ *
+ * Replaces the earlier `tryAcquirePerDocLock` (advisory-lock + polling)
+ * which held one Postgres pool connection per acquired lock for the
+ * duration of the worker's translate + write — that starved the
+ * connection pool (e.g. wild-payload-cms's default pool of 10 with
+ * 10 docs in a bulk run → 10 held connections → 0 free → admin UI
+ * + status endpoints stall on the same pool).
+ *
+ * New design: one atomic SQL UPDATE that conditionally transitions
+ * `pending → running` IFF no sibling unit for the same `(collection,
+ * documentId)` is already `running`. Winners proceed with no held
+ * lock and no held connection. Losers see `0 rowsAffected` → caller
+ * re-enqueues this unit's Payload job so a later cron tick retries.
+ *
+ * Trade-off: re-enqueued workers wait until the next `autoRun` tick
+ * to retry (60s on wild-payload-cms). For N locales of one doc, that
+ * means worst-case ~N minutes of cron ticks to fully serialize. Slower
+ * than blocking-poll but doesn't starve the pool — and "slow" here is
+ * still infinitely faster than the previous failure mode (pool stalls
+ * the entire admin).
+ *
+ * Postgres-only — falls through to a "claimed" no-op on non-Postgres
+ * adapters (mongo doesn't have the same upsertRow id-collision race).
+ */
+import type { CollectionSlug, Payload } from 'payload';
+export type ClaimResult = {
+    claimed: true;
+    attempts: number;
+} | {
+    claimed: false;
+    reason: 'sibling_running' | 'not_pending' | 'noop';
+};
+/**
+ * Atomic claim. Runs:
+ *
+ *   UPDATE <units_table>
+ *      SET status='running', started_at=now(), attempts=attempts+1
+ *    WHERE id=$1 AND status='pending'
+ *      AND NOT EXISTS (
+ *        SELECT 1 FROM <units_table>
+ *         WHERE collection=$2 AND document_id=$3
+ *           AND status='running' AND id<>$1
+ *      )
+ *    RETURNING attempts;
+ *
+ * Returns the bumped `attempts` on success so the worker can echo it
+ * into logs without a second read. `0 rows` → either the unit was
+ * already non-pending (terminal/running) or a sibling is running →
+ * caller defers + re-enqueues.
+ *
+ * Falls back to `claimed: false / reason: 'noop'` on non-Postgres so
+ * non-Postgres callers handle the same return shape. (Production
+ * non-Postgres path doesn't need this race protection anyway.)
+ */
+export declare function tryClaimUnitForDoc(args: {
+    payload: Payload;
+    unitsCollectionSlug: string;
+    unitId: string | number;
+    collection: string;
+    documentId: string | number;
+}): Promise<ClaimResult>;
+/**
+ * Convenience wrapper that matches the legacy `tryAcquirePerDocLock`
+ * signature so the worker can drop in without much restructure. Returns
+ * a `release` no-op because the claim's "release" is the worker's
+ * subsequent status update (success/failed/skipped) — which is what
+ * lets the next sibling claim.
+ */
+export type LegacyLockResult = {
+    acquired: true;
+    release: () => Promise<void>;
+    attempts: number;
+} | {
+    acquired: false;
+    release?: undefined;
+} | {
+    acquired: 'noop';
+    release: () => Promise<void>;
+};
+export declare function tryClaimAsLock(args: {
+    payload: Payload;
+    unitsCollectionSlug: string;
+    unitId: string | number;
+    collection: string;
+    documentId: string | number;
+}): Promise<LegacyLockResult>;
+export declare const DEFAULT_UNITS_COLLECTION_SLUG: "bulk-translate-units";
+export type _UnitsCollectionSlugType = CollectionSlug;

package/dist/lib/per-doc-claim.js

@@ -0,0 +1,140 @@
+/**
+ * Per-document serialization via atomic unit claim.
+ *
+ * Replaces the earlier `tryAcquirePerDocLock` (advisory-lock + polling)
+ * which held one Postgres pool connection per acquired lock for the
+ * duration of the worker's translate + write — that starved the
+ * connection pool (e.g. wild-payload-cms's default pool of 10 with
+ * 10 docs in a bulk run → 10 held connections → 0 free → admin UI
+ * + status endpoints stall on the same pool).
+ *
+ * New design: one atomic SQL UPDATE that conditionally transitions
+ * `pending → running` IFF no sibling unit for the same `(collection,
+ * documentId)` is already `running`. Winners proceed with no held
+ * lock and no held connection. Losers see `0 rowsAffected` → caller
+ * re-enqueues this unit's Payload job so a later cron tick retries.
+ *
+ * Trade-off: re-enqueued workers wait until the next `autoRun` tick
+ * to retry (60s on wild-payload-cms). For N locales of one doc, that
+ * means worst-case ~N minutes of cron ticks to fully serialize. Slower
+ * than blocking-poll but doesn't starve the pool — and "slow" here is
+ * still infinitely faster than the previous failure mode (pool stalls
+ * the entire admin).
+ *
+ * Postgres-only — falls through to a "claimed" no-op on non-Postgres
+ * adapters (mongo doesn't have the same upsertRow id-collision race).
+ */ /**
+ * Atomic claim. Runs:
+ *
+ *   UPDATE <units_table>
+ *      SET status='running', started_at=now(), attempts=attempts+1
+ *    WHERE id=$1 AND status='pending'
+ *      AND NOT EXISTS (
+ *        SELECT 1 FROM <units_table>
+ *         WHERE collection=$2 AND document_id=$3
+ *           AND status='running' AND id<>$1
+ *      )
+ *    RETURNING attempts;
+ *
+ * Returns the bumped `attempts` on success so the worker can echo it
+ * into logs without a second read. `0 rows` → either the unit was
+ * already non-pending (terminal/running) or a sibling is running →
+ * caller defers + re-enqueues.
+ *
+ * Falls back to `claimed: false / reason: 'noop'` on non-Postgres so
+ * non-Postgres callers handle the same return shape. (Production
+ * non-Postgres path doesn't need this race protection anyway.)
+ */ export async function tryClaimUnitForDoc(args) {
+    const { payload, unitsCollectionSlug, unitId, collection, documentId } = args;
+    const dbHandle = payload.db;
+    const pool = dbHandle?.pool;
+    if (!pool || typeof pool.connect !== 'function') {
+        // Non-Postgres or no pool — assume the platform doesn't have the
+        // id-collision race and return a successful "noop claim". Worker
+        // proceeds with the legacy mark-running path itself.
+        return {
+            claimed: false,
+            reason: 'noop'
+        };
+    }
+    // Sanitize the table name (slug → table). Slug uses `-`; Postgres
+    // table uses `_`. Single underscore-only alphanumeric guard against
+    // any callsite ever passing something weirder.
+    const tableBase = unitsCollectionSlug.replace(/-/g, '_');
+    if (!/^[a-zA-Z0-9_]+$/.test(tableBase)) {
+        return {
+            claimed: false,
+            reason: 'noop'
+        };
+    }
+    const client = await pool.connect();
+    try {
+        const res = await client.query(`UPDATE "${tableBase}"
+          SET "status" = 'running',
+              "started_at" = now(),
+              "attempts" = COALESCE("attempts", 0) + 1
+        WHERE "id" = $1
+          AND "status" = 'pending'
+          AND NOT EXISTS (
+            SELECT 1 FROM "${tableBase}"
+             WHERE "collection" = $2
+               AND "document_id" = $3
+               AND "status" = 'running'
+               AND "id" <> $1
+          )
+        RETURNING "attempts"`, [
+            unitId,
+            collection,
+            String(documentId)
+        ]);
+        if ((res.rowCount ?? res.rows.length) > 0) {
+            const row = res.rows[0];
+            const attempts = Number(row?.attempts ?? 0);
+            return {
+                claimed: true,
+                attempts
+            };
+        }
+        // Couldn't claim. Disambiguate: is the unit still pending (sibling
+        // running) or was it already non-pending? Helps logs.
+        const statusRes = await client.query(`SELECT "status" FROM "${tableBase}" WHERE "id" = $1`, [
+            unitId
+        ]);
+        const status = statusRes.rows[0]?.status;
+        if (status && status !== 'pending') {
+            return {
+                claimed: false,
+                reason: 'not_pending'
+            };
+        }
+        return {
+            claimed: false,
+            reason: 'sibling_running'
+        };
+    } finally{
+        client.release();
+    }
+}
+export async function tryClaimAsLock(args) {
+    const r = await tryClaimUnitForDoc(args);
+    if (r.claimed) {
+        return {
+            acquired: true,
+            release: async ()=>undefined,
+            attempts: r.attempts
+        };
+    }
+    if (r.reason === 'noop') {
+        return {
+            acquired: 'noop',
+            release: async ()=>undefined
+        };
+    }
+    return {
+        acquired: false
+    };
+}
+// Re-export the units collection slug used by callers (kept here so the
+// caller doesn't need to thread the literal through). Match Payload's
+// default — the consumer can override via plugin config.
+export const DEFAULT_UNITS_COLLECTION_SLUG = 'bulk-translate-units';

package/dist/lib/per-doc-lock.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-document serialization for bulk-translate workers.
+ *
+ * Why this exists: bulk-translate dispatches one Payload job per
+ * `(collection, documentId, locale)` unit. With Payload's `autoRun.limit`
+ * configured for throughput (e.g. 100/min on wild-payload-cms), workers
+ * pick up multiple units for the SAME document in parallel — each
+ * locale gets its own concurrent worker. Their per-locale `payload.update`
+ * calls then collide on shared junction tables (block-id sequences,
+ * richText fragment ids, array junction rows) producing the cryptic
+ * "Value must be unique: id" upsertRow error reproduced in batch #3 of
+ * the 2026-06-04 debug session. Plugin's `concurrency.perDocument: 1`
+ * config only gates the IN-PROCESS `translateDocument()` API and does
+ * NOT cover the bulk-translate worker pool.
+ *
+ * The fix: a per-document Postgres advisory lock. Each worker tries to
+ * acquire `pg_try_advisory_lock(hash(collection || '|' || documentId))`
+ * before processing. The first worker wins; siblings poll briefly,
+ * then either acquire (lock holder finished) or defer (timeout — the
+ * caller re-enqueues the unit so a later cron tick picks it up).
+ *
+ * Postgres-only — Payload's other adapter (mongodb) wouldn't hit the
+ * same upsert race, so a no-op fallback is correct there. We reach
+ * into `payload.db.pool` (`pg.Pool`) directly rather than via the
+ * drizzle handle so we don't need to dynamic-import `drizzle-orm`
+ * (which isn't hoisted in pnpm workspaces and resolves null from the
+ * plugin's own bundle).
+ */
+import type { Payload } from 'payload';
+/**
+ * Minimal `pg.PoolClient` shape we need. Holding the client between
+ * lock acquire and release guarantees the unlock runs on the same
+ * connection — `pg_advisory_lock` is session-scoped, not pool-scoped,
+ * so a release on a different connection is a no-op.
+ */
+type PoolClient = {
+    query: (text: string, values?: unknown[]) => Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    release: () => void;
+};
+type PgPool = {
+    connect: () => Promise<PoolClient>;
+};
+/**
+ * Result of an attempt to acquire the per-doc lock.
+ *   - `acquired: true` — caller proceeds, MUST call `release()` in a
+ *     finally block to release both the lock AND the dedicated pool
+ *     connection.
+ *   - `acquired: false` — timeout reached. Caller should defer (e.g.
+ *     re-enqueue this unit so a future tick picks it up).
+ *   - `acquired: 'noop'` — DB adapter doesn't expose `pool` (e.g.
+ *     mongo). The race this lock prevents is Postgres-specific anyway;
+ *     callers should proceed as if acquired.
+ */
+export type LockResult = {
+    acquired: true;
+    release: () => Promise<void>;
+} | {
+    acquired: false;
+    release?: undefined;
+} | {
+    acquired: 'noop';
+    release: () => Promise<void>;
+};
+export declare function tryAcquirePerDocLock(args: {
+    payload: Payload;
+    collection: string;
+    documentId: string | number;
+    /** Override the default 120s polling deadline. */
+    timeoutMs?: number;
+    /** Test seam: inject a fake sleep so tests don't wait for real time. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Test seam: inject a fake pool. Production resolves `payload.db.pool`
+     * (the `pg.Pool` exposed by `@payloadcms/db-postgres`).
+     */
+    pool?: PgPool;
+}): Promise<LockResult>;
+/**
+ * Map (collection, documentId) → stable signed 64-bit integer Postgres
+ * accepts as `bigint`. Combines two 32-bit FNV-1a hashes into one
+ * positive 53-bit-safe number so the value fits in a JS Number without
+ * precision loss AND lands inside `bigint` range.
+ *
+ * Hash collisions: with N distinct (coll, doc) tuples and 53-bit space,
+ * the birthday-paradox collision probability stays under 1% until
+ * N ≈ 2^26.5 (≈100M). Realistic upper bound for a single bulk-translate
+ * is ~10k docs — collision risk is negligible. If two different docs
+ * DID hash-collide, they'd serialize against each other (perf cost,
+ * not correctness).
+ */
+export declare function lockKeyFor(collection: string, documentId: string | number): string;
+export {};

package/dist/lib/per-doc-lock.js

@@ -0,0 +1,119 @@
+/**
+ * Per-document serialization for bulk-translate workers.
+ *
+ * Why this exists: bulk-translate dispatches one Payload job per
+ * `(collection, documentId, locale)` unit. With Payload's `autoRun.limit`
+ * configured for throughput (e.g. 100/min on wild-payload-cms), workers
+ * pick up multiple units for the SAME document in parallel — each
+ * locale gets its own concurrent worker. Their per-locale `payload.update`
+ * calls then collide on shared junction tables (block-id sequences,
+ * richText fragment ids, array junction rows) producing the cryptic
+ * "Value must be unique: id" upsertRow error reproduced in batch #3 of
+ * the 2026-06-04 debug session. Plugin's `concurrency.perDocument: 1`
+ * config only gates the IN-PROCESS `translateDocument()` API and does
+ * NOT cover the bulk-translate worker pool.
+ *
+ * The fix: a per-document Postgres advisory lock. Each worker tries to
+ * acquire `pg_try_advisory_lock(hash(collection || '|' || documentId))`
+ * before processing. The first worker wins; siblings poll briefly,
+ * then either acquire (lock holder finished) or defer (timeout — the
+ * caller re-enqueues the unit so a later cron tick picks it up).
+ *
+ * Postgres-only — Payload's other adapter (mongodb) wouldn't hit the
+ * same upsert race, so a no-op fallback is correct there. We reach
+ * into `payload.db.pool` (`pg.Pool`) directly rather than via the
+ * drizzle handle so we don't need to dynamic-import `drizzle-orm`
+ * (which isn't hoisted in pnpm workspaces and resolves null from the
+ * plugin's own bundle).
+ */ const POLL_INTERVAL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes worst-case wait per locale
+export async function tryAcquirePerDocLock(args) {
+    const { payload, collection, documentId, timeoutMs = DEFAULT_TIMEOUT_MS, sleep = defaultSleep, pool: poolOverride } = args;
+    const dbHandle = payload.db;
+    const pool = poolOverride ?? dbHandle?.pool;
+    if (!pool || typeof pool.connect !== 'function') {
+        // Non-Postgres adapter — return a noop "lock" that does nothing.
+        // The race this guards against is specific to Payload's Postgres
+        // upsertRow implementation; mongo callers don't need protection.
+        return {
+            acquired: 'noop',
+            release: async ()=>undefined
+        };
+    }
+    const key = lockKeyFor(collection, documentId);
+    const deadline = Date.now() + timeoutMs;
+    while(true){
+        const client = await pool.connect();
+        let acquired = false;
+        try {
+            const r = await client.query('SELECT pg_try_advisory_lock($1::bigint) AS got', [
+                key
+            ]);
+            acquired = Boolean(r.rows[0]?.got);
+            if (acquired) {
+                // Caller holds this client for the duration of their work; the
+                // release closure below issues pg_advisory_unlock on the SAME
+                // client and then returns it to the pool.
+                return {
+                    acquired: true,
+                    release: async ()=>{
+                        try {
+                            await client.query('SELECT pg_advisory_unlock($1::bigint)', [
+                                key
+                            ]);
+                        } catch (err) {
+                            payload.logger?.warn?.(`[ai-translate] per-doc lock release failed for ${collection}/${String(documentId)}: ${String(err)}`);
+                        } finally{
+                            client.release();
+                        }
+                    }
+                };
+            }
+        } finally{
+            if (!acquired) {
+                client.release();
+            }
+        }
+        if (Date.now() >= deadline) {
+            return {
+                acquired: false
+            };
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+// ---------------------------------------------------------------------------
+// Lock-key derivation
+// ---------------------------------------------------------------------------
+/**
+ * Map (collection, documentId) → stable signed 64-bit integer Postgres
+ * accepts as `bigint`. Combines two 32-bit FNV-1a hashes into one
+ * positive 53-bit-safe number so the value fits in a JS Number without
+ * precision loss AND lands inside `bigint` range.
+ *
+ * Hash collisions: with N distinct (coll, doc) tuples and 53-bit space,
+ * the birthday-paradox collision probability stays under 1% until
+ * N ≈ 2^26.5 (≈100M). Realistic upper bound for a single bulk-translate
+ * is ~10k docs — collision risk is negligible. If two different docs
+ * DID hash-collide, they'd serialize against each other (perf cost,
+ * not correctness).
+ */ export function lockKeyFor(collection, documentId) {
+    const input = `${collection}|${String(documentId)}`;
+    const hi = fnv1a(input + '\x00hi') >>> 0;
+    const lo = fnv1a(input + '\x00lo') >>> 0;
+    const combined = BigInt(hi) << 21n ^ BigInt(lo);
+    // Mask to 63 bits so it always fits Postgres signed bigint.
+    const masked = combined & (1n << 63n) - 1n;
+    return masked.toString();
+}
+function fnv1a(str) {
+    let hash = 0x811c9dc5;
+    for(let i = 0; i < str.length; i++){
+        hash ^= str.charCodeAt(i);
+        hash = hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) >>> 0;
+    }
+    return hash >>> 0;
+}
+function defaultSleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}

package/dist/lib/persist-usage.d.ts

@@ -0,0 +1,91 @@
+import type { Payload } from 'payload';
+import type { AITranslatePluginConfig, FieldLocaleResult, SkippedFieldReport, TranslationUsage } from '../types.js';
+export type LocaleOutcome = {
+    locale: string;
+    status: 'succeeded' | 'failed';
+    /** Verbatim provider error from the first failed field for this locale. */
+    error?: string;
+    /**
+     * Editor-facing code for the first failed field's error. The UI keys
+     * off this for the per-locale outcome chip in the UsageTable expanded
+     * row, rendering a friendly message via `editorMessageFor(code)`
+     * instead of dumping the raw provider error. Optional on legacy rows.
+     */
+    errorCode?: string;
+    /** Field paths that failed in this locale. */
+    failedFields?: string[];
+};
+export type PersistUsageInput = {
+    payload: Payload;
+    config: AITranslatePluginConfig;
+    kind: 'collection' | 'global';
+    /** Collection slug or global slug. */
+    slug: string;
+    /** For globals this equals slug. */
+    documentId: string | number;
+    jobId: string;
+    status: 'succeeded' | 'failed';
+    sourceLocale: string;
+    /**
+     * Per-locale results. Each entry records whether the locale succeeded and
+     * (if it failed) the provider error + which field paths failed. Drives
+     * the per-locale subarray on `translation-usage` rows so admins can see
+     * which locale broke without correlating against logs.
+     */
+    localeOutcomes: LocaleOutcome[];
+    /** Field × locale result counts (matches the event's fields[] length). */
+    succeededCount: number;
+    failedCount: number;
+    /**
+     * Field-locale entries marked `success`. Split into "actually called
+     * the LLM" vs "hash-skipped because source content was unchanged" via
+     * `characterCount === 0 && durationMs === 0` — translate-for-locale
+     * pushes hash-skipped entries with zero counts (see translate.ts:187).
+     * Used to populate the breakdown columns on translation-usage so the
+     * Hub can distinguish a real translation from a no-op pass.
+     */
+    succeeded: FieldLocaleResult[];
+    /**
+     * Field-locale entries the manual-edit guard kept out of the write.
+     * NOT in `event.fields[]` (which is succeeded + failed only) — the
+     * caller threads these in directly from TranslateDocumentResult.
+     */
+    preserved: FieldLocaleResult[];
+    /**
+     * Soft-skipped fields (LLM echoed source verbatim or returned invalid
+     * output). One row per field × locale with the validator's reason.
+     * Stored as a sidecar array on the usage row so editors can audit
+     * which fields silently stayed in source.
+     */
+    softSkippedFields: SkippedFieldReport[];
+    usage: TranslationUsage;
+    durationMs?: number;
+    error?: string;
+};
+/**
+ * Bucket a flat `[allSucceeded, hardFailed]` result list into per-locale
+ * outcomes. Used by both the collection and global persistence call sites.
+ *
+ * Only HARD failures (`status: 'failed'` — provider/schema errors) drive
+ * a locale to `status: 'failed'`. Soft skips (`status: 'skipped'` — echo,
+ * length-ratio, placeholder integrity) are filtered out defensively here:
+ * they're surfaced separately via `softSkippedFields` on the usage row and
+ * must never appear in a locale's `failedFields` list (otherwise the Hub
+ * renders the same field twice — once under a red "Failed fields" header
+ * and once under amber "Soft-skipped fields" — with a misleading
+ * "Something went wrong" banner for a locale that didn't actually fail).
+ */
+export declare function bucketLocaleOutcomes(targetLocales: string[], succeeded: FieldLocaleResult[], failed: FieldLocaleResult[]): LocaleOutcome[];
+/**
+ * Write a translation-usage row after a job completes. No-op when the
+ * feature is disabled. Errors from `payload.create` are caught and logged —
+ * usage tracking must never break a translation that already produced
+ * content for the user.
+ *
+ * Sets `REENTRY_FLAG` on the create context so the write does not retrigger
+ * the auto-translate hook (which gates on it via `hooks/after-change.ts`)
+ * or the audit-log cascade guard. A second flag,
+ * `USAGE_TRACKING_CONTEXT_FLAG`, is provided for future hooks that need to
+ * single-out usage writes specifically.
+ */
+export declare function persistTranslationUsage(input: PersistUsageInput): Promise<void>;

package/dist/lib/persist-usage.js

@@ -0,0 +1,116 @@
+import { DEFAULT_USAGE_COLLECTION_SLUG, REENTRY_FLAG, USAGE_TRACKING_CONTEXT_FLAG } from '../defaults.js';
+/**
+ * Bucket a flat `[allSucceeded, hardFailed]` result list into per-locale
+ * outcomes. Used by both the collection and global persistence call sites.
+ *
+ * Only HARD failures (`status: 'failed'` — provider/schema errors) drive
+ * a locale to `status: 'failed'`. Soft skips (`status: 'skipped'` — echo,
+ * length-ratio, placeholder integrity) are filtered out defensively here:
+ * they're surfaced separately via `softSkippedFields` on the usage row and
+ * must never appear in a locale's `failedFields` list (otherwise the Hub
+ * renders the same field twice — once under a red "Failed fields" header
+ * and once under amber "Soft-skipped fields" — with a misleading
+ * "Something went wrong" banner for a locale that didn't actually fail).
+ */ export function bucketLocaleOutcomes(targetLocales, succeeded, failed) {
+    return targetLocales.map((locale)=>{
+        const localeFailures = failed.filter((f)=>f.locale === locale && f.status === 'failed');
+        if (localeFailures.length === 0) {
+            return {
+                locale,
+                status: 'succeeded'
+            };
+        }
+        return {
+            locale,
+            status: 'failed',
+            // Use the first failure's error as the headline. Field-level details
+            // are in `failedFields`; consumers wanting more should query the
+            // `failed` event payload at runtime or extend this shape.
+            error: localeFailures[0]?.error,
+            errorCode: localeFailures[0]?.errorCode,
+            failedFields: localeFailures.map((f)=>f.fieldPath)
+        };
+    });
+}
+/**
+ * Write a translation-usage row after a job completes. No-op when the
+ * feature is disabled. Errors from `payload.create` are caught and logged —
+ * usage tracking must never break a translation that already produced
+ * content for the user.
+ *
+ * Sets `REENTRY_FLAG` on the create context so the write does not retrigger
+ * the auto-translate hook (which gates on it via `hooks/after-change.ts`)
+ * or the audit-log cascade guard. A second flag,
+ * `USAGE_TRACKING_CONTEXT_FLAG`, is provided for future hooks that need to
+ * single-out usage writes specifically.
+ */ export async function persistTranslationUsage(input) {
+    const tracking = input.config.usageTracking;
+    if (!tracking?.enabled) return;
+    const slug = tracking.collectionSlug ?? DEFAULT_USAGE_COLLECTION_SLUG;
+    // Hash-skipped entries are the `success` rows pushed by translate.ts
+    // when sourceHash === lastSourceHash → no LLM call was made. They're
+    // identified by characterCount === 0 && durationMs === 0. Split the
+    // succeeded bucket so the Hub can show "X translated · Y skipped".
+    let fieldsTranslated = 0;
+    let fieldsHashSkipped = 0;
+    for (const r of input.succeeded){
+        const noWork = (r.characterCount ?? 0) === 0 && (r.durationMs ?? 0) === 0;
+        if (noWork) fieldsHashSkipped++;
+        else fieldsTranslated++;
+    }
+    const fieldsPreserved = input.preserved.length;
+    const fieldsSoftSkipped = input.softSkippedFields.length;
+    try {
+        await input.payload.create({
+            collection: slug,
+            data: {
+                kind: input.kind,
+                jobId: input.jobId,
+                slug: input.slug,
+                documentId: String(input.documentId),
+                status: input.status,
+                sourceLocale: input.sourceLocale,
+                targetLocales: input.localeOutcomes.map((o)=>({
+                        locale: o.locale,
+                        status: o.status,
+                        error: o.error ?? null,
+                        errorCode: o.errorCode ?? null,
+                        failedFields: (o.failedFields ?? []).map((p)=>({
+                                path: p
+                            }))
+                    })),
+                succeededCount: input.succeededCount,
+                failedCount: input.failedCount,
+                fieldsTranslated,
+                fieldsHashSkipped,
+                fieldsPreserved,
+                fieldsSoftSkipped,
+                softSkippedFields: input.softSkippedFields.map((s)=>({
+                        path: s.fieldPath,
+                        locale: s.locale,
+                        reason: s.reason ?? null,
+                        reasonCode: s.reasonCode ?? null,
+                        sourceValue: s.sourceValue ?? null
+                    })),
+                preservedFields: input.preserved.map((p)=>({
+                        path: p.fieldPath,
+                        locale: p.locale
+                    })),
+                inputTokens: input.usage.inputTokens,
+                outputTokens: input.usage.outputTokens,
+                estimatedCostUsd: input.usage.estimatedCostUsd ?? null,
+                model: input.usage.model ?? null,
+                durationMs: input.durationMs ?? null,
+                error: input.error ?? null
+            },
+            context: {
+                [USAGE_TRACKING_CONTEXT_FLAG]: true,
+                [REENTRY_FLAG]: true
+            },
+            overrideAccess: true
+        });
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown persistence error';
+        input.payload.logger.error(`[ai-translate] Failed to persist translation usage for job ${input.jobId}: ${msg}`);
+    }
+}