@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/manual-edit-guard.js

@@ -0,0 +1,393 @@
+import { createHash } from 'node:crypto';
+import { getValueAtPath } from './content-extractor.js';
+/**
+ * SHA-1 of a stable JSON serialization of a value. Used to fingerprint
+ * field values for the `preserveManualEdits` feature so we can detect
+ * when a target locale row has drifted from the last plugin-written
+ * shape.
+ *
+ * Stable serialization: object keys sorted, undefined dropped. Same
+ * value → same hash across processes / machines.
+ */ export function hashFieldValue(value) {
+    return createHash('sha1').update(stableStringify(value)).digest('hex');
+}
+function stableStringify(value) {
+    if (value === undefined) return 'undefined';
+    if (value === null) return 'null';
+    if (typeof value === 'string') return JSON.stringify(value);
+    if (typeof value !== 'object') return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const entries = Object.entries(value).filter(([, v])=>v !== undefined).sort(([a], [b])=>a < b ? -1 : a > b ? 1 : 0);
+    return '{' + entries.map(([k, v])=>JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
+}
+/**
+ * Fetch every (fieldPath → lastWrittenHash) row for one
+ * (collection, documentId, locale) tuple. Used by the writer before
+ * issuing the locale-update so it can filter out fields that have
+ * drifted from the stored hash.
+ */ export async function loadFieldHashes(payload, metaCollection, collection, documentId, locale) {
+    const out = new Map();
+    try {
+        const result = await payload.find({
+            collection: metaCollection,
+            limit: 1000,
+            where: {
+                collection: {
+                    equals: collection
+                },
+                documentId: {
+                    equals: String(documentId)
+                },
+                locale: {
+                    equals: locale
+                }
+            },
+            depth: 0,
+            overrideAccess: true
+        });
+        for (const raw of result.docs){
+            const row = raw;
+            if (row.fieldPath && row.lastWrittenHash) {
+                out.set(row.fieldPath, row.lastWrittenHash);
+            }
+        }
+    } catch  {
+    // First-time write or transient read failure — caller treats empty
+    // as "no prior hash, no manual-edit divergence possible yet."
+    }
+    return out;
+}
+/**
+ * Inspect the current target doc and decide which top-level fields in
+ * `writeData` would overwrite a manually edited value. Returns the set
+ * of field names to DROP from `writeData` before issuing the update.
+ *
+ * Detection: for each top-level field path that has a stored hash, if
+ * the current target value's hash differs from the stored one, the
+ * field has been edited since the plugin's last write — skip it.
+ */ export function pickManualEditedFields(writeData, targetDoc, storedHashes) {
+    const fieldsToDrop = [];
+    const skipReasons = new Map();
+    if (!targetDoc || storedHashes.size === 0) {
+        return {
+            fieldsToDrop,
+            skipReasons
+        };
+    }
+    for (const topField of Object.keys(writeData)){
+        const storedHash = storedHashes.get(topField);
+        if (!storedHash) continue; // never written before — not divergent
+        const currentValue = getValueAtPath(targetDoc, topField);
+        // BUG-24 fix: if the current target value is NULL / undefined / empty,
+        // the row was emptied (version restore, manual deletion, fresh insert
+        // after a delete) — there's nothing for the editor to have "manually
+        // edited," so the stale stored hash should not block recovery. Treat
+        // empty targets as "no preserve" so re-translation populates them.
+        if (isEmptyTargetValue(currentValue)) continue;
+        const currentHash = hashFieldValue(currentValue);
+        if (currentHash !== storedHash) {
+            fieldsToDrop.push(topField);
+            skipReasons.set(topField, 'Target value diverges from last plugin-written hash — assumed manual edit, preserving target');
+        }
+    }
+    return {
+        fieldsToDrop,
+        skipReasons
+    };
+}
+/**
+ * "Empty target" means the row has nothing the editor could have
+ * manually refined. Includes:
+ *   - undefined / null
+ *   - empty string
+ *   - empty array
+ *   - empty object (no enumerable keys)
+ *
+ * NOT empty:
+ *   - 0, false (legitimate primitive values)
+ *   - whitespace-only strings (still editor intent)
+ */ function isEmptyTargetValue(value) {
+    if (value === undefined || value === null) return true;
+    if (typeof value === 'string') return value === '';
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'object') return Object.keys(value).length === 0;
+    return false;
+}
+/**
+ * Upsert per-field hashes after a successful locale write. One row per
+ * (collection, documentId, locale, fieldPath). Best-effort — failures
+ * here do NOT roll back the translation, they just mean the next write
+ * can't detect divergence for that field.
+ *
+ * `sourceValues` (BUG-21): map of `fieldPath → source value at time of
+ * write`. When provided, the upsert also stores `lastSourceHash` so the
+ * next translate can compare current-source-hash to stored-source-hash
+ * and skip the LLM call entirely if both source AND target are
+ * unchanged. Omitted when source values aren't available (rare).
+ */ export async function recordFieldHashes(payload, metaCollection, collection, documentId, locale, writeData, sourceValues, /**
+   * Optional request context to thread into the inner find/update/create
+   * calls. When the caller wraps the locale-write in a fresh transaction,
+   * passing the same `req` here keeps the bookkeeping rows on the same
+   * connection lifecycle. Omit for ad-hoc / out-of-band invocations.
+   */ req) {
+    const now = new Date().toISOString();
+    const fieldPaths = Object.entries(writeData);
+    let written = 0;
+    let failed = 0;
+    // Empty writeData is legitimate (all fields preserved as manual edits)
+    // — log once at debug and return cleanly so callers can distinguish
+    // "nothing to record" from "tried and failed."
+    if (fieldPaths.length === 0) {
+        return {
+            written: 0,
+            failed: 0
+        };
+    }
+    for (const [fieldPath, value] of fieldPaths){
+        const hash = hashFieldValue(value);
+        const sourceHash = sourceValues ? hashFieldValue(sourceValues[fieldPath]) : undefined;
+        try {
+            // Upsert via find + create/update. Payload doesn't have a
+            // native upsert; emulate it.
+            const existing = await payload.find({
+                collection: metaCollection,
+                limit: 1,
+                where: {
+                    and: [
+                        {
+                            collection: {
+                                equals: collection
+                            }
+                        },
+                        {
+                            documentId: {
+                                equals: String(documentId)
+                            }
+                        },
+                        {
+                            locale: {
+                                equals: locale
+                            }
+                        },
+                        {
+                            fieldPath: {
+                                equals: fieldPath
+                            }
+                        }
+                    ]
+                },
+                depth: 0,
+                overrideAccess: true,
+                ...req ? {
+                    req
+                } : {}
+            });
+            const updateData = {
+                lastWrittenHash: hash,
+                lastWrittenAt: now
+            };
+            if (sourceHash !== undefined) updateData.lastSourceHash = sourceHash;
+            if (existing.docs.length > 0) {
+                await payload.update({
+                    collection: metaCollection,
+                    id: existing.docs[0].id,
+                    data: updateData,
+                    overrideAccess: true,
+                    ...req ? {
+                        req
+                    } : {}
+                });
+            } else {
+                await payload.create({
+                    collection: metaCollection,
+                    data: {
+                        collection,
+                        documentId: String(documentId),
+                        locale,
+                        fieldPath,
+                        lastWrittenHash: hash,
+                        ...sourceHash !== undefined ? {
+                            lastSourceHash: sourceHash
+                        } : {},
+                        lastWrittenAt: now
+                    },
+                    overrideAccess: true,
+                    ...req ? {
+                        req
+                    } : {}
+                });
+            }
+            written++;
+        } catch (err) {
+            // Manual-edit detection is best-effort, so we never re-throw — but
+            // silently swallowing made an empty `ai-translate-meta` collection
+            // undebuggable. Surface the per-field failure as an error so it
+            // shows up in prod logs without filtering. The loop keeps going so
+            // one bad field doesn't drop the rest.
+            failed++;
+            const msg = err instanceof Error ? err.message : String(err);
+            const stack = err instanceof Error && err.stack ? `\n${err.stack}` : '';
+            payload.logger?.error?.(`[ai-translate] recordFieldHashes upsert failed for ${collection}/${String(documentId)} locale=${locale} field=${fieldPath}: ${msg}${stack}`);
+        }
+    }
+    return {
+        written,
+        failed
+    };
+}
+/**
+ * Fetch every `(fieldPath → { writtenHash, sourceHash })` row for one
+ * (collection, documentId, locale) tuple. Variant of `loadFieldHashes`
+ * that also returns the BUG-21 source hash so the LLM-skip check can
+ * compare current source content to what was translated last time.
+ *
+ * Returns an empty map on read failure (caller treats as "no prior data,
+ * proceed with full translate"). Rows pre-BUG-21 have `sourceHash:
+ * undefined` — those are treated as "can't safely skip; run translate."
+ */ export async function loadFieldHashesWithSource(payload, metaCollection, collection, documentId, locale) {
+    const out = new Map();
+    try {
+        const result = await payload.find({
+            collection: metaCollection,
+            limit: 1000,
+            where: {
+                collection: {
+                    equals: collection
+                },
+                documentId: {
+                    equals: String(documentId)
+                },
+                locale: {
+                    equals: locale
+                }
+            },
+            depth: 0,
+            overrideAccess: true
+        });
+        for (const raw of result.docs){
+            const row = raw;
+            if (row.fieldPath && row.lastWrittenHash) {
+                out.set(row.fieldPath, {
+                    writtenHash: row.lastWrittenHash,
+                    sourceHash: row.lastSourceHash
+                });
+            }
+        }
+    } catch  {
+    // Best-effort
+    }
+    return out;
+}
+/**
+ * Read stored source+target hashes for `(surfaceSlug, documentId,
+ * targetLocale)`, compare against current source + target, and remove
+ * units whose top-level field is unchanged on both sides. Returns the
+ * remaining units the caller still needs to translate plus synthetic
+ * `status: 'success'` results for the skipped units (characterCount = 0,
+ * durationMs = 0 — these are the "fieldsHashSkipped" rows in usage).
+ *
+ * Surface-agnostic: pass a `loadTargetDoc` closure so callers can supply
+ * `findByIdNoFallback(payload, collection, docId, locale)` for collections
+ * or `findGlobalNoFallback(payload, globalSlug, locale)` for globals.
+ *
+ * Wrapped in try/catch internally — best-effort optimization, never throws.
+ */ export async function applyHashSkip(args) {
+    const { payload, metaCollection, surfaceSlug, documentId, targetLocale, units, sourceDoc, loadTargetDoc } = args;
+    const fallback = {
+        remainingUnits: units,
+        hashSkipped: []
+    };
+    try {
+        const sourceTargetHashes = await loadFieldHashesWithSource(payload, metaCollection, surfaceSlug, documentId, targetLocale);
+        if (sourceTargetHashes.size === 0) {
+            return fallback;
+        }
+        let targetDoc = null;
+        try {
+            targetDoc = await loadTargetDoc();
+        } catch  {
+            targetDoc = null;
+        }
+        if (!targetDoc) {
+            return fallback;
+        }
+        // Group units by top-level field. A top-level field is either hash-
+        // skippable as a whole (every unit under it gets skipped) or it's
+        // not — units within the same top-field share the same source/target
+        // hash bookkeeping.
+        const unitsByTop = new Map();
+        for (const u of units){
+            const top = u.fieldPath.split('.')[0];
+            if (!top) continue;
+            const arr = unitsByTop.get(top) ?? [];
+            arr.push(u);
+            unitsByTop.set(top, arr);
+        }
+        const skippedUnitIds = new Set();
+        for (const [topField, fieldUnits] of unitsByTop){
+            const stored = sourceTargetHashes.get(topField);
+            if (!stored || !stored.sourceHash) continue; // pre-BUG21 row
+            const currentSourceHash = hashFieldValue(sourceDoc[topField]);
+            if (currentSourceHash !== stored.sourceHash) continue; // source changed
+            const currentTargetHash = hashFieldValue(targetDoc[topField]);
+            if (currentTargetHash !== stored.writtenHash) continue; // target changed
+            for (const u of fieldUnits){
+                skippedUnitIds.add(u.id);
+            }
+        }
+        if (skippedUnitIds.size === 0) {
+            return fallback;
+        }
+        const hashSkipped = [];
+        for (const u of units){
+            if (!skippedUnitIds.has(u.id)) continue;
+            hashSkipped.push({
+                fieldPath: u.fieldPath,
+                locale: targetLocale,
+                status: 'success',
+                characterCount: 0,
+                durationMs: 0
+            });
+        }
+        const remainingUnits = units.filter((u)=>!skippedUnitIds.has(u.id));
+        payload.logger?.info?.(`[ai-translate] Hash-skip: ${skippedUnitIds.size}/${units.length} units for ${surfaceSlug}/${String(documentId)} locale=${targetLocale} unchanged since last write — skipping LLM call.`);
+        return {
+            remainingUnits,
+            hashSkipped
+        };
+    } catch  {
+        // Hash-skip is purely an optimization — any failure here falls back
+        // to "translate everything," never blocks the LLM call.
+        return fallback;
+    }
+}
+/**
+ * Persist per-field source+target hashes after a successful locale
+ * write. Surface-agnostic — `surfaceSlug` is the collection slug for
+ * collection writes, or the global slug for global writes (matching the
+ * existing `bulk-translate` persist contract).
+ *
+ * Builds the `sourceValues` map from `sourceDoc` for exactly the fields
+ * in `writeData`, then defers to `recordFieldHashes`. Wraps the call so
+ * upstream errors are logged via the payload logger but never re-thrown
+ * — translation succeeded already, bookkeeping failure shouldn't surface
+ * to the editor.
+ */ export async function recordHashesAfterWrite(args) {
+    const { payload, metaCollection, surfaceSlug, documentId, targetLocale, writeData, sourceDoc } = args;
+    const sourceValues = {};
+    for (const fieldPath of Object.keys(writeData)){
+        sourceValues[fieldPath] = sourceDoc[fieldPath];
+    }
+    try {
+        return await recordFieldHashes(payload, metaCollection, surfaceSlug, documentId, targetLocale, writeData, sourceValues);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        payload.logger?.error?.(`[ai-translate] recordHashesAfterWrite failed for ${surfaceSlug}/${String(documentId)} locale=${targetLocale}: ${msg}`);
+        return {
+            written: 0,
+            failed: Object.keys(writeData).length
+        };
+    }
+}

