@focus-reactive/payload-plugin-translator 0.6.2 → 0.7.0

package/README.md

@@ -141,6 +141,8 @@ Allowed on **`text`, `textarea`, and `richText`** fields (a compile error on oth
 | `access`              | `AccessGuard`         | No       | `undefined`                            | Access guard (`{ check }`) for the translation endpoints; omit to leave them open.                             |
 | `basePath`            | `string`              | No       | `'/translate'`                         | Base path for the plugin's API endpoints.                                                                      |
 | `levels`              | `TranslationLevel[]`  | No       | `[documentLevel(), collectionLevel()]` | Which surfaces to enable — see [Translation surfaces](#translation-surfaces-levels).                           |
+| `provenance`          | `boolean \| { slug?: string }` | No | `false` (disabled) | Opt in to recording a provenance record per translation. _Since v0.7.0._ See [Provenance](#provenance-opt-in) below. |
+| `lifecycle`           | `{ onQueued?, onCompleted?, onFailed? }` | No | `undefined` | Server-side callbacks fired around each task. _Since v0.7.0._ See [Lifecycle callbacks](#lifecycle-callbacks). |
 
 ```typescript
 translatorPlugin({
@@ -151,6 +153,59 @@ translatorPlugin({
 });
 ```
 
+### Provenance (opt-in)
+
+_Since v0.7.0._
+
+Set `provenance: true` (or `{}`) to record, after each successful translation, a durable per-locale
+provenance entry — what source state a translation was derived from. Use `{ slug }` to customise the
+sidecar collection's slug (default `'translator-provenance'`), e.g. to resolve a name collision with
+one of your own collections. Omit (or set `false`) to leave everything as-is: no collection, no
+migration, no behavior change.
+
+Enabling it adds a plugin-managed, hidden sidecar collection to your config. **On a SQL database
+(Postgres/SQLite) this requires a migration** — run `payload migrate:create` then `payload migrate`
+(or let dev push apply it in development). MongoDB infers the collection with no migration step.
+
+When a translated document is deleted, its provenance rows are cleaned up automatically (across all
+locales). The cleanup is best-effort — a failure is logged and never blocks the delete. The exported
+`TranslationProvenanceRecord` type describes a stored row if you query the sidecar collection directly.
+
+```typescript
+translatorPlugin({
+  collections: [Posts, Pages],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+  provenance: true, // or { slug: "my-provenance" }
+});
+```
+
+### Lifecycle callbacks
+
+_Since v0.7.0._
+
+Optional server-side hooks fired around each translation task — for logging, notifications, cache
+invalidation, or feeding a dashboard. They need no schema or migration and are independent of the
+`provenance` opt-in. Each receives a `TranslationTask` descriptor
+(`{ collection, id, sourceLng, targetLng, strategy }`); `onFailed` also receives the error.
+
+A callback that throws is caught and logged — it never fails the translation. `onCompleted` /
+`onFailed` fire per execution attempt (the Payload Jobs runner may retry a failed task); `onQueued`
+fires once at enqueue.
+
+```typescript
+translatorPlugin({
+  collections: [Posts, Pages],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+  lifecycle: {
+    onQueued: (task) => console.log("queued", task),
+    onCompleted: (task) => console.log("done", task),
+    onFailed: (task, error) => console.error("failed", task, error),
+  },
+});
+```
+
 ### Providers
 
 #### OpenAI (built in) — `createOpenAIProvider(config)`

package/dist/core/content-projection/computeSourceFingerprint.d.ts

@@ -0,0 +1,15 @@
+import type { FieldLike } from "../field-traversal";
+/**
+ * The staleness baseline: a stable hash of a document's translatable content.
+ * `CURRENT = computeSourceFingerprint(sourceDoc, schema)` — the value provenance stores at translation
+ * time and #50 recomputes to detect source drift. A named composition of
+ * {@link projectTranslatableContent} + {@link fingerprint} so the "how to fingerprint source content"
+ * contract lives in one place (callers don't re-wire the two primitives). Reorder-invariant and
+ * text-nodes-only, inheriting those properties from its parts.
+ *
+ * @param doc - The source document to fingerprint (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema.
+ * @returns A hex sha256 digest of the projected translatable content.
+ * @since 0.7.0
+ */
+export declare function computeSourceFingerprint(doc: Record<string, unknown>, schema: FieldLike[]): string;

package/dist/core/content-projection/computeSourceFingerprint.js

@@ -0,0 +1,19 @@
+import { projectTranslatableContent } from "./contentProjector";
+import { fingerprint } from "./fingerprinter";
+/**
+ * The staleness baseline: a stable hash of a document's translatable content.
+ * `CURRENT = computeSourceFingerprint(sourceDoc, schema)` — the value provenance stores at translation
+ * time and #50 recomputes to detect source drift. A named composition of
+ * {@link projectTranslatableContent} + {@link fingerprint} so the "how to fingerprint source content"
+ * contract lives in one place (callers don't re-wire the two primitives). Reorder-invariant and
+ * text-nodes-only, inheriting those properties from its parts.
+ *
+ * @param doc - The source document to fingerprint (never mutated).
+ * @param schema - The ORIGINAL (un-sanitized) field schema.
+ * @returns A hex sha256 digest of the projected translatable content.
+ * @since 0.7.0
+ */ export function computeSourceFingerprint(doc, schema) {
+    return fingerprint(projectTranslatableContent(doc, schema));
+}
+
+//# sourceMappingURL=computeSourceFingerprint.js.map

package/dist/core/index.d.ts

@@ -1,9 +1,11 @@
 export type { TranslationProvider, TranslationInput, TranslationOutput, TranslationIndex, } from "./translation-providers";
 export { TranslationPipeline, translateContent } from "./translation-pipeline";
 export type { TranslateContentArgs, TranslationStrategy } from "./translation-pipeline";
+export type { ProvenanceKey, ProvenanceStore, TranslationProvenanceRecord } from "./provenance";
 export { projectTranslatableContent } from "./content-projection/contentProjector";
 export type { ProjectionEntry } from "./content-projection/contentProjector";
 export { fingerprint } from "./content-projection/fingerprinter";
+export { computeSourceFingerprint } from "./content-projection/computeSourceFingerprint";
 export { makeIdPath } from "./content-projection/idPath";
 export type { IdPath, PathSegment } from "./content-projection/idPath";
 export { classifyField, findFieldByPath, hasFields, isBlockItem, isTabsField, matchElementById, resolveBlockFields, tabScopes, walkFields, } from "./field-traversal";

package/dist/core/index.js

@@ -7,6 +7,7 @@ export { TranslationPipeline, translateContent } from "./translation-pipeline";
 // Content projection
 export { projectTranslatableContent } from "./content-projection/contentProjector";
 export { fingerprint } from "./content-projection/fingerprinter";
+export { computeSourceFingerprint } from "./content-projection/computeSourceFingerprint";
 export { makeIdPath } from "./content-projection/idPath";
 // Field traversal
 export { classifyField, findFieldByPath, hasFields, isBlockItem, isTabsField, matchElementById, resolveBlockFields, tabScopes, walkFields } from "./field-traversal";

package/dist/core/provenance/ProvenanceStore.interface.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Translation provenance — the durable record of *what source state a target locale was translated
+ * from* (design: `docs/plans/2026-06-26-translation-provenance-and-lifecycle-design.md`).
+ *
+ * These are framework-agnostic contracts: plain data plus a storage port, with no Payload types, so
+ * they live in the core. Only the Payload-backed implementation of {@link ProvenanceStore} (in the
+ * plugin adapter) knows about Payload.
+ */
+/**
+ * One provenance receipt: a single `(collection, document, target locale)` translation.
+ *
+ * `documentId` is always a string (Payload ids may be string or number — callers stringify on the
+ * way in) and `translatedAt` is an ISO-8601 string, so the record shape is stable across databases.
+ *
+ * @since 0.7.0
+ */
+export interface TranslationProvenanceRecord {
+    /** Slug of the translated collection. */
+    collectionSlug: string;
+    /** Stringified id of the translated document. */
+    documentId: string;
+    /** Locale that was written (translated into). */
+    targetLocale: string;
+    /** Locale the translation was derived from. */
+    sourceLocale: string;
+    /**
+     * Fingerprint of the source content at translation time —
+     * `fingerprint(projectTranslatableContent(sourceDoc, schema))`. Staleness (later, in #50) is
+     * `currentSourceFingerprint !== sourceFingerprint`.
+     */
+    sourceFingerprint: string;
+    /** ISO-8601 timestamp of the last successful translation. */
+    translatedAt: string;
+    /**
+     * The source fingerprint an editor acknowledged as "stale but leave it" (#50's dismissable
+     * indicator). `null` until dismissed. Written by #50 — carried here now so no later migration is
+     * needed.
+     */
+    dismissedFingerprint: string | null;
+}
+/**
+ * The composite key that identifies exactly one provenance record. Also the {@link ProvenanceStore}
+ * `upsert`/`find` match key.
+ *
+ * @since 0.7.0
+ */
+export interface ProvenanceKey {
+    /** Slug of the translated collection. */
+    collectionSlug: string;
+    /** Stringified id of the translated document. */
+    documentId: string;
+    /** Locale that was written (translated into). */
+    targetLocale: string;
+}
+/**
+ * Storage port for translation provenance. The core depends only on this interface; the plugin
+ * supplies a Payload-backed implementation. Kept minimal so it maps cleanly onto any store.
+ *
+ * @since 0.7.0
+ *
+ * @example
+ * ```ts
+ * const store: ProvenanceStore = new PayloadProvenanceStore(payload, "translator-provenance");
+ * await store.upsert({
+ *   collectionSlug: "posts",
+ *   documentId: "42",
+ *   targetLocale: "de",
+ *   sourceLocale: "en",
+ *   sourceFingerprint: fp,
+ *   translatedAt: new Date().toISOString(),
+ *   dismissedFingerprint: null,
+ * });
+ * const record = await store.find({ collectionSlug: "posts", documentId: "42", targetLocale: "de" });
+ * ```
+ */
+export interface ProvenanceStore {
+    /**
+     * Create the record, or update it in place if one already exists for its
+     * `(collectionSlug, documentId, targetLocale)` key. Never produces a duplicate for the same key.
+     *
+     * @param record - The provenance receipt to persist.
+     */
+    upsert(record: TranslationProvenanceRecord): Promise<void>;
+    /**
+     * Look up the record for a key.
+     *
+     * @param key - The `(collectionSlug, documentId, targetLocale)` identity.
+     * @returns The stored record, or `null` if none exists.
+     */
+    find(key: ProvenanceKey): Promise<TranslationProvenanceRecord | null>;
+    /**
+     * Delete every record for a document (all target locales). Used to cascade-clean when the source
+     * document is deleted.
+     *
+     * @param collectionSlug - Slug of the deleted document's collection.
+     * @param documentId - Stringified id of the deleted document.
+     */
+    deleteByDocument(collectionSlug: string, documentId: string): Promise<void>;
+}

package/dist/core/provenance/ProvenanceStore.interface.js

@@ -0,0 +1,37 @@
+/**
+ * Translation provenance — the durable record of *what source state a target locale was translated
+ * from* (design: `docs/plans/2026-06-26-translation-provenance-and-lifecycle-design.md`).
+ *
+ * These are framework-agnostic contracts: plain data plus a storage port, with no Payload types, so
+ * they live in the core. Only the Payload-backed implementation of {@link ProvenanceStore} (in the
+ * plugin adapter) knows about Payload.
+ */ /**
+ * One provenance receipt: a single `(collection, document, target locale)` translation.
+ *
+ * `documentId` is always a string (Payload ids may be string or number — callers stringify on the
+ * way in) and `translatedAt` is an ISO-8601 string, so the record shape is stable across databases.
+ *
+ * @since 0.7.0
+ */ /**
+ * Storage port for translation provenance. The core depends only on this interface; the plugin
+ * supplies a Payload-backed implementation. Kept minimal so it maps cleanly onto any store.
+ *
+ * @since 0.7.0
+ *
+ * @example
+ * ```ts
+ * const store: ProvenanceStore = new PayloadProvenanceStore(payload, "translator-provenance");
+ * await store.upsert({
+ *   collectionSlug: "posts",
+ *   documentId: "42",
+ *   targetLocale: "de",
+ *   sourceLocale: "en",
+ *   sourceFingerprint: fp,
+ *   translatedAt: new Date().toISOString(),
+ *   dismissedFingerprint: null,
+ * });
+ * const record = await store.find({ collectionSlug: "posts", documentId: "42", targetLocale: "de" });
+ * ```
+ */ export { };
+
+//# sourceMappingURL=ProvenanceStore.interface.js.map

package/dist/core/provenance/index.d.ts

@@ -0,0 +1 @@
+export type { ProvenanceKey, ProvenanceStore, TranslationProvenanceRecord, } from "./ProvenanceStore.interface";

package/dist/core/provenance/index.js

@@ -0,0 +1,5 @@
+// Provenance contracts (port + record types) only — payload-free. The Payload-backed store lives
+// in the plugin (src/server/modules/provenance), outside the core.
+export { };
+
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { translatorPlugin } from "./plugin";
 export type { TranslatorPluginConfig } from "./plugin";
+export type { TranslationTask, TranslationLifecycleCallbacks } from "./server/modules/lifecycle";
+export type { TranslationProvenanceRecord } from "./core";
 export type { AccessGuard, AccessGuardRequest } from "./types/AccessGuard";
 export type { TranslationProvider, TranslationInput, TranslationOutput } from "./core";
 export { createOpenAIProvider } from "./translation-providers";

package/dist/plugin.d.ts

@@ -2,6 +2,7 @@ import type { CollectionConfig, Config } from "payload";
 import type { AccessGuard } from "./types/AccessGuard";
 import type { TranslationProvider } from "./core/translation-providers";
 import type { TaskRunnerProvider } from "./server/modules/task-runner";
+import type { TranslationLifecycleCallbacks } from "./server/modules/lifecycle";
 import type { TranslationLevel } from "./server/modules/translation-levels";
 export type TranslatorPluginConfig = {
     /**
@@ -43,6 +44,31 @@ export type TranslatorPluginConfig = {
      * @since 0.5.0
      */
     levels?: TranslationLevel[];
+    /**
+     * Opt-in translation provenance — a durable, per-locale record of what source state each
+     * translation was derived from, stored in a plugin-managed sidecar collection. Set `true` (or `{}`)
+     * to enable with the default slug, or `{ slug }` to customise it. Omit (or `false`) to disable
+     * entirely — no collection, no migration, no behaviour change. **Enabling it on a SQL database adds
+     * a table**: generate and run a migration (`payload migrate:create` + `payload migrate`; dev push in
+     * development; MongoDB infers it with no migration). The lifecycle callbacks are unaffected by this
+     * flag.
+     * @since 0.7.0
+     */
+    provenance?: boolean | {
+        /**
+         * Slug for the sidecar collection. Change it only to resolve a collision with an existing
+         * collection.
+         * @default 'translator-provenance'
+         */
+        slug?: string;
+    };
+    /**
+     * Optional server-side lifecycle callbacks fired around each translation task
+     * (`onQueued` / `onCompleted` / `onFailed`). Always available — no schema, no migration, not gated
+     * by `provenance`. A throwing callback is caught and logged, never failing the translation.
+     * @since 0.7.0
+     */
+    lifecycle?: TranslationLifecycleCallbacks;
 };
 /** @deprecated Use `TranslatorPluginConfig` instead */
 export type TranslateCollectionPluginConfig = TranslatorPluginConfig;

package/dist/plugin.js

@@ -1,8 +1,19 @@
 import { CacheProviderExport } from "./client/app/cache/CacheProvider.export";
+import { DEFAULT_PROVENANCE_SLUG, PayloadProvenanceStore, assertProvenanceSlugFree, injectProvenanceCleanup, isProvenanceCollection, makeProvenanceCollection } from "./server/modules/provenance";
 import { TranslateDocumentHandler } from "./server/features/translate-document";
+import { LifecycleNotifier, taskFromHandlerInput, withQueuedNotification } from "./server/modules/lifecycle";
 import { documentLevel, collectionLevel } from "./composition/levels";
 import { PluginConfigBuilder } from "./server/modules/translation-levels/PluginConfigBuilder";
 import { normalizePath } from "./server/shared";
+/**
+ * Resolve the opt-in `provenance` config to a sidecar slug, or `null` when disabled.
+ * `false`/omitted → off; `true` or `{}` → on with the default slug; `{ slug }` → on with that slug.
+ */ function resolveProvenanceSlug(provenance) {
+    if (!provenance) return null;
+    if (provenance === true) return DEFAULT_PROVENANCE_SLUG;
+    // `||` (not `??`) so an empty/blank slug falls back to the default instead of silently disabling.
+    return provenance.slug || DEFAULT_PROVENANCE_SLUG;
+}
 /** @deprecated Use `translatorPlugin` function instead */ export class TranslateCollectionPlugin {
     pluginConfig;
     constructor(pluginConfig){
@@ -10,7 +21,8 @@ import { normalizePath } from "./server/shared";
     }
     init() {
         return async (config)=>{
-            const { access, translationProvider, runner, collections, levels, basePath: rawBasePath = "/translate" } = this.pluginConfig;
+            const { access, translationProvider, runner, collections, levels, provenance, lifecycle, basePath: rawBasePath = "/translate" } = this.pluginConfig;
+            const lifecycleCallbacks = lifecycle ?? {};
             // Build schema map from deep-cloned collections
             // Deep clone is required because Payload mutates the original collection objects,
             // removing `localized: true` from nested fields during sanitization.
@@ -25,17 +37,31 @@ import { normalizePath } from "./server/shared";
                 ]));
             const collectionSlugs = new Set(schemaMap.keys());
             const basePath = normalizePath(rawBasePath);
-            const translateHandler = new TranslateDocumentHandler(translationProvider, schemaMap);
+            const provenanceSlug = resolveProvenanceSlug(provenance);
+            if (provenanceSlug) {
+                const existing = (config.collections ?? []).filter((collection)=>!isProvenanceCollection(collection));
+                assertProvenanceSlugFree(provenanceSlug, existing);
+            }
+            const provenanceStoreFactory = provenanceSlug ? (p)=>new PayloadProvenanceStore(p, provenanceSlug) : undefined;
+            const translateHandler = new TranslateDocumentHandler(translationProvider, schemaMap, provenanceStoreFactory);
             const runnerContext = {
                 handler: async (payload, input)=>{
-                    await translateHandler.handle(payload, {
-                        collection: input.collection,
-                        collectionId: input.collectionId,
-                        sourceLng: input.sourceLng,
-                        targetLng: input.targetLng,
-                        strategy: input.strategy,
-                        publishOnTranslation: input.publishOnTranslation
-                    });
+                    const notifier = new LifecycleNotifier(lifecycleCallbacks, payload.logger);
+                    const task = taskFromHandlerInput(input);
+                    try {
+                        await translateHandler.handle(payload, {
+                            collection: input.collection,
+                            collectionId: input.collectionId,
+                            sourceLng: input.sourceLng,
+                            targetLng: input.targetLng,
+                            strategy: input.strategy,
+                            publishOnTranslation: input.publishOnTranslation
+                        });
+                    } catch (error) {
+                        await notifier.failed(task, error);
+                        throw error; // rethrow so the runner marks the job failed
+                    }
+                    await notifier.completed(task);
                 },
                 collections: Array.from(collectionSlugs)
             };
@@ -43,8 +69,13 @@ import { normalizePath } from "./server/shared";
             // Bind the context once so routes receive a self-sufficient factory: the
             // runner needs no mutable per-instance handler state and create() has no
             // "configure() must run first" ordering coupling (translator plan, 0c).
+            // When an `onQueued` callback is set, decorate the runner so `enqueue` fires it.
             const taskRunnerFactory = {
-                create: (payload)=>runner.create(payload, runnerContext.handler)
+                create: (payload)=>{
+                    const taskRunner = runner.create(payload, runnerContext.handler);
+                    if (!lifecycleCallbacks.onQueued) return taskRunner;
+                    return withQueuedNotification(taskRunner, new LifecycleNotifier(lifecycleCallbacks, payload.logger));
+                }
             };
             const activeLevels = levels ?? [
                 documentLevel(),
@@ -59,11 +90,20 @@ import { normalizePath } from "./server/shared";
                 translationProvider
             });
             for (const level of activeLevels)level.extend(builder);
-            // Plugin-level contributions, routed through the same single config-writer:
-            //  - the runner's jobs/autorun/onInit modifier (the builder applies it first,
-            //    so a modifier returning a fresh config object doesn't drop later writes),
-            //  - the always-on client cache provider.
             builder.addConfigModifier(runnerConfigModifier);
+            if (provenanceSlug && provenanceStoreFactory) {
+                builder.addConfigModifier((cfg)=>{
+                    const alreadyAdded = cfg.collections?.some((collection)=>collection.slug === provenanceSlug && isProvenanceCollection(collection));
+                    if (!alreadyAdded) {
+                        cfg.collections = [
+                            ...cfg.collections ?? [],
+                            makeProvenanceCollection(provenanceSlug)
+                        ];
+                    }
+                    injectProvenanceCleanup(cfg, collectionSlugs, provenanceStoreFactory, provenanceSlug);
+                    return cfg;
+                });
+            }
             builder.addAdminProvider(new CacheProviderExport(basePath));
             // The single place the Payload config is mutated.
             return builder.applyTo(config);

package/dist/server/features/translate-document/handler.d.ts

@@ -1,6 +1,7 @@
 import type { Payload } from "payload";
 import type { Handler } from "../../shared";
 import type { TranslationProvider } from "../../../core/translation-providers";
+import type { ProvenanceStoreFactory } from "../../modules/provenance";
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 import type { TranslateDocumentInput, TranslateDocumentOutput } from "./model";
 export type TranslateDocumentDependencies = {
@@ -13,7 +14,8 @@ export type TranslateDocumentDependencies = {
 export declare class TranslateDocumentHandler implements Handler<TranslateDocumentInput, TranslateDocumentOutput> {
     private readonly translationProvider;
     private readonly schemaMap;
-    constructor(translationProvider: TranslationProvider, schemaMap: CollectionSchemaMap);
+    private readonly provenanceStoreFactory?;
+    constructor(translationProvider: TranslationProvider, schemaMap: CollectionSchemaMap, provenanceStoreFactory?: ProvenanceStoreFactory);
     handle(payload: Payload, input: TranslateDocumentInput): Promise<TranslateDocumentOutput>;
     private saveTranslatedDocument;
 }

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

@@ -1,13 +1,16 @@
 import { APIError } from "payload";
 import { translateContent } from "../../../core/translation-pipeline";
+import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
 /**
  * Translates a single document from source language to target language
  */ export class TranslateDocumentHandler {
     translationProvider;
     schemaMap;
-    constructor(translationProvider, schemaMap){
+    provenanceStoreFactory;
+    constructor(translationProvider, schemaMap, provenanceStoreFactory){
         this.translationProvider = translationProvider;
         this.schemaMap = schemaMap;
+        this.provenanceStoreFactory = provenanceStoreFactory;
     }
     async handle(payload, input) {
         const { collection, collectionId, sourceLng, targetLng, strategy, publishOnTranslation } = input;
@@ -41,6 +44,29 @@ import { translateContent } from "../../../core/translation-pipeline";
         };
         const collectionConfig = payload.collections[collection].config;
         await this.saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
+        if (this.provenanceStoreFactory) {
+            const store = this.provenanceStoreFactory(payload);
+            try {
+                await store.upsert({
+                    collectionSlug: collection,
+                    documentId: String(collectionId),
+                    targetLocale: targetLng,
+                    sourceLocale: sourceLng,
+                    sourceFingerprint: computeSourceFingerprint(sourceData, schema),
+                    translatedAt: new Date().toISOString(),
+                    dismissedFingerprint: null
+                });
+            } catch (error) {
+                payload.logger.error({
+                    err: error,
+                    collection,
+                    documentId: String(collectionId),
+                    targetLocale: targetLng,
+                    sourceLocale: sourceLng,
+                    msg: "translator: failed to record translation provenance"
+                });
+            }
+        }
         return {
             success: true
         };

package/dist/server/modules/lifecycle/LifecycleNotifier.d.ts

@@ -0,0 +1,21 @@
+import type { TranslationLifecycleCallbacks, TranslationTask } from "./types";
+/** Minimal logger surface used for swallowed callback errors (Payload's `payload.logger` satisfies it). */
+type LifecycleLogger = {
+    error: (obj: unknown) => void;
+};
+/**
+ * Fires the host's translation lifecycle callbacks, best-effort. Each callback is invoked in a
+ * try/catch (covering both synchronous throws and rejected promises); a failure is logged and
+ * swallowed, never propagated — a broken host callback must not fail the translation. Absent
+ * callbacks are a no-op.
+ */
+export declare class LifecycleNotifier {
+    private readonly callbacks;
+    private readonly logger;
+    constructor(callbacks: TranslationLifecycleCallbacks, logger: LifecycleLogger);
+    queued(task: TranslationTask): Promise<void>;
+    completed(task: TranslationTask): Promise<void>;
+    failed(task: TranslationTask, error: unknown): Promise<void>;
+    private safe;
+}
+export {};

package/dist/server/modules/lifecycle/LifecycleNotifier.js

@@ -0,0 +1,38 @@
+/**
+ * Fires the host's translation lifecycle callbacks, best-effort. Each callback is invoked in a
+ * try/catch (covering both synchronous throws and rejected promises); a failure is logged and
+ * swallowed, never propagated — a broken host callback must not fail the translation. Absent
+ * callbacks are a no-op.
+ */ export class LifecycleNotifier {
+    callbacks;
+    logger;
+    constructor(callbacks, logger){
+        this.callbacks = callbacks;
+        this.logger = logger;
+    }
+    queued(task) {
+        const callback = this.callbacks.onQueued;
+        return this.safe("lifecycle.onQueued", callback && (()=>callback(task)));
+    }
+    completed(task) {
+        const callback = this.callbacks.onCompleted;
+        return this.safe("lifecycle.onCompleted", callback && (()=>callback(task)));
+    }
+    failed(task, error) {
+        const callback = this.callbacks.onFailed;
+        return this.safe("lifecycle.onFailed", callback && (()=>callback(task, error)));
+    }
+    async safe(name, thunk) {
+        if (!thunk) return;
+        try {
+            await thunk();
+        } catch (error) {
+            this.logger.error({
+                err: error,
+                msg: `translator: ${name} callback threw`
+            });
+        }
+    }
+}
+
+//# sourceMappingURL=LifecycleNotifier.js.map

package/dist/server/modules/lifecycle/index.d.ts

@@ -0,0 +1,4 @@
+export { LifecycleNotifier } from "./LifecycleNotifier";
+export { withQueuedNotification } from "./withQueuedNotification";
+export { taskFromHandlerInput, taskFromInput } from "./taskMapping";
+export type { TranslationLifecycleCallbacks, TranslationTask } from "./types";

package/dist/server/modules/lifecycle/index.js

@@ -0,0 +1,7 @@
+// Translation lifecycle callbacks — always-on host hooks fired around the runner (not gated by the
+// provenance opt-in, no schema/migration).
+export { LifecycleNotifier } from "./LifecycleNotifier";
+export { withQueuedNotification } from "./withQueuedNotification";
+export { taskFromHandlerInput, taskFromInput } from "./taskMapping";
+
+//# sourceMappingURL=index.js.map

package/dist/server/modules/lifecycle/taskMapping.d.ts

@@ -0,0 +1,7 @@
+import type { TaskInput } from "../task-runner/types";
+import type { TaskHandlerInput } from "../task-runner/TaskRunnerProvider.interface";
+import type { TranslationTask } from "./types";
+/** Map an enqueue-side {@link TaskInput} to the public {@link TranslationTask}. */
+export declare const taskFromInput: (task: TaskInput) => TranslationTask;
+/** Map an execution-side {@link TaskHandlerInput} to the public {@link TranslationTask}. */
+export declare const taskFromHandlerInput: (input: TaskHandlerInput) => TranslationTask;

package/dist/server/modules/lifecycle/taskMapping.js

@@ -0,0 +1,16 @@
+/** Map an enqueue-side {@link TaskInput} to the public {@link TranslationTask}. */ export const taskFromInput = (task)=>({
+        collection: task.collectionSlug,
+        id: task.collectionId,
+        sourceLng: task.sourceLng,
+        targetLng: task.targetLng,
+        strategy: task.strategy
+    });
+/** Map an execution-side {@link TaskHandlerInput} to the public {@link TranslationTask}. */ export const taskFromHandlerInput = (input)=>({
+        collection: input.collection,
+        id: input.collectionId,
+        sourceLng: input.sourceLng,
+        targetLng: input.targetLng,
+        strategy: input.strategy
+    });
+
+//# sourceMappingURL=taskMapping.js.map

package/dist/server/modules/lifecycle/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Descriptor passed to the lifecycle callbacks — a stable, framework-neutral view of one translation
+ * task. Mirrors the fields the runner already threads through; `publishOnTranslation` is intentionally
+ * omitted (an internal write concern, not lifecycle-relevant). `id` is a string: the plugin is
+ * ID-agnostic and normalizes every document id to a string at ingress.
+ *
+ * @since 0.7.0
+ */
+export type TranslationTask = {
+    collection: string;
+    id: string;
+    sourceLng: string;
+    targetLng: string;
+    /**
+     * The resolution strategy for the task. Deliberately widened to `string` (not the internal
+     * `"overwrite" | "skip_existing"` union) so adding a strategy is not a breaking change to this
+     * public type; host callbacks should treat unknown values gracefully.
+     */
+    strategy: string;
+};
+/**
+ * Optional server-side hooks the host can supply to react to translation lifecycle events, passed as
+ * the plugin's `lifecycle` config object. Always available (no schema, no migration) and independent
+ * of the `provenance` opt-in. A throwing callback never fails the translation — it is caught and
+ * logged (see {@link LifecycleNotifier}).
+ *
+ * `onCompleted` / `onFailed` fire per **execution attempt**: the Payload Jobs runner may retry a
+ * failed task, so a task that fails then succeeds fires `onFailed` on each failed attempt and
+ * `onCompleted` on the one that succeeds. `onQueued` fires once, when the task is enqueued.
+ *
+ * @since 0.7.0
+ */
+export type TranslationLifecycleCallbacks = {
+    /**
+     * Fired for each task as it is queued. Best-effort: emitted just before the task is handed to the
+     * runner, so if enqueueing then throws it may fire for a task that never actually queued.
+     *
+     * @since 0.7.0
+     */
+    onQueued?: (task: TranslationTask) => void | Promise<void>;
+    /** Fired after a task completes without error. @since 0.7.0 */
+    onCompleted?: (task: TranslationTask) => void | Promise<void>;
+    /** Fired when a task's translation throws, with the error. @since 0.7.0 */
+    onFailed?: (task: TranslationTask, error: unknown) => void | Promise<void>;
+};

package/dist/server/modules/lifecycle/types.js

@@ -0,0 +1,21 @@
+/**
+ * Descriptor passed to the lifecycle callbacks — a stable, framework-neutral view of one translation
+ * task. Mirrors the fields the runner already threads through; `publishOnTranslation` is intentionally
+ * omitted (an internal write concern, not lifecycle-relevant). `id` is a string: the plugin is
+ * ID-agnostic and normalizes every document id to a string at ingress.
+ *
+ * @since 0.7.0
+ */ /**
+ * Optional server-side hooks the host can supply to react to translation lifecycle events, passed as
+ * the plugin's `lifecycle` config object. Always available (no schema, no migration) and independent
+ * of the `provenance` opt-in. A throwing callback never fails the translation — it is caught and
+ * logged (see {@link LifecycleNotifier}).
+ *
+ * `onCompleted` / `onFailed` fire per **execution attempt**: the Payload Jobs runner may retry a
+ * failed task, so a task that fails then succeeds fires `onFailed` on each failed attempt and
+ * `onCompleted` on the one that succeeds. `onQueued` fires once, when the task is enqueued.
+ *
+ * @since 0.7.0
+ */ export { };
+
+//# sourceMappingURL=types.js.map

package/dist/server/modules/lifecycle/withQueuedNotification.d.ts

@@ -0,0 +1,9 @@
+import type { TaskRunner } from "../task-runner/TaskRunner.interface";
+import type { LifecycleNotifier } from "./LifecycleNotifier";
+/**
+ * Decorate a {@link TaskRunner} so `enqueue` fires the `queued` lifecycle callback for each task.
+ * Fired BEFORE delegating: a synchronous runner (the sync runner) may execute a task inline during
+ * `enqueue` and fire `completed`, so emitting `queued` first preserves the queued → completed order.
+ * All other methods delegate unchanged.
+ */
+export declare function withQueuedNotification(runner: TaskRunner, notifier: LifecycleNotifier): TaskRunner;

package/dist/server/modules/lifecycle/withQueuedNotification.js

@@ -0,0 +1,19 @@
+import { taskFromInput } from "./taskMapping";
+/**
+ * Decorate a {@link TaskRunner} so `enqueue` fires the `queued` lifecycle callback for each task.
+ * Fired BEFORE delegating: a synchronous runner (the sync runner) may execute a task inline during
+ * `enqueue` and fire `completed`, so emitting `queued` first preserves the queued → completed order.
+ * All other methods delegate unchanged.
+ */ export function withQueuedNotification(runner, notifier) {
+    return {
+        async enqueue (tasks) {
+            await Promise.all(tasks.map((task)=>notifier.queued(taskFromInput(task))));
+            await runner.enqueue(tasks);
+        },
+        cancel: (taskIds)=>runner.cancel(taskIds),
+        run: (taskId)=>runner.run(taskId),
+        findByCollection: (collectionSlug, documentIds)=>runner.findByCollection(collectionSlug, documentIds)
+    };
+}
+
+//# sourceMappingURL=withQueuedNotification.js.map

package/dist/server/modules/provenance/PayloadProvenanceStore.d.ts

@@ -0,0 +1,21 @@
+import type { Payload } from "payload";
+import type { ProvenanceKey, ProvenanceStore, TranslationProvenanceRecord } from "../../../core/provenance";
+/** Builds a provenance store bound to a Payload instance; absent when provenance is disabled. */
+export type ProvenanceStoreFactory = (payload: Payload) => ProvenanceStore;
+/**
+ * Payload-backed {@link ProvenanceStore}. All Payload coupling for provenance lives here; the core
+ * knows only the port. Records are keyed by `(collectionSlug, documentId, targetLocale)`; `upsert`
+ * matches on that key so a re-translation updates the row in place instead of duplicating it.
+ *
+ * The sidecar holds custom fields that no generated collection type describes, so the slug is cast to
+ * `CollectionSlug` once; the record shape is guaranteed by {@link makeProvenanceCollection}.
+ */
+export declare class PayloadProvenanceStore implements ProvenanceStore {
+    private readonly payload;
+    private readonly collection;
+    constructor(payload: Payload, slug: string);
+    upsert(record: TranslationProvenanceRecord): Promise<void>;
+    find(key: ProvenanceKey): Promise<TranslationProvenanceRecord | null>;
+    deleteByDocument(collectionSlug: string, documentId: string): Promise<void>;
+    private findDoc;
+}

package/dist/server/modules/provenance/PayloadProvenanceStore.js

@@ -0,0 +1,109 @@
+function keyWhere(key) {
+    return {
+        and: [
+            {
+                collectionSlug: {
+                    equals: key.collectionSlug
+                }
+            },
+            {
+                documentId: {
+                    equals: key.documentId
+                }
+            },
+            {
+                targetLocale: {
+                    equals: key.targetLocale
+                }
+            }
+        ]
+    };
+}
+function toRecord(doc) {
+    return {
+        collectionSlug: String(doc.collectionSlug),
+        documentId: String(doc.documentId),
+        targetLocale: String(doc.targetLocale),
+        sourceLocale: String(doc.sourceLocale),
+        sourceFingerprint: String(doc.sourceFingerprint),
+        // `translatedAt` is backed by a `date` field, which Payload may hand back as a Date; normalize to
+        // ISO-8601 so the stored contract holds and #50's fingerprint comparison stays format-stable.
+        translatedAt: new Date(doc.translatedAt).toISOString(),
+        dismissedFingerprint: doc.dismissedFingerprint == null ? null : String(doc.dismissedFingerprint)
+    };
+}
+/**
+ * Payload-backed {@link ProvenanceStore}. All Payload coupling for provenance lives here; the core
+ * knows only the port. Records are keyed by `(collectionSlug, documentId, targetLocale)`; `upsert`
+ * matches on that key so a re-translation updates the row in place instead of duplicating it.
+ *
+ * The sidecar holds custom fields that no generated collection type describes, so the slug is cast to
+ * `CollectionSlug` once; the record shape is guaranteed by {@link makeProvenanceCollection}.
+ */ export class PayloadProvenanceStore {
+    payload;
+    collection;
+    constructor(payload, slug){
+        this.payload = payload;
+        this.collection = slug;
+    }
+    async upsert(record) {
+        const existing = await this.findDoc(record);
+        if (existing === null) {
+            try {
+                await this.payload.create({
+                    collection: this.collection,
+                    data: record
+                });
+            } catch (error) {
+                const raceWinner = await this.findDoc(record);
+                if (raceWinner === null) throw error;
+                await this.payload.update({
+                    collection: this.collection,
+                    id: raceWinner.id,
+                    data: record
+                });
+            }
+        } else {
+            await this.payload.update({
+                collection: this.collection,
+                id: existing.id,
+                data: record
+            });
+        }
+    }
+    async find(key) {
+        const doc = await this.findDoc(key);
+        return doc === null ? null : toRecord(doc);
+    }
+    async deleteByDocument(collectionSlug, documentId) {
+        await this.payload.delete({
+            collection: this.collection,
+            where: {
+                and: [
+                    {
+                        collectionSlug: {
+                            equals: collectionSlug
+                        }
+                    },
+                    {
+                        documentId: {
+                            equals: documentId
+                        }
+                    }
+                ]
+            }
+        });
+    }
+    async findDoc(key) {
+        const result = await this.payload.find({
+            collection: this.collection,
+            where: keyWhere(key),
+            limit: 1,
+            depth: 0,
+            pagination: false
+        });
+        return result.docs[0] ?? null;
+    }
+}
+
+//# sourceMappingURL=PayloadProvenanceStore.js.map

package/dist/server/modules/provenance/index.d.ts

@@ -0,0 +1,5 @@
+export { DEFAULT_PROVENANCE_SLUG, isProvenanceCollection, makeProvenanceCollection, } from "./provenanceCollection";
+export { PayloadProvenanceStore } from "./PayloadProvenanceStore";
+export type { ProvenanceStoreFactory } from "./PayloadProvenanceStore";
+export { injectProvenanceCleanup, makeProvenanceCleanupHook } from "./provenanceCleanupHook";
+export { assertProvenanceSlugFree } from "./slugGuard";

package/dist/server/modules/provenance/index.js

@@ -0,0 +1,8 @@
+// Provenance adapter (Payload-backed). The framework-agnostic port + record types live in the core
+// (src/core/provenance); this module is the plugin-side implementation.
+export { DEFAULT_PROVENANCE_SLUG, isProvenanceCollection, makeProvenanceCollection } from "./provenanceCollection";
+export { PayloadProvenanceStore } from "./PayloadProvenanceStore";
+export { injectProvenanceCleanup, makeProvenanceCleanupHook } from "./provenanceCleanupHook";
+export { assertProvenanceSlugFree } from "./slugGuard";
+
+//# sourceMappingURL=index.js.map

package/dist/server/modules/provenance/provenanceCleanupHook.d.ts

@@ -0,0 +1,18 @@
+import type { CollectionAfterDeleteHook, Config } from "payload";
+import type { ProvenanceStoreFactory } from "./PayloadProvenanceStore";
+/**
+ * Build the `afterDelete` hook that cascade-deletes a document's provenance rows for `provenanceSlug`.
+ *
+ * Best-effort by design: the store's delete runs in its own transaction (the store does not thread
+ * `req`), and any failure is swallowed and logged — so cleanup can never roll back or fail the user's
+ * document delete. `id` is `number | string`, so it is stringified to match the stored `documentId`.
+ */
+export declare function makeProvenanceCleanupHook(storeFactory: ProvenanceStoreFactory, provenanceSlug: string): CollectionAfterDeleteHook;
+/**
+ * Attach the provenance cleanup hook to every managed (translatable) collection on `config`, appending
+ * to any consumer-supplied `afterDelete` array. Idempotent per `provenanceSlug`: a collection that
+ * already carries this slug's cleanup hook is skipped, so a repeated `init()` never stacks duplicates,
+ * yet a second instance with a different slug still attaches its own hook. The sidecar collection is
+ * never in `managedSlugs`, so it is never hooked (no recursion).
+ */
+export declare function injectProvenanceCleanup(config: Config, managedSlugs: Set<string>, storeFactory: ProvenanceStoreFactory, provenanceSlug: string): void;

package/dist/server/modules/provenance/provenanceCleanupHook.js

@@ -0,0 +1,41 @@
+/**
+ * Build the `afterDelete` hook that cascade-deletes a document's provenance rows for `provenanceSlug`.
+ *
+ * Best-effort by design: the store's delete runs in its own transaction (the store does not thread
+ * `req`), and any failure is swallowed and logged — so cleanup can never roll back or fail the user's
+ * document delete. `id` is `number | string`, so it is stringified to match the stored `documentId`.
+ */ export function makeProvenanceCleanupHook(storeFactory, provenanceSlug) {
+    const hook = async ({ id, collection, req })=>{
+        try {
+            const store = storeFactory(req.payload);
+            await store.deleteByDocument(collection.slug, String(id));
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                collection: collection.slug,
+                documentId: String(id),
+                msg: "translator: failed to clean up provenance records after document delete"
+            });
+        }
+    };
+    hook.__translatorProvenanceCleanup = provenanceSlug;
+    return hook;
+}
+/**
+ * Attach the provenance cleanup hook to every managed (translatable) collection on `config`, appending
+ * to any consumer-supplied `afterDelete` array. Idempotent per `provenanceSlug`: a collection that
+ * already carries this slug's cleanup hook is skipped, so a repeated `init()` never stacks duplicates,
+ * yet a second instance with a different slug still attaches its own hook. The sidecar collection is
+ * never in `managedSlugs`, so it is never hooked (no recursion).
+ */ export function injectProvenanceCleanup(config, managedSlugs, storeFactory, provenanceSlug) {
+    const hook = makeProvenanceCleanupHook(storeFactory, provenanceSlug);
+    for (const collection of config.collections ?? []){
+        if (!managedSlugs.has(collection.slug)) continue;
+        collection.hooks ??= {};
+        collection.hooks.afterDelete ??= [];
+        const alreadyInjected = collection.hooks.afterDelete.some((existing)=>existing.__translatorProvenanceCleanup === provenanceSlug);
+        if (!alreadyInjected) collection.hooks.afterDelete.push(hook);
+    }
+}
+
+//# sourceMappingURL=provenanceCleanupHook.js.map

package/dist/server/modules/provenance/provenanceCollection.d.ts

@@ -0,0 +1,23 @@
+import type { CollectionConfig } from "payload";
+/** Default slug for the provenance sidecar collection. Overridable via `provenance.slug`. */
+export declare const DEFAULT_PROVENANCE_SLUG = "translator-provenance";
+/**
+ * True for the plugin's own provenance sidecar collection. Recognised by the {@link PROVENANCE_MARKER}
+ * on `custom` (not the slug, which is consumer-configurable), so plugin wiring can stay idempotent on
+ * a repeated run and the slug-collision guard can ignore an already-added sidecar.
+ */
+export declare function isProvenanceCollection(collection: {
+    custom?: unknown;
+}): boolean;
+/**
+ * Build the Payload config for the provenance sidecar collection.
+ *
+ * Deliberately minimal and DB-portable — only `text`/`date` fields and one composite index — so the
+ * same config yields a trivial migration on SQL (Postgres/SQLite) and an inferred collection on
+ * MongoDB. The collection is hidden from the admin UI: it is plugin-managed bookkeeping, not editor
+ * content. The composite index on `(collectionSlug, documentId, targetLocale)` is the upsert key.
+ *
+ * The plugin ships only this config; the consumer's Payload creates the table (see the design doc's
+ * SQL-migration note). Enabled only when the consumer opts in via `provenance` (wired in slice B).
+ */
+export declare function makeProvenanceCollection(slug?: string): CollectionConfig;

package/dist/server/modules/provenance/provenanceCollection.js

@@ -0,0 +1,82 @@
+/** Default slug for the provenance sidecar collection. Overridable via `provenance.slug`. */ export const DEFAULT_PROVENANCE_SLUG = "translator-provenance";
+/** The `custom` marker tagging the plugin's own provenance sidecar (set + read in this module). */ const PROVENANCE_MARKER = "translatorProvenance";
+/**
+ * True for the plugin's own provenance sidecar collection. Recognised by the {@link PROVENANCE_MARKER}
+ * on `custom` (not the slug, which is consumer-configurable), so plugin wiring can stay idempotent on
+ * a repeated run and the slug-collision guard can ignore an already-added sidecar.
+ */ export function isProvenanceCollection(collection) {
+    return collection.custom?.[PROVENANCE_MARKER] === true;
+}
+/**
+ * Build the Payload config for the provenance sidecar collection.
+ *
+ * Deliberately minimal and DB-portable — only `text`/`date` fields and one composite index — so the
+ * same config yields a trivial migration on SQL (Postgres/SQLite) and an inferred collection on
+ * MongoDB. The collection is hidden from the admin UI: it is plugin-managed bookkeeping, not editor
+ * content. The composite index on `(collectionSlug, documentId, targetLocale)` is the upsert key.
+ *
+ * The plugin ships only this config; the consumer's Payload creates the table (see the design doc's
+ * SQL-migration note). Enabled only when the consumer opts in via `provenance` (wired in slice B).
+ */ export function makeProvenanceCollection(slug = DEFAULT_PROVENANCE_SLUG) {
+    return {
+        slug,
+        admin: {
+            hidden: true
+        },
+        // Marker so plugin wiring can recognise its own collection ({@link isProvenanceCollection}) — lets
+        // a repeated plugin run stay idempotent and lets the slug-collision guard ignore its own sidecar.
+        custom: {
+            [PROVENANCE_MARKER]: true
+        },
+        fields: [
+            {
+                name: "collectionSlug",
+                type: "text",
+                required: true,
+                index: true
+            },
+            {
+                name: "documentId",
+                type: "text",
+                required: true,
+                index: true
+            },
+            {
+                name: "targetLocale",
+                type: "text",
+                required: true
+            },
+            {
+                name: "sourceLocale",
+                type: "text",
+                required: true
+            },
+            {
+                name: "sourceFingerprint",
+                type: "text",
+                required: true
+            },
+            {
+                name: "translatedAt",
+                type: "date",
+                required: true
+            },
+            {
+                name: "dismissedFingerprint",
+                type: "text"
+            }
+        ],
+        indexes: [
+            {
+                fields: [
+                    "collectionSlug",
+                    "documentId",
+                    "targetLocale"
+                ],
+                unique: true
+            }
+        ]
+    };
+}
+
+//# sourceMappingURL=provenanceCollection.js.map

package/dist/server/modules/provenance/slugGuard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fail fast if the provenance sidecar slug collides with a collection the consumer already defines.
+ * Sharing a table would silently corrupt both — better a clear startup error telling the consumer to
+ * set `provenance.slug`.
+ *
+ * Compares by exact slug: this catches the common footgun — a consumer collection already using this
+ * slug — and is correct on every adapter (on MongoDB the slug IS the collection name). It does NOT
+ * try to model SQL table-name derivation: `@payloadcms/drizzle` snake-cases slugs and honours
+ * `dbName` overrides, so case/separator variants (`translatorProvenance` vs `translator-provenance`)
+ * or `dbName` collisions are not detected here. Robust table-name collision detection, if it proves
+ * necessary, belongs at plugin init where the full `CollectionConfig` (including `dbName`) is
+ * available — not in this slug-only helper.
+ */
+export declare function assertProvenanceSlugFree(slug: string, collections: ReadonlyArray<{
+    slug: string;
+}>): void;

package/dist/server/modules/provenance/slugGuard.js

@@ -0,0 +1,19 @@
+/**
+ * Fail fast if the provenance sidecar slug collides with a collection the consumer already defines.
+ * Sharing a table would silently corrupt both — better a clear startup error telling the consumer to
+ * set `provenance.slug`.
+ *
+ * Compares by exact slug: this catches the common footgun — a consumer collection already using this
+ * slug — and is correct on every adapter (on MongoDB the slug IS the collection name). It does NOT
+ * try to model SQL table-name derivation: `@payloadcms/drizzle` snake-cases slugs and honours
+ * `dbName` overrides, so case/separator variants (`translatorProvenance` vs `translator-provenance`)
+ * or `dbName` collisions are not detected here. Robust table-name collision detection, if it proves
+ * necessary, belongs at plugin init where the full `CollectionConfig` (including `dbName`) is
+ * available — not in this slug-only helper.
+ */ export function assertProvenanceSlugFree(slug, collections) {
+    if (collections.some((collection)=>collection.slug === slug)) {
+        throw new Error(`[payload-plugin-translator] provenance slug "${slug}" collides with an existing collection. ` + "Set a distinct slug via the plugin's provenance.slug option.");
+    }
+}
+
+//# sourceMappingURL=slugGuard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",