@focus-reactive/payload-plugin-translator 0.7.2 → 0.8.1

package/dist/server/features/createTranslationRoutes.d.ts

@@ -1,23 +1,22 @@
 import type { CollectionSlug, Endpoint } from "payload";
-import type { AccessGuard } from "../shared";
-import type { TaskRunnerFactory } from "../modules/task-runner";
-export type TranslationRoutesDeps = {
-    taskRunnerFactory: TaskRunnerFactory;
+import type { TranslationContext } from "../modules/translation-levels";
+export type TranslationRoutesDeps = Pick<TranslationContext, "taskRunnerFactory" | "access" | "provenanceServiceFactory"> & {
     /** Collections the plugin manages — gates which slugs the routes accept. */
     collectionConfig: {
         availableCollections: Set<CollectionSlug>;
     };
-    access?: AccessGuard;
     basePath?: string;
 };
 /**
- * The translator's HTTP surface as one shared bundle: the 6 job-API endpoints
+ * The translator's HTTP surface as one shared bundle: the job-API endpoints
  * (enqueue / run / cancel / cancel-by-collection / document-status /
- * collection-status), all wired to the same runner factory and access guard.
+ * collection-status) plus the provenance-backed staleness endpoints
+ * (document-staleness / dismiss), all wired to the same access guard.
  *
  * Extracted from the plugin's `init()` so registration is a single unit. The
  * document and collection levels each contribute this bundle via the level
  * context; the plugin deduplicates by method + path, so it registers exactly
- * once. Behaviour-preserving: same endpoints, same order, same wiring.
+ * once. The staleness endpoints always register; when provenance is disabled
+ * (`provenanceServiceFactory` absent) they simply report no staleness.
  */
-export declare function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, }: TranslationRoutesDeps): Endpoint[];
+export declare function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, provenanceServiceFactory, }: TranslationRoutesDeps): Endpoint[];

package/dist/server/features/createTranslationRoutes.js

@@ -4,23 +4,32 @@ import { createCancelRoute } from "./cancel";
 import { createCancelByCollectionRoute } from "./cancel-by-collection";
 import { createGetDocumentStatusRoute } from "./get-document-status";
 import { createGetCollectionStatusRoute } from "./get-collection-status";
+import { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./staleness";
 /**
- * The translator's HTTP surface as one shared bundle: the 6 job-API endpoints
+ * The translator's HTTP surface as one shared bundle: the job-API endpoints
  * (enqueue / run / cancel / cancel-by-collection / document-status /
- * collection-status), all wired to the same runner factory and access guard.
+ * collection-status) plus the provenance-backed staleness endpoints
+ * (document-staleness / dismiss), all wired to the same access guard.
  *
  * Extracted from the plugin's `init()` so registration is a single unit. The
  * document and collection levels each contribute this bundle via the level
  * context; the plugin deduplicates by method + path, so it registers exactly
- * once. Behaviour-preserving: same endpoints, same order, same wiring.
- */ export function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath }) {
+ * once. The staleness endpoints always register; when provenance is disabled
+ * (`provenanceServiceFactory` absent) they simply report no staleness.
+ */ export function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, provenanceServiceFactory }) {
+    const stalenessConfig = {
+        availableCollections: collectionConfig.availableCollections,
+        provenanceServiceFactory
+    };
     return [
         createEnqueueRoute(taskRunnerFactory, collectionConfig, access, basePath),
         createRunRoute(taskRunnerFactory, access, basePath),
         createCancelRoute(taskRunnerFactory, access, basePath),
         createCancelByCollectionRoute(collectionConfig, taskRunnerFactory, access, basePath),
         createGetDocumentStatusRoute(collectionConfig, taskRunnerFactory, access, basePath),
-        createGetCollectionStatusRoute(collectionConfig, taskRunnerFactory, access, basePath)
+        createGetCollectionStatusRoute(collectionConfig, taskRunnerFactory, access, basePath),
+        createGetDocumentStalenessRoute(stalenessConfig, access, basePath),
+        createDismissStalenessRoute(stalenessConfig, access, basePath)
     ];
 }
 

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JobIdSchema } from "../../shared";
+import { JobIdSchema, toClientErrorMessage } from "../../shared";
 /**
  * Input validation schema.
  *
@@ -28,7 +28,12 @@ import { JobIdSchema } from "../../shared";
             target_lng: task.input.targetLng,
             strategy: task.input.strategy
         },
-        error: task.error,
+        // Never ship the raw provider/runtime error to the browser outside development — it can leak
+        // implementation detail and secrets (e.g. a partial API key). The full error stays in the job
+        // record + server logs.
+        error: task.error ? {
+            message: toClientErrorMessage(task.error.message)
+        } : undefined,
         cancelled: task.cancelled
     };
 }

package/dist/server/features/staleness/dismissStaleness.handler.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from "payload";
+import type { StalenessConfig } from "./model";
+/** Dismisses (acknowledges) staleness of one target locale for a document. */
+export declare class DismissStalenessHandler {
+    private readonly config;
+    constructor(config: StalenessConfig);
+    handle(req: PayloadRequest): Promise<Response>;
+}

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