package/dist/lib/output-validation.d.ts

@@ -0,0 +1,48 @@
+import type { ValidationConfig } from '../types.js';
+import type { EditorErrorCode } from './error-messages.js';
+export type ValidateTranslationOptions = {
+    /**
+     * Source locale of the input text. When provided alongside `targetLocale`
+     * and the two differ, the validator rejects translations that are equal to
+     * the source after NFC + whitespace normalization — a common failure mode
+     * where the model echoes a batched item untranslated. v1.2.7: echo
+     * detection runs regardless of source length; a verbatim echo is never
+     * written through to the target locale, even for short strings like brand
+     * names. The soft-skip preserves the previous target value (or leaves the
+     * target empty so the UI falls back to source). This trades the "short
+     * loanword is a valid no-op translation" assumption for never silently
+     * overwriting an existing target translation with raw source text.
+     */
+    sourceLocale?: string;
+    targetLocale?: string;
+};
+export type ValidationResult = {
+    valid: boolean;
+    reason?: string;
+    /**
+     * `true` when the rejection is informational rather than a real error.
+     * Today this fires for verbatim echoes — the model may have legitimately
+     * returned the same string for a proper noun / brand / URL fragment.
+     * Callers should classify these as `skipped`, not `failed`.
+     */
+    soft?: boolean;
+    /**
+     * Editor-facing code (one of the `soft-skip.*` values in
+     * `lib/error-messages.ts`). Set on every non-valid result so the UI
+     * can render a friendly message via `editorMessageFor(code, ctx)`
+     * instead of dumping the raw `reason` string. `reason` is kept for
+     * disclosure-style "Show technical details" rendering.
+     */
+    code?: EditorErrorCode;
+    /**
+     * Context for templating the code's message (e.g. ratio observed,
+     * placeholder ids missing). Mirrors `EditorErrorContext` shape.
+     */
+    context?: {
+        ratio?: number;
+        ratioThreshold?: number;
+        missingPlaceholders?: readonly string[];
+        extraPlaceholders?: readonly string[];
+    };
+};
+export declare function validateTranslation(source: string, translated: string, config?: ValidationConfig, options?: ValidateTranslationOptions): ValidationResult;

