@byline/core 1.9.1 → 1.10.0

package/dist/@types/collection-types.d.ts

@@ -302,33 +302,52 @@ export declare function defineWorkflow(input?: DefineWorkflowInput): WorkflowCon
  * Context passed to `beforeCreate` hooks.
  *
  * The hook can mutate `data` before it is persisted.
+ *
+ * `duplicate` is set only when the create originates from a
+ * `duplicateDocument` call. Userland hooks that need to react differently
+ * (e.g. skip outbound webhooks, tag analytics) can branch on its presence.
+ * When set, `data` carries the multi-locale tree shape (localized fields
+ * appear as `{ locale: value }` objects) — mirroring the multi-locale
+ * `data` precedent set by `restoreDocumentVersion`'s `beforeUpdate` hook.
  */
 export interface BeforeCreateContext {
     data: Record<string, any>;
     collectionPath: string;
+    duplicate?: {
+        sourceDocumentId: string;
+    };
 }
 /**
  * Context passed to `afterCreate` hooks.
  *
  * Includes the `documentId` and `documentVersionId` returned by storage
  * so the hook can reference the persisted document.
+ *
+ * `duplicate` mirrors `BeforeCreateContext.duplicate` — present only when
+ * the create was triggered by `duplicateDocument`.
  */
 export interface AfterCreateContext {
     data: Record<string, any>;
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    duplicate?: {
+        sourceDocumentId: string;
+    };
 }
 /**
- * Context passed to `beforeUpdate` hooks — PUT, patch, and restore flows.
+ * Context passed to `beforeUpdate` hooks — PUT, patch, restore, and
+ * copy-to-locale flows.
  *
  * `data` is the next version (mutable). `originalData` is the previous
  * version as reconstructed from storage.
  *
  * `restore` is set only when the update originates from a "make current"
- * action against a historical version. Userland hooks that need to react
- * differently (e.g. tag the audit entry, skip search re-index) can branch
- * on its presence.
+ * action against a historical version. `copyToLocale` is set only when
+ * the update originates from a Copy-to-Locale operation. The two are
+ * mutually exclusive in practice. Userland hooks that need to react
+ * differently (e.g. tag the audit entry, skip search re-index, suppress
+ * translation webhooks during a bulk seed) can branch on their presence.
  */
 export interface BeforeUpdateContext {
     data: Record<string, any>;
@@ -337,6 +356,10 @@ export interface BeforeUpdateContext {
     restore?: {
         sourceVersionId: string;
     };
+    copyToLocale?: {
+        sourceLocale: string;
+        targetLocale: string;
+    };
 }
 /**
  * Context passed to `afterUpdate` hooks.
@@ -346,6 +369,8 @@ export interface BeforeUpdateContext {
  *
  * `restore` mirrors `BeforeUpdateContext.restore` — present only when the
  * update was triggered by restoring a historical version.
+ * `copyToLocale` mirrors `BeforeUpdateContext.copyToLocale` — present only
+ * when the update was triggered by `copyToLocale`.
  */
 export interface AfterUpdateContext {
     data: Record<string, any>;
@@ -356,6 +381,10 @@ export interface AfterUpdateContext {
     restore?: {
         sourceVersionId: string;
     };
+    copyToLocale?: {
+        sourceLocale: string;
+        targetLocale: string;
+    };
 }
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.

package/dist/services/document-lifecycle.d.ts

@@ -119,6 +119,43 @@ export interface RestoreVersionResult {
     documentVersionId: string;
     sourceVersionId: string;
 }
+export interface CopyToLocaleResult {
+    documentId: string;
+    documentVersionId: string;
+    /** Source locale read for the copy. */
+    sourceLocale: string;
+    /** Target locale into which the source's localized leaves were written. */
+    targetLocale: string;
+    /**
+     * Number of localized field values copied from source to target. Useful
+     * for UI toasts ("Copied 4 fields from EN to FR"). A zero result means
+     * the source had no localized content to copy into the target under the
+     * chosen merge rule (e.g. `overwrite: false` and target was already
+     * fully populated).
+     */
+    fieldsUpdated: number;
+}
+export interface DuplicateDocumentResult {
+    /** The newly-created document's id. */
+    documentId: string;
+    /** The newly-created version id (every duplicate starts at version 1). */
+    documentVersionId: string;
+    /** The id of the document this duplicate was cloned from. */
+    sourceDocumentId: string;
+    /**
+     * Final `path` written into `byline_document_paths` for the new document.
+     * Surfaced in the result so the UI can include it in success toasts /
+     * navigate to it directly.
+     */
+    newPath: string;
+    /**
+     * `true` when the candidate path collided with an existing row and the
+     * lifecycle retried with a short-UUID suffix. UIs can surface a hint that
+     * the auto-generated path is uglier than usual so the editor knows to
+     * adjust it via the path widget.
+     */
+    pathRetried: boolean;
+}
 /**
  * Create a new document.
  *
@@ -293,3 +330,72 @@ export declare function restoreDocumentVersion(ctx: DocumentLifecycleContext, pa
 export declare function deleteDocument(ctx: DocumentLifecycleContext, params: {
     documentId: string;
 }): Promise<DeleteDocumentResult>;
+/**
+ * Duplicate a document, cloning all of its locales into a brand-new
+ * document atomically.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('create')` — duplicating is a create at the
+ *      ability level. The source must be readable (any RBAC scoping the
+ *      caller has applies via the storage read).
+ *   2. Fetch the source with `locale: 'all'` so a single read carries the
+ *      full multi-locale tree forward.
+ *   3. Deep-clone the source fields; strip block / array-item `_id` meta
+ *      so the new doc gets fresh identities.
+ *   4. Append `" (copy)"` to the `useAsTitle` field's value(s).
+ *   5. Derive a candidate path from the default-locale suffixed title.
+ *   6. `hooks.beforeCreate({ data, collectionPath, duplicate })`.
+ *   7. `db.commands.documents.createDocumentVersion(...)` with `locale:
+ *      'all'`, `action: 'create'`, no `documentId` → fresh document_id.
+ *      On `ERR_PATH_CONFLICT` retry once with the candidate path plus a
+ *      4-char UUID suffix; bounded to two attempts, no existence
+ *      pre-check, no TOCTOU race.
+ *   8. `hooks.afterCreate({ data, collectionPath, documentId,
+ *      documentVersionId, duplicate })`.
+ *
+ * The write is atomic at the storage layer — a partial duplicate is
+ * structurally impossible. Editors are expected to rename both the
+ * title and the system path after the operation; the UI surfaces a
+ * confirmation modal that calls this out.
+ */
+export declare function duplicateDocument(ctx: DocumentLifecycleContext, params: {
+    sourceDocumentId: string;
+}): Promise<DuplicateDocumentResult>;
+/**
+ * Copy a document's content from one locale into another, in place on
+ * the same document.
+ *
+ * Reads the source and target locales separately (the storage layer
+ * resolves localized fields to flat single-locale shapes when given a
+ * specific `resolveLocale`). A schema-aware merge walker decides, leaf
+ * by leaf, whether to take the source's value or keep the target's,
+ * driven by the `overwrite` flag. The merged tree is written via
+ * `createDocumentVersion({ action: 'copy_to_locale', locale: target })`
+ * — the existing cross-locale carry-forward in the storage primitive
+ * preserves every *other* locale's rows untouched.
+ *
+ * Non-localized fields are never altered by this operation: they live
+ * on `locale: 'all'` rows and the merge walker passes the target's
+ * value through so the write does not blank them.
+ *
+ * Path is sticky and lives on default-locale only; this operation never
+ * touches `byline_document_paths`. Status resets to the workflow
+ * default — translations land as drafts.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — same gate as a translation save.
+ *   2. Reject if `sourceLocale === targetLocale`.
+ *   3. Fetch source via `getDocumentById({ locale: sourceLocale })`.
+ *   4. Fetch target via `getDocumentById({ locale: targetLocale })`.
+ *   5. `mergeLocaleData(definition.fields, source.fields, target.fields, overwrite)`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, copyToLocale })`.
+ *   7. `createDocumentVersion({ documentId, action: 'copy_to_locale',
+ *      locale: targetLocale, documentData, previousVersionId, status })`.
+ *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
+ */
+export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    sourceLocale: string;
+    targetLocale: string;
+    overwrite: boolean;
+}): Promise<CopyToLocaleResult>;