@@ -0,0 +1,31 @@
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { DismissStalenessInputSchema } from "./model";
+/** Dismisses (acknowledges) staleness of one target locale for a document. */ export class DismissStalenessHandler {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async handle(req) {
+        const validationResult = DismissStalenessInputSchema.safeParse(await req.json?.());
+        if (validationResult.error) {
+            return ServerResponse.validationError(validationResult.error.issues);
+        }
+        const { collection_slug, collection_id, target_lng } = validationResult.data;
+        const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
+        if (!collectionSlug) {
+            return ServerResponse.badRequest("Collection not available for translation");
+        }
+        const service = this.config.provenanceServiceFactory?.(req.payload);
+        await service?.dismiss({
+            collectionSlug: collectionSlug,
+            documentId: collection_id,
+            targetLocale: target_lng
+        });
+        return ServerResponse.success({
+            success: true
+        });
+    }
+}
+
+//# sourceMappingURL=dismissStaleness.handler.js.map

package/dist/server/features/staleness/getDocumentStaleness.handler.d.ts

@@ -0,0 +1,12 @@
+import type { PayloadRequest } from "payload";
+import type { StalenessConfig } from "./model";
+/**
+ * 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)
+ * degrades to an empty result and a log line — it must never 500 the document panel.
+ */
+export declare class GetDocumentStalenessHandler {
+    private readonly config;
+    constructor(config: StalenessConfig);
+    handle(req: PayloadRequest): Promise<Response>;
+}

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

@@ -0,0 +1,43 @@
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { GetDocumentStalenessInputSchema } from "./model";
+/**
+ * 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)
+ * degrades to an empty result and a log line — it must never 500 the document panel.
+ */ export class GetDocumentStalenessHandler {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async handle(req) {
+        const validationResult = GetDocumentStalenessInputSchema.safeParse(req.routeParams);
+        if (validationResult.error) {
+            return ServerResponse.validationError(validationResult.error.issues);
+        }
+        const { collection_slug, collection_id } = validationResult.data;
+        const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
+        if (!collectionSlug) {
+            return ServerResponse.badRequest("Collection not available for translation");
+        }
+        try {
+            const service = this.config.provenanceServiceFactory?.(req.payload);
+            const locales = service ? await service.getStaleness(collectionSlug, collection_id) : [];
+            return ServerResponse.success({
+                locales
+            });
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                collection: collectionSlug,
+                documentId: collection_id,
+                msg: "translator: failed to compute translation staleness"
+            });
+            return ServerResponse.success({
+                locales: []
+            });
+        }
+    }
+}
+
+//# sourceMappingURL=getDocumentStaleness.handler.js.map

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

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

package/dist/server/features/staleness/index.js