package/dist/lib/output-validation.js

@@ -0,0 +1,148 @@
+import { validatePlaceholderIntegrity } from '../lexical/placeholder-integrity.js';
+const DEFAULT_MIN_RATIO = 0.3;
+const DEFAULT_MAX_RATIO = 3.0;
+const DEFAULT_MIN_SOURCE_LENGTH = 10;
+const REFUSAL_PATTERNS = [
+    /I cannot translate/i,
+    /As an AI/i,
+    /I'm unable to/i,
+    /I apologize/i,
+    /I'm sorry, but/i
+];
+const INJECTION_PATTERNS = [
+    /<tool_call>/i,
+    /<\/tool_call>/i,
+    /<function_call>/i,
+    /<\/function_call>/i,
+    /<system>/i,
+    /<\/system>/i
+];
+// Control characters except \n (0x0A), \t (0x09), \r (0x0D)
+const CONTROL_CHAR_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+/**
+ * NFC-normalize, collapse internal whitespace runs, and trim. Used for the
+ * echo-equality comparison so that models emitting a subtly-different but
+ * display-equivalent variant of the source (smart quote vs ASCII quote,
+ * non-breaking space, doubled space, leading/trailing whitespace) still
+ * trip echo detection. Without this, gemini-2.5-flash has been observed
+ * passing through "Slot Games (test 1780581867023)" as a "translation"
+ * with a NBSP swap that escaped a strict `===` check.
+ */ function normalizeForEcho(s) {
+    return s.normalize('NFC').replace(/\s+/g, ' ').trim();
+}
+export function validateTranslation(source, translated, config, options) {
+    const minRatio = config?.minLengthRatio ?? DEFAULT_MIN_RATIO;
+    const maxRatio = config?.maxLengthRatio ?? DEFAULT_MAX_RATIO;
+    const minSourceLength = config?.minSourceLength ?? DEFAULT_MIN_SOURCE_LENGTH;
+    // Echo detection runs regardless of source length (v1.2.7). Short brand
+    // names / loanwords used to bypass this gate, which let gemini-2.5-flash
+    // overwrite existing target translations with verbatim source for fields
+    // like "Bonus Buy". A verbatim echo is a soft-skip: the previous target
+    // value is preserved; an empty target stays empty (and the UI falls back
+    // to source). The ratio checks below still respect minSourceLength.
+    if (options?.sourceLocale && options.targetLocale && options.sourceLocale !== options.targetLocale && normalizeForEcho(translated) === normalizeForEcho(source)) {
+        return {
+            valid: false,
+            soft: true,
+            code: 'soft-skip.echoed',
+            reason: `Translation matches source verbatim — model likely echoed input for "${options.targetLocale}"`
+        };
+    }
+    if (source.length >= minSourceLength) {
+        const ratio = translated.length / source.length;
+        if (ratio < minRatio) {
+            return {
+                // 2026-06-05: all `soft-skip.*` codes now set `soft: true` so the
+                // caller (translate.ts:899) routes them to the `skipped` map
+                // instead of the retry/error path. The naming `soft-skip.*` always
+                // implied this — prior to today only `echoed` carried the flag,
+                // which meant a Chinese translation legitimately denser than the
+                // English source (ratio 0.10 vs min 0.15) would be classified as
+                // a HARD validation failure and the unit aggregator stamped it
+                // `permanent.schema` with editor copy that pointed at "needs a
+                // configuration fix" — nonsensical for an output-quality issue.
+                valid: false,
+                soft: true,
+                code: 'soft-skip.too-short',
+                context: {
+                    ratio,
+                    ratioThreshold: minRatio
+                },
+                reason: `Translation too short: ratio ${ratio.toFixed(2)} (min ${minRatio})`
+            };
+        }
+        if (ratio > maxRatio) {
+            return {
+                valid: false,
+                soft: true,
+                code: 'soft-skip.too-long',
+                context: {
+                    ratio,
+                    ratioThreshold: maxRatio
+                },
+                reason: `Translation too long: ratio ${ratio.toFixed(2)} (max ${maxRatio})`
+            };
+        }
+    }
+    if (CONTROL_CHAR_RE.test(translated)) {
+        return {
+            valid: false,
+            soft: true,
+            code: 'soft-skip.control-chars',
+            reason: 'Translation contains disallowed control characters'
+        };
+    }
+    // Placeholder integrity: rich-text units carry inline marks (bold,
+    // links, etc.) as `<ph id="...">` tokens. The model must echo the
+    // exact same set verbatim — added or dropped placeholders mean the
+    // deserializer would silently corrupt the Lexical tree.
+    if (source.includes('<ph')) {
+        const integrity = validatePlaceholderIntegrity(source, translated);
+        if (!integrity.valid) {
+            const issues = [];
+            if (integrity.missingIds.length) issues.push(`missing [${integrity.missingIds.join(', ')}]`);
+            if (integrity.extraIds.length) issues.push(`extra [${integrity.extraIds.join(', ')}]`);
+            return {
+                valid: false,
+                soft: true,
+                code: 'soft-skip.placeholders',
+                context: {
+                    missingPlaceholders: integrity.missingIds,
+                    extraPlaceholders: integrity.extraIds
+                },
+                reason: `Translation lost placeholder integrity — ${issues.join('; ')}`
+            };
+        }
+    }
+    const allRefusal = [
+        ...REFUSAL_PATTERNS,
+        ...config?.extraRefusalPatterns ?? []
+    ];
+    for (const pattern of allRefusal){
+        if (pattern.test(translated)) {
+            return {
+                valid: false,
+                soft: true,
+                code: 'soft-skip.refusal',
+                reason: `Translation contains refusal pattern: ${pattern.source}`
+            };
+        }
+    }
+    const allInjection = [
+        ...INJECTION_PATTERNS,
+        ...config?.extraInjectionPatterns ?? []
+    ];
+    for (const pattern of allInjection){
+        if (pattern.test(translated)) {
+            return {
+                valid: false,
+                soft: true,
+                code: 'soft-skip.injection',
+                reason: `Translation contains injection pattern: ${pattern.source}`
+            };
+        }
+    }
+    return {
+        valid: true
+    };
+}

