@focus-reactive/payload-plugin-translator 0.8.0 → 0.8.2

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

@@ -10,6 +10,27 @@ import { JobIdSchema, toClientErrorMessage } from "../../shared";
     collection_id: JobIdSchema,
     collection_slug: z.string().nonempty()
 });
+// A job is "newer" by creation time, tie-broken by last update — both ISO-8601, so a lexicographic
+// string compare is a correct chronological compare (no Date parsing needed).
+const isNewerTask = (candidate, current)=>candidate.createdAt !== current.createdAt ? candidate.createdAt > current.createdAt : candidate.updatedAt > current.updatedAt;
+/**
+ * Reduce a document's jobs to the latest one per target locale.
+ *
+ * `findByCollection` returns every job for the document across all target locales (plus any superseded
+ * jobs not yet cancelled). The status panel shows one row per target locale, so we keep — per
+ * `targetLng` — the most recently created job (tie-break: most recently updated). Without this the
+ * caller sees a single arbitrary job and every other in-flight locale looks idle, which is the
+ * concurrent re-translate bug (a second re-translate appearing to overwrite the first's status).
+ */ export function latestTaskPerTargetLocale(tasks) {
+    const byLocale = new Map();
+    for (const task of tasks){
+        const current = byLocale.get(task.input.targetLng);
+        if (!current || isNewerTask(task, current)) byLocale.set(task.input.targetLng, task);
+    }
+    return [
+        ...byLocale.values()
+    ];
+}
 /**
  * Transforms a Task to API output format (snake_case for client compatibility)
  */ export function taskToJobStatusOutput(task) {

package/dist/server/features/staleness/dismissStaleness.handler.js

@@ -1,7 +1,6 @@
 import { ServerResponse } from "../../shared";
 import { isCollectionAvailable } from "../_lib/collection-utils";
 import { DismissStalenessInputSchema } from "./model";
-import { dismissLocaleStaleness } from "./service";
 /** Dismisses (acknowledges) staleness of one target locale for a document. */ export class DismissStalenessHandler {
     config;
     constructor(config){
@@ -17,7 +16,12 @@ import { dismissLocaleStaleness } from "./service";
         if (!collectionSlug) {
             return ServerResponse.badRequest("Collection not available for translation");
         }
-        await dismissLocaleStaleness(req.payload, this.config, collectionSlug, collection_id, target_lng);
+        const service = this.config.provenanceServiceFactory?.(req.payload);
+        await service?.dismiss({
+            collectionSlug: collectionSlug,
+            documentId: collection_id,
+            targetLocale: target_lng
+        });
         return ServerResponse.success({
             success: true
         });

package/dist/server/features/staleness/getDocumentStaleness.handler.js

@@ -1,7 +1,6 @@
 import { ServerResponse } from "../../shared";
 import { isCollectionAvailable } from "../_lib/collection-utils";
 import { GetDocumentStalenessInputSchema } from "./model";
-import { computeDocumentStaleness } from "./service";
 /**
  * Reads per-locale staleness for a single document. Best-effort: a recompute failure (e.g. the
  * consumer enabled provenance but has not run the SQL migration, so the sidecar table is missing)
@@ -22,7 +21,8 @@ import { computeDocumentStaleness } from "./service";
             return ServerResponse.badRequest("Collection not available for translation");
         }
         try {
-            const locales = await computeDocumentStaleness(req.payload, this.config, collectionSlug, collection_id);
+            const service = this.config.provenanceServiceFactory?.(req.payload);
+            const locales = service ? await service.getStaleness(collectionSlug, collection_id) : [];
             return ServerResponse.success({
                 locales
             });

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

@@ -1,2 +1,2 @@
 export { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./route";
-export type { StalenessConfig, StalenessLocaleOutput } from "./model";
+export type { StalenessConfig } from "./model";

package/dist/server/features/staleness/model.d.ts

@@ -1,7 +1,6 @@
 import { z } from "zod";
 import type { CollectionSlug } from "payload";
-import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
-import type { ProvenanceStoreFactory } from "../../modules/provenance";
+import type { TranslationContext } from "../../modules/translation-levels";
 /**
  * Route params for reading a document's per-locale staleness.
  *
@@ -32,21 +31,10 @@ export declare const DismissStalenessInputSchema: z.ZodObject<{
     target_lng: string;
 }>;
 /**
- * Per-locale staleness for one document (snake_case for client compatibility, matching the other
- * translation endpoints). One entry per target locale that has a provenance record.
- */
-export type StalenessLocaleOutput = {
-    target_lng: string;
-    source_lng: string;
-    is_stale: boolean;
-    translated_at: string;
-};
-/**
- * Handler configuration. `provenanceStoreFactory` is absent when provenance is disabled — the
+ * Handler configuration. `provenanceServiceFactory` is absent when provenance is disabled — the
  * handlers then report no staleness (empty), so the endpoint contract stays stable either way.
+ * The fingerprint policy + schema live inside {@link ProvenanceService}, so no `schemaMap` here.
  */
-export type StalenessConfig = {
+export type StalenessConfig = Pick<TranslationContext, "provenanceServiceFactory"> & {
     availableCollections: Set<CollectionSlug>;
-    schemaMap: CollectionSchemaMap;
-    provenanceStoreFactory?: ProvenanceStoreFactory;
 };

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

@@ -1,21 +1,19 @@
 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 { ProvenanceServiceFactory } from "../../modules/provenance";
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 import type { TranslateDocumentInput, TranslateDocumentOutput } from "./model";
-export type TranslateDocumentDependencies = {
-    translationProvider: TranslationProvider;
-    schemaMap: CollectionSchemaMap;
-};
 /**
- * Translates a single document from source language to target language
+ * Translates a single document from source language to target language. Provenance is delegated to
+ * {@link ProvenanceService}: this handler only decides *when* to capture the source fingerprint
+ * (before the pipeline mutates the source in place) and *when* to record it (after the save).
  */
 export declare class TranslateDocumentHandler implements Handler<TranslateDocumentInput, TranslateDocumentOutput> {
     private readonly translationProvider;
     private readonly schemaMap;
-    private readonly provenanceStoreFactory?;
-    constructor(translationProvider: TranslationProvider, schemaMap: CollectionSchemaMap, provenanceStoreFactory?: ProvenanceStoreFactory);
+    private readonly provenanceServiceFactory?;
+    constructor(translationProvider: TranslationProvider, schemaMap: CollectionSchemaMap, provenanceServiceFactory?: ProvenanceServiceFactory);
     handle(payload: Payload, input: TranslateDocumentInput): Promise<TranslateDocumentOutput>;
     private saveTranslatedDocument;
 }

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

@@ -1,17 +1,18 @@
 import { APIError } from "payload";
 import { translateContent } from "../../../core/translation-pipeline";
-import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
-import { fetchSourceDocument } from "../_lib/sourceDocument";
+import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
 /**
- * Translates a single document from source language to target language
+ * Translates a single document from source language to target language. Provenance is delegated to
+ * {@link ProvenanceService}: this handler only decides *when* to capture the source fingerprint
+ * (before the pipeline mutates the source in place) and *when* to record it (after the save).
  */ export class TranslateDocumentHandler {
     translationProvider;
     schemaMap;
-    provenanceStoreFactory;
-    constructor(translationProvider, schemaMap, provenanceStoreFactory){
+    provenanceServiceFactory;
+    constructor(translationProvider, schemaMap, provenanceServiceFactory){
         this.translationProvider = translationProvider;
         this.schemaMap = schemaMap;
-        this.provenanceStoreFactory = provenanceStoreFactory;
+        this.provenanceServiceFactory = provenanceServiceFactory;
     }
     async handle(payload, input) {
         const { collection, collectionId, sourceLng, targetLng, strategy, publishOnTranslation } = input;
@@ -19,24 +20,12 @@ import { fetchSourceDocument } from "../_lib/sourceDocument";
         const schema = this.schemaMap.get(collection);
         if (!schema) throw new APIError(`Collection "${collection}" not found in schemaMap`, 400);
         const sourceData = await fetchSourceDocument(payload, collection, collectionId, sourceLng);
-        // Capture the staleness baseline from the PRISTINE source NOW, before the pipeline runs. The
-        // pipeline translates in place and shares object-valued source leaves (e.g. richText nodes) by
-        // reference with `sourceData`, so fingerprinting after `translateContent` would hash the target
-        // translation — making every fresh translation look immediately stale. Best-effort: a fingerprint
-        // failure logs and skips provenance rather than breaking the translation.
-        let sourceFingerprint = null;
-        if (this.provenanceStoreFactory) {
-            try {
-                sourceFingerprint = computeSourceFingerprint(sourceData, schema);
-            } catch (error) {
-                payload.logger.error({
-                    err: error,
-                    collection,
-                    documentId: String(collectionId),
-                    msg: "translator: failed to fingerprint source for provenance"
-                });
-            }
-        }
+        // Capture the staleness baseline from the PRISTINE source NOW, before the pipeline runs — it
+        // translates in place and shares object-valued source leaves (e.g. richText nodes) by reference,
+        // so fingerprinting after `translateContent` would hash the target translation and make every
+        // fresh translation look instantly stale. The service is best-effort (a failure returns null).
+        const provenance = this.provenanceServiceFactory?.(payload);
+        const sourceFingerprint = provenance?.captureFingerprint(collection, sourceData) ?? null;
         const targetData = await payload.findByID({
             collection,
             id: collectionId,
@@ -58,28 +47,13 @@ import { fetchSourceDocument } from "../_lib/sourceDocument";
         };
         const collectionConfig = payload.collections[collection].config;
         await this.saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
-        if (this.provenanceStoreFactory && sourceFingerprint !== null) {
-            const store = this.provenanceStoreFactory(payload);
-            try {
-                await store.upsert({
-                    collectionSlug: collection,
-                    documentId: String(collectionId),
-                    targetLocale: targetLng,
-                    sourceLocale: sourceLng,
-                    sourceFingerprint,
-                    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"
-                });
-            }
+        if (provenance && sourceFingerprint !== null) {
+            await provenance.record({
+                collectionSlug: collection,
+                documentId: String(collectionId),
+                targetLocale: targetLng,
+                sourceLocale: sourceLng
+            }, sourceFingerprint);
         }
         return {
             success: true

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

@@ -1,2 +1,3 @@
 export { TranslateDocumentHandler } from "./handler";
+export { wireTranslateRunner } from "./wireTranslateRunner";
 export type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";

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

@@ -1,3 +1,4 @@
 export { TranslateDocumentHandler } from "./handler";
+export { wireTranslateRunner } from "./wireTranslateRunner";
 
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,28 @@
+import type { CollectionSlug } from "payload";
+import type { TranslationProvider } from "../../../core/translation-providers";
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+import type { ConfigModifier } from "../../../types/ConfigModifier";
+import type { ProvenanceServiceFactory } from "../../modules/provenance";
+import type { TranslationLifecycleCallbacks } from "../../modules/lifecycle";
+import type { TaskRunnerFactory, TaskRunnerProvider } from "../../modules/task-runner";
+type WireTranslateRunnerParams = {
+    translationProvider: TranslationProvider;
+    schemaMap: CollectionSchemaMap;
+    provenanceServiceFactory?: ProvenanceServiceFactory;
+    runner: TaskRunnerProvider;
+    lifecycle: TranslationLifecycleCallbacks;
+    collections: CollectionSlug[];
+};
+/**
+ * Assemble the document-translation task pipeline: the {@link TranslateDocumentHandler}, the runner
+ * context that wraps each task with lifecycle notifications, the runner's config modifier, and the
+ * per-request {@link TaskRunnerFactory} (decorated with `onQueued` notification when configured).
+ *
+ * Extracted from the plugin's `init()` so the composition root stays a flat list — `plugin.ts` calls
+ * this once and registers the returned `configModifier` through the shared builder.
+ */
+export declare function wireTranslateRunner({ translationProvider, schemaMap, provenanceServiceFactory, runner, lifecycle, collections, }: WireTranslateRunnerParams): {
+    taskRunnerFactory: TaskRunnerFactory;
+    configModifier: ConfigModifier;
+};
+export {};

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

@@ -0,0 +1,49 @@
+import { LifecycleNotifier, taskFromHandlerInput, withQueuedNotification } from "../../modules/lifecycle";
+import { TranslateDocumentHandler } from "./handler";
+/**
+ * Assemble the document-translation task pipeline: the {@link TranslateDocumentHandler}, the runner
+ * context that wraps each task with lifecycle notifications, the runner's config modifier, and the
+ * per-request {@link TaskRunnerFactory} (decorated with `onQueued` notification when configured).
+ *
+ * Extracted from the plugin's `init()` so the composition root stays a flat list — `plugin.ts` calls
+ * this once and registers the returned `configModifier` through the shared builder.
+ */ export function wireTranslateRunner({ translationProvider, schemaMap, provenanceServiceFactory, runner, lifecycle, collections }) {
+    const translateHandler = new TranslateDocumentHandler(translationProvider, schemaMap, provenanceServiceFactory);
+    const runnerContext = {
+        handler: async (payload, input)=>{
+            const notifier = new LifecycleNotifier(lifecycle, 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
+    };
+    // 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.
+    // When an `onQueued` callback is set, decorate the runner so `enqueue` fires it.
+    const taskRunnerFactory = {
+        create: (payload)=>{
+            const taskRunner = runner.create(payload, runnerContext.handler);
+            if (!lifecycle.onQueued) return taskRunner;
+            return withQueuedNotification(taskRunner, new LifecycleNotifier(lifecycle, payload.logger));
+        }
+    };
+    return {
+        taskRunnerFactory,
+        configModifier: runner.configure(runnerContext)
+    };
+}
+
+//# sourceMappingURL=wireTranslateRunner.js.map

package/dist/server/modules/provenance/{provenanceCollection.d.ts → Provenance.collection.d.ts}

@@ -1,14 +1,7 @@
 import type { CollectionConfig } from "payload";
+import type { ManagedCollectionsConfig } from "./Provenance.shapes";
 /** 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.
  *
@@ -18,6 +11,21 @@ export declare function isProvenanceCollection(collection: {
  * 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).
+ * SQL-migration note). Enabled only when the consumer opts in via `provenance`.
  */
 export declare function makeProvenanceCollection(slug?: string): CollectionConfig;
+/**
+ * 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;
+/**
+ * Idempotently register the provenance sidecar collection on `host`: add it once, skipping when a
+ * sidecar with this slug is already present, so a repeated `init()` never stacks a duplicate. Takes
+ * only the narrow {@link ManagedCollectionsConfig} slice — a real Payload `Config` is structurally
+ * assignable, and a test passes a plain `{ collections: [...] }` literal.
+ */
+export declare function ensureProvenanceCollectionRegistered(host: ManagedCollectionsConfig, slug: string): void;

package/dist/server/modules/provenance/{provenanceCollection.js → Provenance.collection.js}

@@ -1,12 +1,5 @@
 /** 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.
  *
@@ -16,7 +9,7 @@
  * 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).
+ * SQL-migration note). Enabled only when the consumer opts in via `provenance`.
  */ export function makeProvenanceCollection(slug = DEFAULT_PROVENANCE_SLUG) {
     return {
         slug,
@@ -78,5 +71,26 @@
         ]
     };
 }
+/**
+ * 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;
+}
+/**
+ * Idempotently register the provenance sidecar collection on `host`: add it once, skipping when a
+ * sidecar with this slug is already present, so a repeated `init()` never stacks a duplicate. Takes
+ * only the narrow {@link ManagedCollectionsConfig} slice — a real Payload `Config` is structurally
+ * assignable, and a test passes a plain `{ collections: [...] }` literal.
+ */ export function ensureProvenanceCollectionRegistered(host, slug) {
+    const alreadyAdded = host.collections?.some((collection)=>collection.slug === slug && isProvenanceCollection(collection));
+    if (!alreadyAdded) {
+        host.collections = [
+            ...host.collections ?? [],
+            makeProvenanceCollection(slug)
+        ];
+    }
+}
 
-//# sourceMappingURL=provenanceCollection.js.map
+//# sourceMappingURL=Provenance.collection.js.map

package/dist/server/modules/provenance/Provenance.service.d.ts

@@ -0,0 +1,56 @@
+import type { CollectionSlug, Payload } from "payload";
+import type { ProvenanceKey, ProvenanceStore } from "../../../core/provenance";
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+/** Per-locale staleness for one document (snake_case, matching the other translation endpoints). */
+export type StalenessLocale = {
+    target_lng: string;
+    source_lng: string;
+    is_stale: boolean;
+    translated_at: string;
+};
+/** Builds a {@link ProvenanceService} bound to a Payload instance; absent when provenance is disabled. */
+export type ProvenanceServiceFactory = (payload: Payload) => ProvenanceService;
+/**
+ * The single owner of provenance fingerprint policy — how the source is hashed on write, re-hashed on
+ * read, and compared for staleness. The write path and the read path go through this one class, so
+ * they can never drift (the biggest correctness trap in staleness detection). Sits above the CRUD
+ * {@link ProvenanceStore} port; the port + `computeSourceFingerprint` + `isRecordStale` stay
+ * framework-agnostic in the core.
+ *
+ * Best-effort by contract: fingerprint/record failures log and no-op rather than failing a translation.
+ */
+export declare class ProvenanceService {
+    private readonly payload;
+    private readonly store;
+    private readonly schemaMap;
+    constructor(payload: Payload, store: ProvenanceStore, schemaMap: CollectionSchemaMap);
+    /**
+     * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
+     * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
+     * it would capture the target translation and make every fresh translation look instantly stale.
+     * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
+     */
+    captureFingerprint(collection: CollectionSlug, sourceData: Record<string, unknown>): string | null;
+    /** Persist a translation receipt (best-effort; a store failure logs and no-ops). */
+    record(key: ProvenanceKey & {
+        sourceLocale: string;
+    }, sourceFingerprint: string): Promise<void>;
+    /**
+     * Per-locale staleness for one document: read every receipt, recompute the current source
+     * fingerprint (write-path-identical), and mark each locale stale on undismissed drift. Returns `[]`
+     * when the collection has no schema. Isolates per-locale failures so one bad record can't blank the rest.
+     */
+    getStaleness(collection: CollectionSlug, documentId: string): Promise<StalenessLocale[]>;
+    /**
+     * Acknowledge the current source drift for one target locale: persist the current fingerprint as the
+     * dismissed one, so the indicator hides until the source changes again. No-op when the collection has
+     * no schema or the locale has no record.
+     */
+    dismiss(key: ProvenanceKey): Promise<void>;
+    /**
+     * Recompute the current source fingerprint the same way the write path does (shared fetch shape +
+     * hash). Cached per source locale so a document translated from one source into N locales fetches
+     * the source once.
+     */
+    private makeCurrentFingerprint;
+}

package/dist/server/modules/provenance/Provenance.service.js

@@ -0,0 +1,124 @@
+import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
+import { isRecordStale } from "../../../core/provenance";
+import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
+/**
+ * The single owner of provenance fingerprint policy — how the source is hashed on write, re-hashed on
+ * read, and compared for staleness. The write path and the read path go through this one class, so
+ * they can never drift (the biggest correctness trap in staleness detection). Sits above the CRUD
+ * {@link ProvenanceStore} port; the port + `computeSourceFingerprint` + `isRecordStale` stay
+ * framework-agnostic in the core.
+ *
+ * Best-effort by contract: fingerprint/record failures log and no-op rather than failing a translation.
+ */ export class ProvenanceService {
+    payload;
+    store;
+    schemaMap;
+    constructor(payload, store, schemaMap){
+        this.payload = payload;
+        this.store = store;
+        this.schemaMap = schemaMap;
+    }
+    /**
+   * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
+   * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
+   * it would capture the target translation and make every fresh translation look instantly stale.
+   * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
+   */ captureFingerprint(collection, sourceData) {
+        const schema = this.schemaMap.get(collection);
+        if (!schema) return null;
+        try {
+            return computeSourceFingerprint(sourceData, schema);
+        } catch (error) {
+            this.payload.logger.error({
+                err: error,
+                collection,
+                msg: "translator: failed to fingerprint source for provenance"
+            });
+            return null;
+        }
+    }
+    /** Persist a translation receipt (best-effort; a store failure logs and no-ops). */ async record(key, sourceFingerprint) {
+        try {
+            await this.store.upsert({
+                collectionSlug: key.collectionSlug,
+                documentId: key.documentId,
+                targetLocale: key.targetLocale,
+                sourceLocale: key.sourceLocale,
+                sourceFingerprint,
+                translatedAt: new Date().toISOString(),
+                dismissedFingerprint: null
+            });
+        } catch (error) {
+            this.payload.logger.error({
+                err: error,
+                collection: key.collectionSlug,
+                documentId: key.documentId,
+                targetLocale: key.targetLocale,
+                sourceLocale: key.sourceLocale,
+                msg: "translator: failed to record translation provenance"
+            });
+        }
+    }
+    /**
+   * Per-locale staleness for one document: read every receipt, recompute the current source
+   * fingerprint (write-path-identical), and mark each locale stale on undismissed drift. Returns `[]`
+   * when the collection has no schema. Isolates per-locale failures so one bad record can't blank the rest.
+   */ async getStaleness(collection, documentId) {
+        const schema = this.schemaMap.get(collection);
+        if (!schema) return [];
+        const records = await this.store.findByDocument(collection, documentId);
+        if (records.length === 0) return [];
+        const currentFingerprint = this.makeCurrentFingerprint(collection, documentId, schema);
+        const locales = [];
+        for (const record of records){
+            try {
+                const current = await currentFingerprint(record.sourceLocale);
+                locales.push({
+                    target_lng: record.targetLocale,
+                    source_lng: record.sourceLocale,
+                    is_stale: isRecordStale(record, current),
+                    translated_at: record.translatedAt
+                });
+            } catch (error) {
+                this.payload.logger.error({
+                    err: error,
+                    collection,
+                    documentId,
+                    targetLocale: record.targetLocale,
+                    sourceLocale: record.sourceLocale,
+                    msg: "translator: failed to compute staleness for locale"
+                });
+            }
+        }
+        return locales;
+    }
+    /**
+   * Acknowledge the current source drift for one target locale: persist the current fingerprint as the
+   * dismissed one, so the indicator hides until the source changes again. No-op when the collection has
+   * no schema or the locale has no record.
+   */ async dismiss(key) {
+        const schema = this.schemaMap.get(key.collectionSlug);
+        if (!schema) return;
+        const record = await this.store.find(key);
+        if (!record) return;
+        const currentFingerprint = this.makeCurrentFingerprint(key.collectionSlug, key.documentId, schema);
+        await this.store.dismiss(key, await currentFingerprint(record.sourceLocale));
+    }
+    /**
+   * Recompute the current source fingerprint the same way the write path does (shared fetch shape +
+   * hash). Cached per source locale so a document translated from one source into N locales fetches
+   * the source once.
+   */ makeCurrentFingerprint(collection, documentId, schema) {
+        const cache = new Map();
+        return async (sourceLocale)=>{
+            const cached = cache.get(sourceLocale);
+            if (cached !== undefined) return cached;
+            const sourceData = await fetchSourceDocument(this.payload, collection, documentId, sourceLocale);
+            const fingerprint = computeSourceFingerprint(sourceData, schema);
+            cache.set(sourceLocale, fingerprint);
+            return fingerprint;
+        };
+    }
+}
+
+//# sourceMappingURL=Provenance.service.js.map

package/dist/server/modules/provenance/Provenance.shapes.d.ts

@@ -0,0 +1,26 @@
+import type { CollectionAfterDeleteHook } from "payload";
+/**
+ * The minimal slice of a Payload collection that provenance's config-time wiring reads and mutates:
+ * its `slug`, the sidecar `custom` marker, and the `afterDelete` hook slot. A real `CollectionConfig`
+ * is **structurally assignable** to this — call sites pass the live collection with no adapter, and a
+ * test passes a plain `{ slug: "posts" }` literal. Keeps `injectProvenanceCleanup` /
+ * `ensureProvenanceCollectionRegistered` off the god-`Config`/`CollectionConfig` types.
+ *
+ * The only Payload type imported here is `CollectionAfterDeleteHook` — a framework callback contract
+ * that legitimately stays framework-typed.
+ */
+export type ManagedCollectionEntry = {
+    slug: string;
+    custom?: unknown;
+    hooks?: {
+        afterDelete?: CollectionAfterDeleteHook[];
+    };
+};
+/**
+ * The minimal config host provenance's config-time wiring touches: just a mutable `collections`
+ * array. A real Payload `Config` plugs straight in (its `collections?: CollectionConfig[]` satisfies
+ * `ManagedCollectionEntry[]`).
+ */
+export type ManagedCollectionsConfig = {
+    collections?: ManagedCollectionEntry[];
+};

package/dist/server/modules/provenance/Provenance.shapes.js

@@ -0,0 +1,7 @@
+/**
+ * The minimal config host provenance's config-time wiring touches: just a mutable `collections`
+ * array. A real Payload `Config` plugs straight in (its `collections?: CollectionConfig[]` satisfies
+ * `ManagedCollectionEntry[]`).
+ */ export { };
+
+//# sourceMappingURL=Provenance.shapes.js.map

package/dist/server/modules/provenance/{PayloadProvenanceStore.js → Provenance.store.js}

@@ -129,4 +129,4 @@ function toRecord(doc) {
     }
 }
 
-//# sourceMappingURL=PayloadProvenanceStore.js.map
+//# sourceMappingURL=Provenance.store.js.map