@@ -0,0 +1,3 @@
+export { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./route";
+
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { CollectionSlug } from "payload";
+import type { TranslationContext } from "../../modules/translation-levels";
+/**
+ * Route params for reading a document's per-locale staleness.
+ *
+ * `collection_id` accepts any shape Payload allows as a document id — see {@link JobIdSchema}.
+ */
+export declare const GetDocumentStalenessInputSchema: z.ZodObject<{
+    collection_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
+    collection_slug: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    collection_slug: string;
+    collection_id: string;
+}, {
+    collection_slug: string;
+    collection_id: string | number;
+}>;
+/** Body for dismissing (acknowledging) staleness of one target locale. */
+export declare const DismissStalenessInputSchema: z.ZodObject<{
+    collection_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
+    collection_slug: z.ZodString;
+    target_lng: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    collection_slug: string;
+    collection_id: string;
+    target_lng: string;
+}, {
+    collection_slug: string;
+    collection_id: string | number;
+    target_lng: string;
+}>;
+/**
+ * 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 = Pick<TranslationContext, "provenanceServiceFactory"> & {
+    availableCollections: Set<CollectionSlug>;
+};

package/dist/server/features/staleness/model.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
+/**
+ * Route params for reading a document's per-locale staleness.
+ *
+ * `collection_id` accepts any shape Payload allows as a document id — see {@link JobIdSchema}.
+ */ export const GetDocumentStalenessInputSchema = z.object({
+    collection_id: JobIdSchema,
+    collection_slug: z.string().nonempty()
+});
+/** Body for dismissing (acknowledging) staleness of one target locale. */ export const DismissStalenessInputSchema = z.object({
+    collection_id: JobIdSchema,
+    collection_slug: z.string().nonempty(),
+    target_lng: z.string().nonempty()
+});
+
+//# sourceMappingURL=model.js.map

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

@@ -0,0 +1,7 @@
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { StalenessConfig } from "./model";
+/** GET per-locale staleness for one document. */
+export declare function createGetDocumentStalenessRoute(config: StalenessConfig, access?: AccessGuard, basePath?: string): Endpoint;
+/** POST to dismiss (acknowledge) staleness of one target locale. */
+export declare function createDismissStalenessRoute(config: StalenessConfig, access?: AccessGuard, basePath?: string): Endpoint;

package/dist/server/features/staleness/route.js

@@ -0,0 +1,21 @@
+import { withErrorHandler, withAccessCheck } from "../../shared";
+import { GetDocumentStalenessHandler } from "./getDocumentStaleness.handler";
+import { DismissStalenessHandler } from "./dismissStaleness.handler";
+/** GET per-locale staleness for one document. */ export function createGetDocumentStalenessRoute(config, access, basePath = "/translate") {
+    const handler = new GetDocumentStalenessHandler(config);
+    return {
+        path: `${basePath}/stale/:collection_slug/:collection_id`,
+        method: "get",
+        handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
+    };
+}
+/** POST to dismiss (acknowledge) staleness of one target locale. */ export function createDismissStalenessRoute(config, access, basePath = "/translate") {
+    const handler = new DismissStalenessHandler(config);
+    return {
+        path: `${basePath}/stale/dismiss`,
+        method: "post",
+        handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
+    };
+}
+
+//# sourceMappingURL=route.js.map

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,28 +1,31 @@
 import { APIError } from "payload";
 import { translateContent } from "../../../core/translation-pipeline";
-import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
+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;
         // Get original schema (preserves localized: true on nested fields)
         const schema = this.schemaMap.get(collection);
         if (!schema) throw new APIError(`Collection "${collection}" not found in schemaMap`, 400);
-        const sourceData = await payload.findByID({
-            collection,
-            id: collectionId,
-            locale: sourceLng,
-            depth: 0
-        });
+        const sourceData = await fetchSourceDocument(payload, collection, collectionId, sourceLng);
+        // 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,
@@ -44,28 +47,13 @@ import { computeSourceFingerprint } from "../../../core/content-projection/compu
         };
         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"
-                });
-            }
+        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;
+}