package/dist/lib/payload-read.d.ts

@@ -0,0 +1,16 @@
+import type { Payload, Where } from 'payload';
+export type ReadOptions = {
+    /**
+     * Read the latest draft version when the collection has drafts enabled.
+     * Pass-through to Payload's local API. No-op for non-versioned collections.
+     * Default: false (preserves existing read-published behavior for hooks
+     * that fire on already-committed docs).
+     */
+    draft?: boolean;
+};
+export declare function findByIdNoFallback(payload: Payload, collection: string, id: string | number, locale: string, options?: ReadOptions): Promise<Record<string, unknown>>;
+export declare function findNoFallback(payload: Payload, collection: string, where: Where, locale: string, options?: ReadOptions): Promise<{
+    docs: Record<string, unknown>[];
+    totalDocs: number;
+}>;
+export declare function findGlobalNoFallback(payload: Payload, slug: string, locale: string): Promise<Record<string, unknown>>;

package/dist/lib/payload-read.js

@@ -0,0 +1,51 @@
+// Payload's Local API disables locale fallback when `fallbackLocale: false`.
+// Passing `null` does NOT disable fallback — the runtime falls back to the
+// default chain (typically the source/EN locale), which silently returns
+// source content under a target-locale query. That's exactly the wrong
+// behavior here: the locale-merge logic relies on knowing whether the target
+// locale actually has data so it can pick the fresh-target vs. target-present
+// branch. With the old `null` value, every "fresh target" query returned EN
+// data, the merge entered the target-present branch carrying EN row ids, and
+// Payload rejected the locale write with `"The following field is invalid: id"`
+// because those row ids belong to the source locale's rows.
+//
+// Payload's TypeScript types declare `fallbackLocale` as a locale string, so
+// we cast once here rather than scattering `as unknown as string` across the
+// codebase. The runtime accepts the boolean `false` and disables fallback.
+const NO_FALLBACK = false;
+export async function findByIdNoFallback(payload, collection, id, locale, options = {}) {
+    const result = await payload.findByID({
+        collection: collection,
+        id,
+        locale,
+        fallbackLocale: NO_FALLBACK,
+        draft: options.draft ?? false,
+        // depth: 0 returns relationships as scalar IDs (not populated docs).
+        // The default depth: 2 populates upload/relationship fields, which
+        // become invalid when the merge writes them back to Payload —
+        // upload validators reject populated docs containing admin-only
+        // fields and server-generated metadata (sizes.*, url, filename, ...).
+        depth: 0
+    });
+    return result;
+}
+export async function findNoFallback(payload, collection, where, locale, options = {}) {
+    const result = await payload.find({
+        collection: collection,
+        where,
+        locale,
+        fallbackLocale: NO_FALLBACK,
+        draft: options.draft ?? false,
+        depth: 0
+    });
+    return result;
+}
+export async function findGlobalNoFallback(payload, slug, locale) {
+    const result = await payload.findGlobal({
+        slug: slug,
+        locale,
+        fallbackLocale: NO_FALLBACK,
+        depth: 0
+    });
+    return result;
+}