package/dist/services/document-lifecycle.js

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { normalizeCollectionHook, } from '../@types/index.js';
+import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
-import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, } from '../lib/errors.js';
+import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, ErrorCodes, } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
 import { applyPatches } from '../patches/index.js';
 import { normaliseDateFields } from '../utils/normalise-dates.js';
@@ -702,3 +702,505 @@ export async function deleteDocument(ctx, params) {
         return { deletedVersionCount };
     });
 }
+/**
+ * Strip the synthetic `_id` / `_type` meta keys from every block and
+ * array-item node in a reconstructed document tree.
+ *
+ * Reconstructed `locale: 'all'` trees carry stable `_id` values for
+ * blocks and array items (see CLAUDE.md → "Block/array items carry a
+ * stable `_id`"). For a *duplicate*, the new document is conceptually a
+ * fresh entity — its blocks should get fresh meta ids rather than
+ * inheriting the source's. Mutates the tree in place.
+ *
+ * Distinct from `restoreDocumentVersion`, which deliberately preserves
+ * `_id`s so block identity is stable across history.
+ */
+function stripMetaIdsInPlace(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            stripMetaIdsInPlace(item);
+        }
+        return;
+    }
+    if (value != null && typeof value === 'object' && !(value instanceof Date)) {
+        const obj = value;
+        delete obj._id;
+        delete obj._type;
+        for (const key of Object.keys(obj)) {
+            stripMetaIdsInPlace(obj[key]);
+        }
+    }
+}
+/**
+ * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
+ * duplicate's data tree. Handles both shapes:
+ *
+ *   - Localized title — `fields[useAsTitle]` is `{ en: '...', fr: '...' }`,
+ *     suffix is applied to every locale's value.
+ *   - Non-localized title — `fields[useAsTitle]` is a plain string;
+ *     suffix appended once.
+ *
+ * No-op when the collection has no `useAsTitle` or the title is null /
+ * undefined; the duplicate proceeds with the source's title verbatim and
+ * the editor can rename it. Mutates the tree in place.
+ */
+function applyDuplicateTitleSuffix(definition, fields, suffix) {
+    const titleField = definition.useAsTitle;
+    if (titleField == null)
+        return;
+    const value = fields[titleField];
+    if (value == null)
+        return;
+    if (typeof value === 'string') {
+        fields[titleField] = value + suffix;
+        return;
+    }
+    if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+        const localized = value;
+        for (const loc of Object.keys(localized)) {
+            const v = localized[loc];
+            if (typeof v === 'string') {
+                localized[loc] = v + suffix;
+            }
+        }
+    }
+}
+/**
+ * Compute the candidate path for a duplicate.
+ *
+ * Reads the default-locale value of `definition.useAsPath` (peeling the
+ * localized-shape wrapper if present) and runs it through the existing
+ * `derivePath` helper. Falls back to `crypto.randomUUID()` when no source
+ * value is available — matches `createDocument`'s behaviour for paths
+ * that can't be slugged.
+ */
+function deriveDuplicateCandidatePath(definition, fields, defaultLocale, slugifier) {
+    const useAsPath = definition.useAsPath;
+    if (useAsPath == null) {
+        return crypto.randomUUID();
+    }
+    const raw = fields[useAsPath];
+    // Peel the localized wrapper to find the default-locale value.
+    let sourceValue = raw;
+    if (raw != null && typeof raw === 'object' && !Array.isArray(raw) && !(raw instanceof Date)) {
+        sourceValue = raw[defaultLocale];
+    }
+    return derivePath(definition, { [useAsPath]: sourceValue }, defaultLocale, slugifier);
+}
+/**
+ * Duplicate a document, cloning all of its locales into a brand-new
+ * document atomically.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('create')` — duplicating is a create at the
+ *      ability level. The source must be readable (any RBAC scoping the
+ *      caller has applies via the storage read).
+ *   2. Fetch the source with `locale: 'all'` so a single read carries the
+ *      full multi-locale tree forward.
+ *   3. Deep-clone the source fields; strip block / array-item `_id` meta
+ *      so the new doc gets fresh identities.
+ *   4. Append `" (copy)"` to the `useAsTitle` field's value(s).
+ *   5. Derive a candidate path from the default-locale suffixed title.
+ *   6. `hooks.beforeCreate({ data, collectionPath, duplicate })`.
+ *   7. `db.commands.documents.createDocumentVersion(...)` with `locale:
+ *      'all'`, `action: 'create'`, no `documentId` → fresh document_id.
+ *      On `ERR_PATH_CONFLICT` retry once with the candidate path plus a
+ *      4-char UUID suffix; bounded to two attempts, no existence
+ *      pre-check, no TOCTOU race.
+ *   8. `hooks.afterCreate({ data, collectionPath, documentId,
+ *      documentVersionId, duplicate })`.
+ *
+ * The write is atomic at the storage layer — a partial duplicate is
+ * structurally impossible. Editors are expected to rename both the
+ * title and the system path after the operation; the UI surfaces a
+ * confirmation modal that calls this out.
+ */
+export async function duplicateDocument(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'duplicateDocument' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        const slugifier = ctx.slugifier ?? slugify;
+        const hooks = definition.hooks;
+        // 1. Read source with locale='all' — single read, full multi-locale tree.
+        const source = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.sourceDocumentId,
+            locale: 'all',
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (source == null) {
+            throw ERR_NOT_FOUND({
+                message: 'source document not found',
+                details: { sourceDocumentId: params.sourceDocumentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        const sourceRecord = source;
+        const sourceFields = sourceRecord.fields ?? {};
+        // 2. Deep clone — we'll mutate (suffix titles, strip meta ids).
+        const clonedFields = structuredClone(sourceFields);
+        // 3. Fresh block / array-item identities for the new doc.
+        stripMetaIdsInPlace(clonedFields);
+        // 4. Suffix titles per locale (or once if non-localized).
+        const titleSuffix = ' (copy)';
+        applyDuplicateTitleSuffix(definition, clonedFields, titleSuffix);
+        // 5. Derive candidate path from the (now suffixed) default-locale title.
+        const candidatePath = deriveDuplicateCandidatePath(definition, clonedFields, defaultLocale, slugifier);
+        // 6. beforeCreate hook with duplicate marker.
+        const duplicateMarker = { sourceDocumentId: params.sourceDocumentId };
+        await invokeHook(hooks?.beforeCreate, {
+            data: clonedFields,
+            collectionPath,
+            duplicate: duplicateMarker,
+        });
+        // 7. Atomic write. Try the candidate path; on ERR_PATH_CONFLICT
+        //    retry once with a 4-char UUID suffix.
+        const defaultStatus = getDefaultStatus(definition);
+        let finalPath = candidatePath;
+        let pathRetried = false;
+        let result;
+        try {
+            result = await db.commands.documents
+                .createDocumentVersion({
+                collectionId,
+                collectionVersion: ctx.collectionVersion,
+                collectionConfig: definition,
+                action: 'create',
+                documentData: clonedFields,
+                path: finalPath,
+                status: defaultStatus,
+                locale: 'all',
+            })
+                .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
+        }
+        catch (err) {
+            if (!isPathConflictError(err)) {
+                throw err;
+            }
+            // Single retry with a short UUID suffix. crypto.randomUUID() is
+            // 36 chars; take the first 4 hex digits for a compact disambiguator.
+            const shortDisambiguator = crypto.randomUUID().slice(0, 4);
+            finalPath = `${candidatePath}-${shortDisambiguator}`;
+            pathRetried = true;
+            ctx.logger?.info({ candidatePath, retryPath: finalPath, sourceDocumentId: params.sourceDocumentId }, 'duplicateDocument: candidate path collided, retrying with short-UUID suffix');
+            result = await db.commands.documents
+                .createDocumentVersion({
+                collectionId,
+                collectionVersion: ctx.collectionVersion,
+                collectionConfig: definition,
+                action: 'create',
+                documentData: clonedFields,
+                path: finalPath,
+                status: defaultStatus,
+                locale: 'all',
+            })
+                .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
+        }
+        const newDocumentId = extractDocumentId(result.document);
+        const newDocumentVersionId = extractVersionId(result.document);
+        // 8. afterCreate hook with duplicate marker.
+        await invokeHook(hooks?.afterCreate, {
+            data: clonedFields,
+            collectionPath,
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+            duplicate: duplicateMarker,
+        });
+        return {
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+            sourceDocumentId: params.sourceDocumentId,
+            newPath: finalPath,
+            pathRetried,
+        };
+    });
+}
+/**
+ * Detect whether an error is the `ERR_PATH_CONFLICT` raised by
+ * `rethrowPathConflict`. Used by `duplicateDocument`'s retry logic to
+ * keep the conflict-handling path separate from genuine errors.
+ */
+function isPathConflictError(err) {
+    return (err != null &&
+        typeof err === 'object' &&
+        err.code === ErrorCodes.PATH_CONFLICT);
+}
+// ---------------------------------------------------------------------------
+// Copy-to-Locale merge walker
+// ---------------------------------------------------------------------------
+/**
+ * Treat null, undefined, and empty string as "no value" for the purpose
+ * of the `overwrite: false` merge rule. We intentionally do NOT treat
+ * `0`, `false`, or `[]` / `{}` as empty — they are meaningful values an
+ * editor may have set deliberately.
+ */
+function isEmptyLeafValue(value) {
+    return value == null || value === '';
+}
+/**
+ * Build the payload `copyToLocale` will write into the target locale.
+ *
+ * Walks `definition.fields` and the two reconstructed data trees in
+ * lockstep, applying the merge rule at every leaf:
+ *
+ *   - **Localized leaf, `overwrite: true`** — take source's value (even
+ *     when source is empty; overwriting means overwriting).
+ *   - **Localized leaf, `overwrite: false`** — take source's value only
+ *     when target is empty AND source is non-empty. Otherwise keep
+ *     target's value. Empties under this rule are treated by
+ *     `isEmptyLeafValue` — `null` / `undefined` / `''`.
+ *   - **Non-localized leaf** — always keep target's value. Non-localized
+ *     fields live on `locale: 'all'` rows in storage and would be wiped
+ *     by the upcoming write if we did not pass them through verbatim.
+ *
+ * Structure (number of array items, blocks, etc.) follows the *target*
+ * tree — copy-to-locale never restructures the document; it only fills
+ * in localized leaves at positions the target already has.
+ *
+ * Pure: mutates nothing. The returned `data` is a fresh tree suitable
+ * to pass to `createDocumentVersion`.
+ */
+function mergeLocaleData(fields, sourceData, targetData, overwrite) {
+    const source = (sourceData ?? {});
+    const target = (targetData ?? {});
+    const out = {};
+    let fieldsUpdated = 0;
+    for (const field of fields) {
+        const updated = mergeFieldValue(field, source[field.name], target[field.name], overwrite);
+        out[field.name] = updated.value;
+        fieldsUpdated += updated.fieldsUpdated;
+    }
+    return { data: out, fieldsUpdated };
+}
+function mergeFieldValue(field, sourceValue, targetValue, overwrite) {
+    if (isGroupField(field)) {
+        const childSource = isPlainObject(sourceValue) ? sourceValue : {};
+        const childTarget = isPlainObject(targetValue) ? targetValue : {};
+        const merged = mergeLocaleData(field.fields, childSource, childTarget, overwrite);
+        return { value: merged.data, fieldsUpdated: merged.fieldsUpdated };
+    }
+    if (isArrayField(field)) {
+        if (!Array.isArray(targetValue)) {
+            // Target has no array here — keep that. Source is not authoritative
+            // for structure under copy-to-locale.
+            return { value: targetValue, fieldsUpdated: 0 };
+        }
+        const sourceItems = Array.isArray(sourceValue) ? sourceValue : [];
+        const mergedItems = [];
+        let count = 0;
+        for (let i = 0; i < targetValue.length; i++) {
+            const tItem = targetValue[i];
+            const sItem = sourceItems[i];
+            if (!isPlainObject(tItem)) {
+                mergedItems.push(tItem);
+                continue;
+            }
+            const itemMerge = mergeLocaleData(field.fields, isPlainObject(sItem) ? sItem : {}, tItem, overwrite);
+            // Preserve `_id` / `_type` meta on the target item — same identity
+            // is carried forward across this update.
+            const merged = { ...itemMerge.data };
+            if (tItem._id !== undefined)
+                merged._id = tItem._id;
+            if (tItem._type !== undefined)
+                merged._type = tItem._type;
+            mergedItems.push(merged);
+            count += itemMerge.fieldsUpdated;
+        }
+        return { value: mergedItems, fieldsUpdated: count };
+    }
+    if (isBlocksField(field)) {
+        if (!Array.isArray(targetValue)) {
+            return { value: targetValue, fieldsUpdated: 0 };
+        }
+        const sourceItems = Array.isArray(sourceValue) ? sourceValue : [];
+        const mergedItems = [];
+        let count = 0;
+        for (let i = 0; i < targetValue.length; i++) {
+            const tItem = targetValue[i];
+            if (!isPlainObject(tItem)) {
+                mergedItems.push(tItem);
+                continue;
+            }
+            const blockType = tItem._type;
+            const block = field.blocks.find((b) => b.blockType === blockType);
+            if (block == null) {
+                // Unknown block — pass through unchanged.
+                mergedItems.push(tItem);
+                continue;
+            }
+            const sItem = sourceItems[i];
+            const itemMerge = mergeLocaleData(block.fields, isPlainObject(sItem) && sItem._type === blockType ? sItem : {}, tItem, overwrite);
+            const merged = { ...itemMerge.data };
+            if (tItem._id !== undefined)
+                merged._id = tItem._id;
+            merged._type = blockType;
+            mergedItems.push(merged);
+            count += itemMerge.fieldsUpdated;
+        }
+        return { value: mergedItems, fieldsUpdated: count };
+    }
+    // Leaf field.
+    const localized = field.localized === true;
+    if (!localized) {
+        // Non-localized leaves live on locale: 'all' rows. Pass the target's
+        // value through verbatim so the write does not wipe them.
+        return { value: targetValue, fieldsUpdated: 0 };
+    }
+    if (overwrite) {
+        return {
+            value: sourceValue,
+            fieldsUpdated: sourceValue === targetValue ? 0 : 1,
+        };
+    }
+    // overwrite: false — fill only when target is empty AND source has content.
+    if (isEmptyLeafValue(targetValue) && !isEmptyLeafValue(sourceValue)) {
+        return { value: sourceValue, fieldsUpdated: 1 };
+    }
+    return { value: targetValue, fieldsUpdated: 0 };
+}
+function isPlainObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------
+// copyToLocale
+// ---------------------------------------------------------------------------
+/**
+ * Copy a document's content from one locale into another, in place on
+ * the same document.
+ *
+ * Reads the source and target locales separately (the storage layer
+ * resolves localized fields to flat single-locale shapes when given a
+ * specific `resolveLocale`). A schema-aware merge walker decides, leaf
+ * by leaf, whether to take the source's value or keep the target's,
+ * driven by the `overwrite` flag. The merged tree is written via
+ * `createDocumentVersion({ action: 'copy_to_locale', locale: target })`
+ * — the existing cross-locale carry-forward in the storage primitive
+ * preserves every *other* locale's rows untouched.
+ *
+ * Non-localized fields are never altered by this operation: they live
+ * on `locale: 'all'` rows and the merge walker passes the target's
+ * value through so the write does not blank them.
+ *
+ * Path is sticky and lives on default-locale only; this operation never
+ * touches `byline_document_paths`. Status resets to the workflow
+ * default — translations land as drafts.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — same gate as a translation save.
+ *   2. Reject if `sourceLocale === targetLocale`.
+ *   3. Fetch source via `getDocumentById({ locale: sourceLocale })`.
+ *   4. Fetch target via `getDocumentById({ locale: targetLocale })`.
+ *   5. `mergeLocaleData(definition.fields, source.fields, target.fields, overwrite)`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, copyToLocale })`.
+ *   7. `createDocumentVersion({ documentId, action: 'copy_to_locale',
+ *      locale: targetLocale, documentData, previousVersionId, status })`.
+ *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
+ */
+export async function copyToLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'copyToLocale' }, async () => {
+        const { db, definition, collectionId, collectionPath } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        if (params.sourceLocale === params.targetLocale) {
+            throw ERR_VALIDATION({
+                message: 'sourceLocale and targetLocale must differ',
+                details: {
+                    documentId: params.documentId,
+                    sourceLocale: params.sourceLocale,
+                    targetLocale: params.targetLocale,
+                },
+            }).log(ctx.logger);
+        }
+        // 1. Source read.
+        const source = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.sourceLocale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (source == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found in source locale',
+                details: {
+                    documentId: params.documentId,
+                    sourceLocale: params.sourceLocale,
+                    collectionPath,
+                },
+            }).log(ctx.logger);
+        }
+        // 2. Target read — needed for both originalData (hooks) and to
+        //    preserve non-localized values + structural shape.
+        const target = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.targetLocale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (target == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found in target locale',
+                details: {
+                    documentId: params.documentId,
+                    targetLocale: params.targetLocale,
+                    collectionPath,
+                },
+            }).log(ctx.logger);
+        }
+        const sourceRecord = source;
+        const targetRecord = target;
+        const sourceFields = sourceRecord.fields ?? {};
+        const targetFields = targetRecord.fields ?? {};
+        // 3. Merge.
+        const merged = mergeLocaleData(definition.fields, sourceFields, targetFields, params.overwrite);
+        // 4. Hooks see the target-locale view as originalData (consistent
+        //    with how updateDocument scopes originalData to the active
+        //    locale) and the merged payload as the next `data`.
+        const hooks = definition.hooks;
+        const copyToLocaleMarker = {
+            sourceLocale: params.sourceLocale,
+            targetLocale: params.targetLocale,
+        };
+        await invokeHook(hooks?.beforeUpdate, {
+            data: merged.data,
+            originalData: targetFields,
+            collectionPath,
+            copyToLocale: copyToLocaleMarker,
+        });
+        // 5. Write. previousVersionId threads the current version id so the
+        //    storage primitive's cross-locale carry-forward fires for every
+        //    *other* locale (not source, not target — those rows are
+        //    rewritten by this call).
+        const previousVersionId = targetRecord.document_version_id ?? undefined;
+        const writeResult = await db.commands.documents.createDocumentVersion({
+            documentId: params.documentId,
+            collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: definition,
+            action: 'copy_to_locale',
+            documentData: merged.data,
+            status: getDefaultStatus(definition),
+            locale: params.targetLocale,
+            previousVersionId,
+        });
+        const documentVersionId = extractVersionId(writeResult.document);
+        await invokeHook(hooks?.afterUpdate, {
+            data: merged.data,
+            originalData: targetFields,
+            collectionPath,
+            documentId: params.documentId,
+            documentVersionId,
+            copyToLocale: copyToLocaleMarker,
+        });
+        return {
+            documentId: params.documentId,
+            documentVersionId,
+            sourceLocale: params.sourceLocale,
+            targetLocale: params.targetLocale,
+            fieldsUpdated: merged.fieldsUpdated,
+        };
+    });
+}

package/dist/services/document-lifecycle.test.node.js

@@ -7,8 +7,8 @@
  */
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
-import { BylineError, ErrorCodes } from '../lib/errors.js';
-import { changeDocumentStatus, createDocument, deleteDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle.js';
+import { BylineError, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
+import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
 // ---------------------------------------------------------------------------
@@ -918,6 +918,585 @@ describe('Document lifecycle service', () => {
         });
     });
     // -----------------------------------------------------------------------
+    // duplicateDocument
+    // -----------------------------------------------------------------------
+    describe('duplicateDocument', () => {
+        /** Collection with a localized title (drives the per-locale suffix path). */
+        const localizedCollection = {
+            path: 'articles',
+            labels: { singular: 'Article', plural: 'Articles' },
+            useAsTitle: 'title',
+            useAsPath: 'title',
+            fields: [
+                { name: 'title', type: 'text', localized: true },
+                { name: 'tagline', type: 'text' },
+            ],
+        };
+        /** Helper: seed the source read with `locale: 'all'`. */
+        function setupSource(mocks, opts) {
+            const sourceDocumentId = opts?.sourceDocumentId ?? 'doc-source';
+            const sourceFields = opts?.sourceFields ?? {
+                title: { en: 'Hello', fr: 'Bonjour' },
+                tagline: 'A tagline',
+            };
+            mocks.getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-source',
+                document_id: sourceDocumentId,
+                path: 'hello',
+                status: 'draft',
+                created_at: new Date(),
+                updated_at: new Date(),
+                fields: sourceFields,
+            });
+            mocks.createDocumentVersion.mockResolvedValue({
+                document: { id: 'ver-new', document_id: 'doc-new' },
+                fieldCount: 5,
+            });
+            return { sourceDocumentId, sourceFields };
+        }
+        it('reads the source with locale: "all" and writes via createDocumentVersion with locale: "all", action: "create", no documentId', async () => {
+            const mocks = createMockDb();
+            const { sourceDocumentId } = setupSource(mocks);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            const result = await duplicateDocument(ctx, { sourceDocumentId });
+            expect(mocks.getDocumentById).toHaveBeenCalledWith(expect.objectContaining({
+                collection_id: 'col-1',
+                document_id: sourceDocumentId,
+                locale: 'all',
+                reconstruct: true,
+                lenient: true,
+            }));
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+            const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            expect(call.action).toBe('create');
+            expect(call.locale).toBe('all');
+            expect(call.documentId).toBeUndefined();
+            expect(result.documentId).toBe('doc-new');
+            expect(result.documentVersionId).toBe('ver-new');
+            expect(result.sourceDocumentId).toBe(sourceDocumentId);
+            expect(result.pathRetried).toBe(false);
+        });
+        it('appends " (copy)" to every locale of a localized useAsTitle field', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks, {
+                sourceFields: {
+                    title: { en: 'Hello', fr: 'Bonjour' },
+                    tagline: 'A tagline',
+                },
+            });
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            expect(call.documentData.title).toEqual({
+                en: 'Hello (copy)',
+                fr: 'Bonjour (copy)',
+            });
+            // Non-title fields pass through untouched.
+            expect(call.documentData.tagline).toBe('A tagline');
+        });
+        it('appends " (copy)" once to a non-localized useAsTitle field', async () => {
+            const nonLocalizedCollection = {
+                ...localizedCollection,
+                fields: [
+                    { name: 'title', type: 'text' },
+                    { name: 'tagline', type: 'text' },
+                ],
+            };
+            const mocks = createMockDb();
+            setupSource(mocks, {
+                sourceFields: {
+                    title: 'Hello',
+                    tagline: 'A tagline',
+                },
+            });
+            const ctx = buildCtx(mocks.db, nonLocalizedCollection);
+            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            expect(call.documentData.title).toBe('Hello (copy)');
+        });
+        it('derives the candidate path from the default-locale suffixed title', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks, {
+                sourceFields: {
+                    title: { en: 'Hello World', fr: 'Bonjour Monde' },
+                    tagline: 'A tagline',
+                },
+            });
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            const result = await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            // Default locale is 'en'; "Hello World (copy)" slugifies to "hello-world-copy".
+            expect(call.path).toBe('hello-world-copy');
+            expect(result.newPath).toBe('hello-world-copy');
+        });
+        it('strips _id and _type metadata from blocks and array items so the new doc gets fresh identities', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks, {
+                sourceFields: {
+                    title: { en: 'Hello', fr: 'Bonjour' },
+                    tagline: 'A tagline',
+                    sections: [
+                        {
+                            _id: 'section-id-1',
+                            _type: 'section',
+                            heading: 'Intro',
+                            blocks: [
+                                { _id: 'block-id-1', _type: 'photoBlock', display: 'wide' },
+                                { _id: 'block-id-2', _type: 'textBlock', body: 'inner' },
+                            ],
+                        },
+                    ],
+                },
+            });
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            const sections = call.documentData.sections;
+            expect(sections[0]._id).toBeUndefined();
+            expect(sections[0]._type).toBeUndefined();
+            expect(sections[0].blocks[0]._id).toBeUndefined();
+            expect(sections[0].blocks[1]._id).toBeUndefined();
+            // Content survives — only meta is stripped.
+            expect(sections[0].heading).toBe('Intro');
+            expect(sections[0].blocks[0].display).toBe('wide');
+        });
+        it('does not mutate the source object returned by getDocumentById (deep-clones before suffix / strip)', async () => {
+            const originalFields = {
+                title: { en: 'Hello', fr: 'Bonjour' },
+                tagline: 'A tagline',
+                sections: [{ _id: 'sec-1', heading: 'Intro' }],
+            };
+            const mocks = createMockDb();
+            mocks.getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-source',
+                document_id: 'doc-source',
+                path: 'hello',
+                status: 'draft',
+                created_at: new Date(),
+                updated_at: new Date(),
+                fields: originalFields,
+            });
+            mocks.createDocumentVersion.mockResolvedValue({
+                document: { id: 'ver-new', document_id: 'doc-new' },
+                fieldCount: 5,
+            });
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            // Source title should be unchanged in memory.
+            expect(originalFields.title).toEqual({ en: 'Hello', fr: 'Bonjour' });
+            expect(originalFields.sections[0]?._id).toBe('sec-1');
+        });
+        it('retries once with a short-UUID suffix when the candidate path collides', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            // First call: throw a path-conflict error. Second call: succeed.
+            let attempt = 0;
+            mocks.createDocumentVersion.mockImplementation(() => {
+                attempt += 1;
+                if (attempt === 1) {
+                    const err = ERR_PATH_CONFLICT({ message: 'path conflict' });
+                    return Promise.reject(err);
+                }
+                return Promise.resolve({
+                    document: { id: 'ver-new', document_id: 'doc-new' },
+                    fieldCount: 5,
+                });
+            });
+            const result = await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            expect(mocks.createDocumentVersion).toHaveBeenCalledTimes(2);
+            const firstPath = mocks.createDocumentVersion.mock.calls[0]?.[0].path;
+            const retryPath = mocks.createDocumentVersion.mock.calls[1]?.[0].path;
+            expect(retryPath.startsWith(`${firstPath}-`)).toBe(true);
+            // 4-char UUID slice
+            expect(retryPath.length).toBe(firstPath.length + 5);
+            expect(result.pathRetried).toBe(true);
+            expect(result.newPath).toBe(retryPath);
+        });
+        it('only retries once — a second conflict propagates to the caller', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            // Both attempts throw path-conflict.
+            mocks.createDocumentVersion.mockImplementation(() => {
+                return Promise.reject(ERR_PATH_CONFLICT({ message: 'path conflict' }));
+            });
+            await expect(duplicateDocument(ctx, { sourceDocumentId: 'doc-source' })).rejects.toMatchObject({ code: ErrorCodes.PATH_CONFLICT });
+            // Bounded to exactly two attempts.
+            expect(mocks.createDocumentVersion).toHaveBeenCalledTimes(2);
+        });
+        it('throws ERR_NOT_FOUND when the source document does not exist', async () => {
+            const mocks = createMockDb();
+            mocks.getDocumentById.mockResolvedValue(null);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            try {
+                await duplicateDocument(ctx, { sourceDocumentId: 'doc-missing' });
+                expect.fail('expected ERR_NOT_FOUND');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.NOT_FOUND);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('fires beforeCreate / afterCreate hooks with a duplicate marker', async () => {
+            const beforeCreate = vi.fn();
+            const afterCreate = vi.fn();
+            const withHooks = {
+                ...localizedCollection,
+                hooks: {
+                    beforeCreate,
+                    afterCreate,
+                },
+            };
+            const mocks = createMockDb();
+            setupSource(mocks, { sourceDocumentId: 'doc-source' });
+            const ctx = buildCtx(mocks.db, withHooks);
+            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            expect(beforeCreate).toHaveBeenCalledOnce();
+            const beforeCtx = beforeCreate.mock.calls[0]?.[0];
+            expect(beforeCtx.duplicate).toEqual({ sourceDocumentId: 'doc-source' });
+            expect(beforeCtx.collectionPath).toBe('articles');
+            // Hook sees the multi-locale shape (mirrors restoreDocumentVersion's
+            // multi-locale-data precedent on beforeUpdate).
+            expect(beforeCtx.data.title).toEqual({ en: 'Hello (copy)', fr: 'Bonjour (copy)' });
+            expect(afterCreate).toHaveBeenCalledOnce();
+            const afterCtx = afterCreate.mock.calls[0]?.[0];
+            expect(afterCtx.duplicate).toEqual({ sourceDocumentId: 'doc-source' });
+            expect(afterCtx.documentId).toBe('doc-new');
+            expect(afterCtx.documentVersionId).toBe('ver-new');
+        });
+        it('enforces collections.<path>.create — rejects an admin actor missing the ability', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            // Replace super-admin with an admin who only has read.
+            const actor = new AdminAuth({
+                id: 'reader',
+                abilities: ['collections.articles.read'],
+            });
+            ctx.requestContext = createRequestContext({ actor });
+            try {
+                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+                expect.fail('expected ERR_FORBIDDEN');
+            }
+            catch (err) {
+                expect(err.code).toBe(AuthErrorCodes.FORBIDDEN);
+                expect(err.message).toContain('collections.articles.create');
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('rejects when requestContext is absent (ERR_UNAUTHENTICATED)', async () => {
+            const mocks = createMockDb();
+            setupSource(mocks);
+            const ctx = buildCtx(mocks.db, localizedCollection);
+            ctx.requestContext = undefined;
+            try {
+                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+                expect.fail('expected ERR_UNAUTHENTICATED');
+            }
+            catch (err) {
+                expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // copyToLocale
+    // -----------------------------------------------------------------------
+    describe('copyToLocale', () => {
+        /** Collection with mixed localized / non-localized fields, including
+         *  nested structure (array of groups, blocks). */
+        const mixedCollection = {
+            path: 'articles',
+            labels: { singular: 'Article', plural: 'Articles' },
+            useAsTitle: 'title',
+            fields: [
+                { name: 'title', type: 'text', localized: true },
+                { name: 'tagline', type: 'text', localized: true },
+                { name: 'sku', type: 'text' /* non-localized */ },
+                {
+                    name: 'sections',
+                    type: 'array',
+                    fields: [
+                        { name: 'heading', type: 'text', localized: true },
+                        { name: 'order', type: 'integer' /* non-localized */ },
+                    ],
+                },
+            ],
+        };
+        function setupSourceTarget(opts) {
+            const mocks = createMockDb();
+            const sourceFields = opts?.sourceFields ?? {
+                title: 'Hello',
+                tagline: 'World',
+                sku: 'SKU-1',
+                sections: [{ _id: 'sec-1', heading: 'Intro', order: 1 }],
+            };
+            const targetFields = opts?.targetFields ?? {
+                title: '',
+                tagline: 'Already translated',
+                sku: 'SKU-1',
+                sections: [{ _id: 'sec-1', heading: '', order: 1 }],
+            };
+            const currentVersionId = opts?.currentVersionId ?? 'ver-current';
+            mocks.getDocumentById.mockImplementation(async (params) => {
+                if (params.locale === 'en') {
+                    return {
+                        document_version_id: currentVersionId,
+                        document_id: 'doc-1',
+                        path: 'hello',
+                        status: 'draft',
+                        fields: sourceFields,
+                    };
+                }
+                if (params.locale === 'fr') {
+                    return {
+                        document_version_id: currentVersionId,
+                        document_id: 'doc-1',
+                        path: 'hello',
+                        status: 'draft',
+                        fields: targetFields,
+                    };
+                }
+                return null;
+            });
+            mocks.createDocumentVersion.mockResolvedValue({
+                document: { id: 'ver-new', document_id: 'doc-1' },
+                fieldCount: 5,
+            });
+            return { mocks, sourceFields, targetFields, currentVersionId };
+        }
+        it('reads both source and target locales, writes target with action="copy_to_locale", locale=target, previousVersionId threaded', async () => {
+            const { mocks, currentVersionId } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            const result = await copyToLocale(ctx, {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            });
+            // Source + target read.
+            const readCalls = mocks.getDocumentById.mock.calls.map((c) => c[0]);
+            expect(readCalls.some((p) => p.locale === 'en')).toBe(true);
+            expect(readCalls.some((p) => p.locale === 'fr')).toBe(true);
+            // Single write to target locale.
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+            const writeCall = mocks.createDocumentVersion.mock.calls[0]?.[0];
+            expect(writeCall.action).toBe('copy_to_locale');
+            expect(writeCall.locale).toBe('fr');
+            expect(writeCall.documentId).toBe('doc-1');
+            expect(writeCall.previousVersionId).toBe(currentVersionId);
+            expect(writeCall.path).toBeUndefined();
+            // Result envelope.
+            expect(result.documentId).toBe('doc-1');
+            expect(result.sourceLocale).toBe('en');
+            expect(result.targetLocale).toBe('fr');
+        });
+        it('overwrite=false: fills empty target slots from source, preserves populated target slots, never touches non-localized fields', async () => {
+            const { mocks } = setupSourceTarget({
+                sourceFields: {
+                    title: 'EN Title',
+                    tagline: 'EN Tagline',
+                    sku: 'SKU-EN',
+                    sections: [{ _id: 'sec-1', heading: 'EN Heading', order: 5 }],
+                },
+                targetFields: {
+                    title: '', // empty → should be filled
+                    tagline: 'FR Tagline Already', // populated → should be kept
+                    sku: 'SKU-FR', // non-localized, target value preserved
+                    sections: [{ _id: 'sec-1', heading: '', order: 9 }],
+                },
+            });
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            const result = await copyToLocale(ctx, {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            });
+            const data = mocks.createDocumentVersion.mock.calls[0]?.[0].documentData;
+            expect(data.title).toBe('EN Title'); // filled
+            expect(data.tagline).toBe('FR Tagline Already'); // kept
+            expect(data.sku).toBe('SKU-FR'); // non-localized: target preserved
+            expect(data.sections[0].heading).toBe('EN Heading'); // filled
+            expect(data.sections[0].order).toBe(9); // non-localized: target preserved
+            expect(data.sections[0]._id).toBe('sec-1'); // identity preserved
+            expect(result.fieldsUpdated).toBe(2); // title + sections[0].heading
+        });
+        it('overwrite=true: replaces every localized leaf with source value, even when source is empty', async () => {
+            const { mocks } = setupSourceTarget({
+                sourceFields: {
+                    title: 'EN Title',
+                    tagline: '', // empty source
+                    sku: 'SKU-EN',
+                    sections: [{ _id: 'sec-1', heading: 'EN Heading', order: 5 }],
+                },
+                targetFields: {
+                    title: 'FR Title',
+                    tagline: 'FR Tagline',
+                    sku: 'SKU-FR',
+                    sections: [{ _id: 'sec-1', heading: 'FR Heading', order: 9 }],
+                },
+            });
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            await copyToLocale(ctx, {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: true,
+            });
+            const data = mocks.createDocumentVersion.mock.calls[0]?.[0].documentData;
+            expect(data.title).toBe('EN Title'); // overwritten
+            expect(data.tagline).toBe(''); // overwritten even though source is empty
+            expect(data.sku).toBe('SKU-FR'); // non-localized: still target preserved
+            expect(data.sections[0].heading).toBe('EN Heading'); // overwritten
+            expect(data.sections[0].order).toBe(9); // non-localized preserved
+        });
+        it('does not pass `path` — path is sticky on copy-to-locale', async () => {
+            const { mocks } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            await copyToLocale(ctx, {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            });
+            expect(mocks.createDocumentVersion.mock.calls[0]?.[0].path).toBeUndefined();
+        });
+        it('rejects when sourceLocale === targetLocale (ERR_VALIDATION)', async () => {
+            const { mocks } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            try {
+                await copyToLocale(ctx, {
+                    documentId: 'doc-1',
+                    sourceLocale: 'en',
+                    targetLocale: 'en',
+                    overwrite: false,
+                });
+                expect.fail('expected ERR_VALIDATION');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.VALIDATION);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('throws ERR_NOT_FOUND when the source-locale read returns null', async () => {
+            const mocks = createMockDb();
+            mocks.getDocumentById.mockResolvedValue(null); // both reads fail
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            try {
+                await copyToLocale(ctx, {
+                    documentId: 'doc-1',
+                    sourceLocale: 'en',
+                    targetLocale: 'fr',
+                    overwrite: false,
+                });
+                expect.fail('expected ERR_NOT_FOUND');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.NOT_FOUND);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('throws ERR_NOT_FOUND when the target-locale read returns null', async () => {
+            const mocks = createMockDb();
+            // Source returns a doc; target returns null.
+            mocks.getDocumentById.mockImplementation(async (params) => {
+                if (params.locale === 'en') {
+                    return {
+                        document_version_id: 'ver-current',
+                        document_id: 'doc-1',
+                        path: 'hello',
+                        status: 'draft',
+                        fields: { title: 'EN Title' },
+                    };
+                }
+                return null;
+            });
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            try {
+                await copyToLocale(ctx, {
+                    documentId: 'doc-1',
+                    sourceLocale: 'en',
+                    targetLocale: 'fr',
+                    overwrite: false,
+                });
+                expect.fail('expected ERR_NOT_FOUND');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.NOT_FOUND);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('fires beforeUpdate / afterUpdate with the copyToLocale discriminator', async () => {
+            const beforeUpdate = vi.fn();
+            const afterUpdate = vi.fn();
+            const withHooks = {
+                ...mixedCollection,
+                hooks: { beforeUpdate, afterUpdate },
+            };
+            const { mocks } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, withHooks);
+            await copyToLocale(ctx, {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            });
+            expect(beforeUpdate).toHaveBeenCalledOnce();
+            expect(beforeUpdate.mock.calls[0]?.[0].copyToLocale).toEqual({
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+            });
+            expect(afterUpdate).toHaveBeenCalledOnce();
+            expect(afterUpdate.mock.calls[0]?.[0].copyToLocale).toEqual({
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+            });
+        });
+        it('enforces collections.<path>.update — rejects an admin actor missing the ability', async () => {
+            const { mocks } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            const actor = new AdminAuth({
+                id: 'reader',
+                abilities: ['collections.articles.read'],
+            });
+            ctx.requestContext = createRequestContext({ actor });
+            try {
+                await copyToLocale(ctx, {
+                    documentId: 'doc-1',
+                    sourceLocale: 'en',
+                    targetLocale: 'fr',
+                    overwrite: false,
+                });
+                expect.fail('expected ERR_FORBIDDEN');
+            }
+            catch (err) {
+                expect(err.code).toBe(AuthErrorCodes.FORBIDDEN);
+                expect(err.message).toContain('collections.articles.update');
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('rejects when requestContext is absent (ERR_UNAUTHENTICATED)', async () => {
+            const { mocks } = setupSourceTarget();
+            const ctx = buildCtx(mocks.db, mixedCollection);
+            ctx.requestContext = undefined;
+            try {
+                await copyToLocale(ctx, {
+                    documentId: 'doc-1',
+                    sourceLocale: 'en',
+                    targetLocale: 'fr',
+                    overwrite: false,
+                });
+                expect.fail('expected ERR_UNAUTHENTICATED');
+            }
+            catch (err) {
+                expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+    });
+    // -----------------------------------------------------------------------
     // Ability enforcement (Phase 4)
     // -----------------------------------------------------------------------
     describe('ability enforcement', () => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.9.1"
+    "@byline/auth": "1.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",