@byline/core 3.11.2 → 3.12.0

package/dist/services/document-lifecycle.js

@@ -1,1569 +0,0 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
-import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, resolveHooks, } from '../@types/index.js';
-import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
-import { getCollectionDefinition, getServerConfig } from '../config/config.js';
-import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, ErrorCodes, } from '../lib/errors.js';
-import { generateKeyBetween } from '../lib/fractional-index.js';
-import { withLogContext } from '../lib/logger.js';
-import { applyPatches } from '../patches/index.js';
-import { normaliseDateFields } from '../utils/normalise-dates.js';
-import { slugify } from '../utils/slugify.js';
-import { getUploadFields } from '../utils/storage-utils.js';
-import { getDefaultStatus, getWorkflow, validateStatusTransition } from '../workflow/workflow.js';
-import { assignCounterValues } from './assign-counter-values.js';
-import { createReadContext } from './populate.js';
-import { embedRichTextFields } from './richtext-embed.js';
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Safely invoke an optional hook slot, awaiting the result if it returns a
- * Promise. When the slot is an array of functions they are executed
- * sequentially in order.
- */
-async function invokeHook(hook, ctx) {
-    const fns = normalizeCollectionHook(hook);
-    for (const fn of fns) {
-        await fn(ctx);
-    }
-}
-/**
- * Run the registered richtext embed adapter across every rich-text leaf
- * in the outgoing document data. Mirror of the read-side
- * `populateRichTextFields` — fires once per write, mutates `data` in
- * place. Per-leaf errors are logged and swallowed by `embedRichTextFields`
- * itself (branch C); document-level errors propagate.
- *
- * No-op when no embed adapter is registered. The bootstrap validator
- * (step 7 of the link-refactor strategy) will eventually fail-fast for
- * collections that declare `embedRelationsOnSave: true` without a
- * registered adapter; until then a missing adapter is silent and writes
- * proceed unmodified.
- */
-async function applyRichTextEmbed(ctx, data) {
-    // Tolerate environments that drive the lifecycle without
-    // `initBylineCore()` (unit tests, isolated tooling) — they have no
-    // adapter to invoke, so this is a soft no-op.
-    let embed;
-    try {
-        embed = getServerConfig().fields?.richText?.embed;
-    }
-    catch {
-        return;
-    }
-    if (embed == null)
-        return;
-    await embedRichTextFields({
-        fields: ctx.definition.fields,
-        collectionPath: ctx.collectionPath,
-        data,
-        embed,
-        readContext: createReadContext(),
-        logger: ctx.logger,
-    });
-}
-/**
- * For collections with `orderable: true` on their schema definition, compute
- * an append-at-end fractional-index key for a newly-inserted document.
- * Returns `undefined` when the collection hasn't opted in (or has no
- * definition registered, e.g. in unit-test environments), so the storage row
- * gets `order_key = NULL` and the existing "no ordering" behavior holds.
- */
-async function maybeAppendOrderKey(ctx, collectionPath) {
-    const definition = getCollectionDefinition(collectionPath);
-    if (definition?.orderable !== true)
-        return undefined;
-    const last = await ctx.db.queries.documents.getLastOrderKey({
-        collection_id: ctx.collectionId,
-    });
-    return generateKeyBetween(last, null);
-}
-/** Extract `id` from the document object returned by `createDocumentVersion`. */
-function extractVersionId(document) {
-    return document?.id ?? document?.document_version_id ?? '';
-}
-/**
- * Detect a Postgres unique-constraint violation on
- * `byline_document_paths(collection_id, locale, path)` and translate it
- * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
- *
- * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
- * the constraint name on the error object (`constraint`); matching by
- * name keeps this targeted to the path constraint and avoids spuriously
- * rebranding unrelated unique violations as path conflicts.
- *
- * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
- * original attached as `cause`, so we walk a short cause chain to find
- * the carried `code` / `constraint`.
- */
-function rethrowPathConflict(err, path, locale) {
-    let e = err;
-    // Walk at most a few `cause` hops — DrizzleQueryError → underlying pg error.
-    for (let i = 0; i < 3 && e; i++) {
-        if (e.code === '23505' &&
-            typeof e.constraint === 'string' &&
-            e.constraint.includes('document_paths_collection_locale_path')) {
-            throw ERR_PATH_CONFLICT({
-                message: `path "${path}" is already in use in this collection (locale: ${locale})`,
-                details: { path, locale, constraint: e.constraint },
-            });
-        }
-        e = e.cause;
-    }
-    throw err;
-}
-/**
- * Resolve the path argument the storage primitive should receive on an
- * update operation. Phase 1 only writes path rows under the default
- * content locale; on translation saves a supplied path is dropped with
- * a `logger.warn`, leaving the existing default-locale row untouched.
- *
- * Returns `undefined` to signal the storage primitive should skip the
- * path write entirely (no upsert).
- */
-function resolvePathForUpdate(args) {
-    const { explicitPath, currentPath, requestLocale, sourceLocale, documentId, logger } = args;
-    if (requestLocale === sourceLocale) {
-        // Source-locale write: pass path through when supplied; otherwise
-        // skip the write (existing path row stays as-is — sticky). The path row
-        // lives under the document's source_locale (its anchor), not the mutable
-        // global default — so this stays correct after the global default is
-        // switched. See docs/I18N.md.
-        return explicitPath ?? undefined;
-    }
-    // Non-source-locale (translation) write: reject any path change with a warn
-    // so the operation succeeds but the editor / API caller is informed.
-    if (explicitPath !== null && explicitPath !== currentPath) {
-        logger?.warn({
-            documentId,
-            requestedLocale: requestLocale,
-            sourceLocale,
-            suppliedPath: explicitPath,
-            currentPath,
-        }, 'path changes apply only on source-locale writes; ignored on translation save');
-    }
-    return undefined;
-}
-/** Extract the logical document id from the document object returned by `createDocumentVersion`. */
-function extractDocumentId(document) {
-    return document?.document_id ?? '';
-}
-/**
- * Derive the `path` value written into `byline_document_paths` at
- * create time.
- *
- *   1. `definition.useAsPath` set → slugify the named source field's value
- *      in the default content locale.
- *   2. Source field absent / empty → fall back to `crypto.randomUUID()`.
- *
- * Caller passes explicit overrides separately; this helper only handles
- * the auto-derivation cascade.
- */
-function derivePath(definition, data, defaultLocale, slugifier) {
-    if (definition.useAsPath != null) {
-        const sourceValue = data[definition.useAsPath];
-        if (sourceValue != null) {
-            const asString = sourceValue instanceof Date ? sourceValue.toISOString() : String(sourceValue);
-            if (asString.length > 0) {
-                const slug = slugifier(asString, {
-                    locale: defaultLocale,
-                    collectionPath: definition.path,
-                });
-                if (slug.length > 0)
-                    return slug;
-            }
-        }
-    }
-    return crypto.randomUUID();
-}
-// ---------------------------------------------------------------------------
-// Lifecycle functions
-// ---------------------------------------------------------------------------
-/**
- * Create a new document.
- *
- * Flow:
- *   1. Default-locale enforcement: reject if `params.locale` is anything
- *      other than the configured default content locale (a brand-new
- *      document's canonical `path` lives in the default locale).
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeCreate({ data, collectionPath })`
- *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
- *      → UUID fallback.
- *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
- *   6. `hooks.afterCreate({ data, collectionPath, documentId, documentVersionId })`
- */
-export async function createDocument(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'createDocument' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
-        const slugifier = ctx.slugifier ?? slugify;
-        const hooks = await resolveHooks(definition);
-        const data = params.data;
-        if (params.locale != null && params.locale !== defaultLocale) {
-            throw ERR_VALIDATION({
-                message: `documents must be created in the default content locale ('${defaultLocale}'); received '${params.locale}'. Create the default-locale version first, then add localised versions via update.`,
-                details: { defaultLocale, providedLocale: params.locale, collectionPath },
-            }).log(ctx.logger);
-        }
-        normaliseDateFields(data);
-        await invokeHook(hooks?.beforeCreate, { data, collectionPath });
-        // Allocate counter-field values after beforeCreate so user-land hooks
-        // can run their own logic on the raw payload, but before the flatten/
-        // insert pass so the assigned values are persisted on the same write.
-        // Caller-supplied counter values are overwritten — counters are
-        // allocator-assigned, never user-set.
-        await assignCounterValues({
-            fields: definition.fields,
-            data,
-            counters: db.commands.counters,
-        });
-        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const resolvedPath = explicitPath ?? derivePath(definition, data, defaultLocale, slugifier);
-        // Append-at-end order_key for `orderable: true` collections.
-        // Computed before the insert so the single createDocumentVersion call
-        // carries the key into the byline_documents row. No effect when the
-        // admin config opts out or isn't registered.
-        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
-        // Refresh embedded relation envelopes inside rich-text fields
-        // (internal-link / inline-image nodes) before flatten-and-persist.
-        await applyRichTextEmbed(ctx, data);
-        const result = await db.commands.documents
-            .createDocumentVersion({
-            collectionId,
-            collectionVersion: ctx.collectionVersion,
-            collectionConfig: definition,
-            action: 'create',
-            documentData: data,
-            path: resolvedPath,
-            availableLocales: params.availableLocales,
-            status: params.status ?? data.status ?? getDefaultStatus(definition),
-            locale: params.locale ?? defaultLocale,
-            orderKey,
-        })
-            .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
-        const documentId = extractDocumentId(result.document);
-        const documentVersionId = extractVersionId(result.document);
-        await invokeHook(hooks?.afterCreate, {
-            data,
-            collectionPath,
-            documentId,
-            documentVersionId,
-            path: resolvedPath,
-        });
-        return { documentId, documentVersionId };
-    });
-}
-/**
- * Update a document via full replacement (PUT semantics).
- *
- * Unlike the previous implementation, this now fetches the current version
- * from storage to provide a real `originalData` to hooks.
- *
- * Flow:
- *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`
- *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
- *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
- */
-export async function updateDocument(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocument' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = await resolveHooks(definition);
-        const data = params.data;
-        // Fetch the real original so hooks get accurate originalData (fixes the
-        // PUT handler bug where originalData === data).
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale ?? defaultLocale,
-            reconstruct: true,
-        });
-        const originalData = latest ?? {};
-        normaliseDateFields(data);
-        await invokeHook(hooks?.beforeUpdate, { data, originalData, collectionPath });
-        // Counter fields are immutable: carry their values forward from the
-        // previous version rather than trusting whatever (or nothing) the
-        // caller sent. Lazy-allocates when a counter was added to the
-        // collection after this document was first created.
-        // originalData is the document envelope (with `.fields`, `.path`,
-        // `.document_version_id`); assignCounterValues expects field-shape.
-        await assignCounterValues({
-            fields: definition.fields,
-            data,
-            previousData: originalData.fields ?? originalData,
-            counters: db.commands.counters,
-        });
-        const defaultStatus = getDefaultStatus(definition);
-        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const requestLocale = params.locale ?? defaultLocale;
-        // The document's own content-locale anchor governs which save writes the
-        // path row — not the mutable global default. Falls back to the global
-        // default for rows predating source_locale (not yet backfilled).
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
-        const pathForCommand = resolvePathForUpdate({
-            explicitPath,
-            currentPath: originalData.path,
-            requestLocale,
-            sourceLocale,
-            documentId: params.documentId,
-            logger: ctx.logger,
-        });
-        await applyRichTextEmbed(ctx, data);
-        const result = await db.commands.documents
-            .createDocumentVersion({
-            documentId: params.documentId,
-            collectionId,
-            collectionVersion: ctx.collectionVersion,
-            collectionConfig: definition,
-            action: 'update',
-            documentData: data,
-            path: pathForCommand,
-            availableLocales: params.availableLocales,
-            status: defaultStatus,
-            locale: requestLocale,
-            previousVersionId: originalData.document_version_id,
-        })
-            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
-        const documentId = extractDocumentId(result.document) || params.documentId;
-        const documentVersionId = extractVersionId(result.document);
-        await invokeHook(hooks?.afterUpdate, {
-            data,
-            originalData,
-            collectionPath,
-            documentId,
-            documentVersionId,
-            path: pathForCommand ?? originalData.path,
-        });
-        return { documentId, documentVersionId };
-    });
-}
-/**
- * Update a document via patch application.
- *
- * Flow:
- *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. Optimistic concurrency check on `documentVersionId`
- *   3. `applyPatches(definition, originalData, patches)` → `nextData`
- *   4. `normaliseDateFields(nextData)`
- *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`
- *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
- *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
- *
- * @throws {BylineError} ERR_CONFLICT if the supplied `documentVersionId` does not match the current version.
- * @throws {BylineError} ERR_PATCH_FAILED if `applyPatches` fails.
- */
-export async function updateDocumentWithPatches(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentWithPatches' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = await resolveHooks(definition);
-        // 1. Fetch current document.
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale ?? defaultLocale,
-            reconstruct: true,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        const originalData = latest;
-        // 2. Optimistic concurrency check.
-        if (params.documentVersionId &&
-            params.documentVersionId !== originalData.document_version_id) {
-            throw ERR_CONFLICT({
-                message: 'document has been modified since you loaded it',
-                details: {
-                    currentVersionId: originalData.document_version_id,
-                    yourVersionId: params.documentVersionId,
-                },
-            }).log(ctx.logger);
-        }
-        // 3. Apply patches (patches operate on flat field data, not the full envelope).
-        const { doc: patchedDocument, errors } = applyPatches(definition, originalData.fields ?? {}, params.patches);
-        if (errors.length > 0) {
-            throw ERR_PATCH_FAILED({
-                message: `failed to apply patches: ${errors.map((e) => e.message).join('; ')}`,
-                details: { errors },
-            }).log(ctx.logger);
-        }
-        const nextData = patchedDocument;
-        // 4. Normalise dates.
-        normaliseDateFields(nextData);
-        // 5. beforeUpdate hook.
-        await invokeHook(hooks?.beforeUpdate, { data: nextData, originalData, collectionPath });
-        // 5b. Carry counter values forward from the previous version (or
-        // lazy-allocate if the previous version is missing a value). See
-        // updateDocument for the rationale — patch-based updates are
-        // subject to the same immutability contract.
-        await assignCounterValues({
-            fields: definition.fields,
-            data: nextData,
-            previousData: originalData.fields ?? {},
-            counters: db.commands.counters,
-        });
-        // 6. Persist.
-        const defaultStatus = getDefaultStatus(definition);
-        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const requestLocale = params.locale ?? defaultLocale;
-        // The document's own content-locale anchor governs which save writes the
-        // path row — not the mutable global default. Falls back to the global
-        // default for rows predating source_locale (not yet backfilled).
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
-        const pathForCommand = resolvePathForUpdate({
-            explicitPath,
-            currentPath: originalData.path,
-            requestLocale,
-            sourceLocale,
-            documentId: params.documentId,
-            logger: ctx.logger,
-        });
-        await applyRichTextEmbed(ctx, nextData);
-        const result = await db.commands.documents
-            .createDocumentVersion({
-            documentId: params.documentId,
-            collectionId,
-            collectionVersion: ctx.collectionVersion,
-            collectionConfig: definition,
-            action: 'update',
-            documentData: nextData,
-            path: pathForCommand,
-            availableLocales: params.availableLocales,
-            status: defaultStatus,
-            locale: requestLocale,
-            previousVersionId: originalData.document_version_id,
-        })
-            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
-        const documentId = extractDocumentId(result.document) || params.documentId;
-        const documentVersionId = extractVersionId(result.document);
-        // 7. afterUpdate hook.
-        await invokeHook(hooks?.afterUpdate, {
-            data: nextData,
-            originalData,
-            collectionPath,
-            documentId,
-            documentVersionId,
-            path: pathForCommand ?? originalData.path,
-        });
-        return { documentId, documentVersionId };
-    });
-}
-/**
- * Write a document's system-managed, document-grain fields — `path` and the
- * editorial `availableLocales` set — **without** minting a new version or
- * touching workflow status.
- *
- * These fields are document-grain (they live in `byline_document_paths` and
- * `byline_document_available_locales`, keyed by logical document, sticky across
- * versions), so a workflow status change would falsely imply the edit is gated
- * behind publish. It is not: the write is immediate and applies across every
- * version. This service backs the admin path / available-locales widgets'
- * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
- * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/I18N.md.
- *
- * Flow:
- *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
- *   3. Path (when supplied): `resolvePathForUpdate` enforces the source-locale
- *      rule (translation-locale path edits are dropped with a warn); a real
- *      change is written via `updateDocumentPath`, mapping the unique-constraint
- *      violation to `ERR_PATH_CONFLICT`.
- *   4. `availableLocales` (when supplied): rewritten wholesale via
- *      `setDocumentAvailableLocales`.
- *
- * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the job of the (planned) document-grain audit log.
- *
- * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
- * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
- */
-export async function updateDocumentSystemFields(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentSystemFields' }, async () => {
-        const { db, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const requestLocale = params.locale ?? defaultLocale;
-        // Resolve the document's source-locale anchor + current path. Both feed
-        // the path source-locale guard below; the fetch also asserts existence.
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: requestLocale,
-            reconstruct: true,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        const originalData = latest;
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
-        // Path: honour the same source-locale-only rule the versioned write
-        // uses. `resolvePathForUpdate` returns `undefined` to mean "skip the
-        // write" (null/empty override, or a translation-locale save).
-        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const pathForCommand = resolvePathForUpdate({
-            explicitPath,
-            currentPath: originalData.path,
-            requestLocale,
-            sourceLocale,
-            documentId: params.documentId,
-            logger: ctx.logger,
-        });
-        if (pathForCommand !== undefined) {
-            await db.commands.documents
-                .updateDocumentPath({
-                documentId: params.documentId,
-                collectionId,
-                locale: sourceLocale,
-                path: pathForCommand,
-            })
-                .catch((err) => rethrowPathConflict(err, pathForCommand, defaultLocale));
-        }
-        // Advertised locales: rewrite the document-grain set wholesale.
-        const availableLocalesWritten = params.availableLocales !== undefined;
-        if (params.availableLocales !== undefined) {
-            await db.commands.documents.setDocumentAvailableLocales({
-                documentId: params.documentId,
-                collectionId,
-                availableLocales: params.availableLocales,
-            });
-        }
-        return {
-            documentId: params.documentId,
-            path: pathForCommand,
-            availableLocalesWritten,
-        };
-    });
-}
-/**
- * Change a document's workflow status.
- *
- * Flow:
- *   1. Fetch current document metadata
- *   2. Validate transition via `validateStatusTransition()`
- *   3. `hooks.beforeStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
- *   4. `db.commands.documents.setDocumentStatus(...)` — in-place mutation
- *   5. Auto-archive: if transitioning to `'published'`, archive other published versions
- *   6. `hooks.afterStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
- */
-export async function changeDocumentStatus(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'changeDocumentStatus' }, async () => {
-        const { db, definition, collectionId, collectionPath } = ctx;
-        // Every transition requires the general changeStatus ability.
-        // Transitions that target the `published` status additionally
-        // require the narrower `publish` ability — so installations can
-        // grant "move things through the workflow" without also granting
-        // "flip the final publish switch".
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'changeStatus');
-        if (params.nextStatus === 'published') {
-            assertActorCanPerform(ctx.requestContext, collectionPath, 'publish');
-        }
-        // Single-status workflows (e.g. SINGLE_STATUS_WORKFLOW for lookups)
-        // have no transitions to perform. Reject early with a clear message
-        // rather than relying on the generic ±1-step validator.
-        const workflow = getWorkflow(definition);
-        if (workflow.statuses.length <= 1) {
-            throw ERR_INVALID_TRANSITION({
-                message: `collection '${collectionPath}' has a single-status workflow; status transitions are not supported`,
-                details: { collectionPath, nextStatus: params.nextStatus },
-            }).log(ctx.logger);
-        }
-        const hooks = await resolveHooks(definition);
-        // 1. Fetch current version metadata. No field reconstruction needed —
-        //    status transitions only touch the document_versions.status column.
-        const latest = await db.queries.documents.getCurrentVersionMetadata({
-            collection_id: collectionId,
-            document_id: params.documentId,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        const currentStatus = latest.status ?? 'draft';
-        const documentVersionId = latest.document_version_id;
-        // 2. Validate transition.
-        const result = validateStatusTransition(workflow, currentStatus, params.nextStatus);
-        if (!result.valid) {
-            throw ERR_INVALID_TRANSITION({
-                message: result.reason ??
-                    `invalid status transition from '${currentStatus}' to '${params.nextStatus}'`,
-                details: { currentStatus, nextStatus: params.nextStatus },
-            }).log(ctx.logger);
-        }
-        // Resolve the document's canonical path so the hooks can act on the
-        // specific document/URL (CDN purge, cache-key drop). Narrow lookup —
-        // getCurrentVersionMetadata deliberately omits the path subquery.
-        const path = (await ctx.db.queries.documents.getCurrentPath({
-            collection_id: collectionId,
-            document_id: params.documentId,
-        })) ?? '';
-        const hookCtx = {
-            documentId: params.documentId,
-            documentVersionId,
-            collectionPath,
-            path,
-            previousStatus: currentStatus,
-            nextStatus: params.nextStatus,
-        };
-        // 3. beforeStatusChange hook.
-        await invokeHook(hooks?.beforeStatusChange, hookCtx);
-        // 4. Mutate status in-place.
-        await db.commands.documents.setDocumentStatus({
-            document_version_id: documentVersionId,
-            status: params.nextStatus,
-        });
-        // 5. Auto-archive previous published versions.
-        if (params.nextStatus === 'published') {
-            await db.commands.documents.archivePublishedVersions({
-                document_id: params.documentId,
-                excludeVersionId: documentVersionId,
-            });
-        }
-        // 6. afterStatusChange hook.
-        await invokeHook(hooks?.afterStatusChange, hookCtx);
-        return { previousStatus: currentStatus, newStatus: params.nextStatus };
-    });
-}
-/**
- * Unpublish a document by archiving its published version(s).
- *
- * Flow:
- *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. `db.commands.documents.archivePublishedVersions(...)`
- *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
- */
-export async function unpublishDocument(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'unpublishDocument' }, async () => {
-        const { db, collectionId, collectionPath, definition } = ctx;
-        // Unpublish is a workflow transition out of `published` — reuse the
-        // changeStatus gate rather than a separate ability.
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'changeStatus');
-        // Single-status workflows have nothing to unpublish to.
-        const workflow = getWorkflow(definition);
-        if (workflow.statuses.length <= 1) {
-            throw ERR_INVALID_TRANSITION({
-                message: `collection '${collectionPath}' has a single-status workflow; unpublish is not supported`,
-                details: { collectionPath },
-            }).log(ctx.logger);
-        }
-        const hooks = await resolveHooks(definition);
-        // Resolve the document's canonical path so the hooks can target the
-        // specific document/URL (CDN purge, cache-key drop).
-        const path = (await db.queries.documents.getCurrentPath({
-            collection_id: collectionId,
-            document_id: params.documentId,
-        })) ?? '';
-        await invokeHook(hooks?.beforeUnpublish, {
-            documentId: params.documentId,
-            collectionPath,
-            path,
-        });
-        const archivedCount = await db.commands.documents.archivePublishedVersions({
-            document_id: params.documentId,
-        });
-        await invokeHook(hooks?.afterUnpublish, {
-            documentId: params.documentId,
-            collectionPath,
-            path,
-            archivedCount,
-        });
-        return { archivedCount };
-    });
-}
-/**
- * Restore a historical document version as the new current version.
- *
- * Reads the source version with `locale: 'all'` so the entire multi-locale
- * field tree (with `_id` / `_type` meta inlined onto blocks and array items
- * by `reconstructFromUnifiedRows`) is captured. That tree is then re-emitted
- * through `createDocumentVersion` with `locale: 'all'`, which produces a
- * fresh version row with a new UUIDv7 id and the latest `created_at`. The
- * `current_documents` view (`ROW_NUMBER() OVER PARTITION BY document_id
- * ORDER BY created_at DESC`) automatically promotes the new row to current.
- *
- * Status is hard-defaulted to the workflow's first status — restoring an
- * old `published` version must never silently re-publish content. The user
- * runs the restored draft through the normal workflow.
- *
- * `path` is sticky from the previous current version (not from the source),
- * matching the semantics of `updateDocument`. A path change made between
- * the source and now should not be undone by the restore.
- *
- * Auth reuses the `update` ability — restore is conceptually an edit
- * against an existing document.
- *
- * Hooks: fires `beforeUpdate` / `afterUpdate` with a `restore: { sourceVersionId }`
- * field on the context. Userland hooks that need to react differently
- * (e.g. tag the audit entry, skip search re-index) can branch on its
- * presence.
- *
- * Flow:
- *   1. Auth: `update` ability.
- *   2. Read source version with `locale: 'all'`.
- *   3. Validate source belongs to `documentId` (defence against forged
- *      cross-document version ids).
- *   4. Read current version metadata; reject if the source IS already the
- *      current version (nothing to restore).
- *   5. Read current document with reconstruction for hook `originalData`.
- *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, restore })`
- *   7. `db.commands.documents.createDocumentVersion(...)` with
- *      `action: 'restore'`, `locale: 'all'`, sticky path, default status.
- *   8. `hooks.afterUpdate({ ..., restore })`
- */
-export async function restoreDocumentVersion(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'restoreDocumentVersion' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = await resolveHooks(definition);
-        // 1. Read source version (full multi-locale tree).
-        const source = await db.queries.documents.getDocumentByVersion({
-            document_version_id: params.sourceVersionId,
-            locale: 'all',
-        });
-        if (source == null) {
-            throw ERR_NOT_FOUND({
-                message: 'source version not found',
-                details: { sourceVersionId: params.sourceVersionId },
-            }).log(ctx.logger);
-        }
-        // 2. Cross-document forgery check.
-        if (source.document_id !== params.documentId) {
-            throw ERR_VALIDATION({
-                message: 'source version does not belong to the target document',
-                details: {
-                    documentId: params.documentId,
-                    sourceVersionId: params.sourceVersionId,
-                    sourceDocumentId: source.document_id,
-                },
-            }).log(ctx.logger);
-        }
-        // 3. Current version metadata — used both for the already-current
-        //    guard and for the sticky path resolution.
-        const currentMeta = await db.queries.documents.getCurrentVersionMetadata({
-            collection_id: collectionId,
-            document_id: params.documentId,
-        });
-        if (currentMeta == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        if (currentMeta.document_version_id === params.sourceVersionId) {
-            throw ERR_INVALID_TRANSITION({
-                message: 'source version is already the current version of this document',
-                details: {
-                    documentId: params.documentId,
-                    sourceVersionId: params.sourceVersionId,
-                },
-            }).log(ctx.logger);
-        }
-        // 4. originalData for hooks: full reconstruction of the current
-        //    version (locale-scoped, matching updateDocument's semantics).
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: defaultLocale,
-            reconstruct: true,
-        });
-        const originalData = latest ?? {};
-        const sourceFields = source.fields ?? {};
-        const restoreContext = { sourceVersionId: params.sourceVersionId };
-        // 5. beforeUpdate.
-        await invokeHook(hooks?.beforeUpdate, {
-            data: sourceFields,
-            originalData,
-            collectionPath,
-            restore: restoreContext,
-        });
-        // Embed walker is a no-op here for localized richtext leaves
-        // (multi-locale `{ locale: lexJson }` shape — see
-        // richtext-embed.ts header). Non-localized richtext leaves still
-        // get refreshed, so leave the call in for that branch.
-        await applyRichTextEmbed(ctx, sourceFields);
-        // 6. Persist new version. locale: 'all' carries every locale row in
-        //    the source tree forward in a single flatten pass — the
-        //    cross-locale carry-forward branch in createDocumentVersion does
-        //    not fire when locale === 'all'.
-        //
-        // No `path` is passed: restore does not change the document's path
-        // (the existing byline_document_paths row stays as-is — sticky).
-        const result = await db.commands.documents.createDocumentVersion({
-            documentId: params.documentId,
-            collectionId,
-            collectionVersion: ctx.collectionVersion,
-            collectionConfig: definition,
-            action: 'restore',
-            documentData: sourceFields,
-            status: getDefaultStatus(definition),
-            locale: 'all',
-            previousVersionId: currentMeta.document_version_id,
-        });
-        const documentId = extractDocumentId(result.document) || params.documentId;
-        const documentVersionId = extractVersionId(result.document);
-        // 7. afterUpdate. Restore is path-sticky: the canonical path comes
-        //    from the current version's envelope (originalData), not the source.
-        await invokeHook(hooks?.afterUpdate, {
-            data: sourceFields,
-            originalData,
-            collectionPath,
-            documentId,
-            documentVersionId,
-            path: originalData.path ?? '',
-            restore: restoreContext,
-        });
-        return {
-            documentId,
-            documentVersionId,
-            sourceVersionId: params.sourceVersionId,
-        };
-    });
-}
-/**
- * Soft-delete a document.
- *
- * Marks all versions of the document as deleted (`is_deleted = true`). The
- * `current_documents` view automatically filters deleted rows, so the
- * document disappears from all list / page queries without physically
- * removing data.
- *
- * When the collection has any upload-capable image/file field and
- * `ctx.storage` is provided, every original file and persisted variant
- * across those fields is also removed from storage after the DB
- * soft-delete succeeds. Variant paths are read from the field value's
- * `variants` array (no re-derivation from `upload.sizes`), so cleanup
- * stays correct even if the size set changed between upload and delete.
- * File cleanup failures are logged but are non-fatal.
- *
- * Flow:
- *   1. Fetch current document (reconstruct when upload-capable fields exist)
- *   2. `hooks.beforeDelete({ documentId, collectionPath })`
- *   3. `db.commands.documents.softDeleteDocument({ document_id })`
- *   4. Storage file + variant cleanup (skipped when no upload fields, non-fatal)
- *   5. `hooks.afterDelete({ documentId, collectionPath })`
- */
-export async function deleteDocument(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteDocument' }, async () => {
-        const { db, collectionPath, definition, logger } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'delete');
-        const hooks = await resolveHooks(definition);
-        // 1. Verify the document exists.
-        //    For collections that have any upload-capable image/file field
-        //    AND a storage provider, fetch with reconstruct: true so we
-        //    can read the stored file paths (and persisted variant paths)
-        //    from the field values before the DB rows are deleted.
-        const uploadFieldNames = getUploadFields(definition).map((f) => f.name);
-        const isUploadCollection = uploadFieldNames.length > 0 && ctx.storage != null;
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: ctx.collectionId,
-            document_id: params.documentId,
-            reconstruct: isUploadCollection,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        // Collect storage paths for every upload-capable field on the doc:
-        // the original file plus every persisted variant. Reading the
-        // variants from the field value (rather than re-deriving from
-        // `upload.sizes`) keeps cleanup correct even when the size set
-        // changes between upload and delete.
-        const storagePathsToDelete = [];
-        if (isUploadCollection) {
-            for (const fieldName of uploadFieldNames) {
-                const fieldValue = latest?.fields?.[fieldName];
-                if (!fieldValue || typeof fieldValue !== 'object')
-                    continue;
-                if (typeof fieldValue.storagePath === 'string') {
-                    storagePathsToDelete.push(fieldValue.storagePath);
-                }
-                if (Array.isArray(fieldValue.variants)) {
-                    for (const variant of fieldValue.variants) {
-                        if (variant && typeof variant.storagePath === 'string') {
-                            storagePathsToDelete.push(variant.storagePath);
-                        }
-                    }
-                }
-            }
-        }
-        const hookCtx = {
-            documentId: params.documentId,
-            collectionPath,
-            // The current document was fetched above (reconstructed only for
-            // upload collections, but the envelope carries the locale-resolved
-            // `path` projection either way). Surface it so delete hooks can purge
-            // the specific document/URL.
-            path: latest.path ?? '',
-        };
-        // 2. beforeDelete hook.
-        await invokeHook(hooks?.beforeDelete, hookCtx);
-        // 3. Soft-delete all versions.
-        const deletedVersionCount = await db.commands.documents.softDeleteDocument({
-            document_id: params.documentId,
-        });
-        // 4. Clean up storage files. Non-fatal: logs errors but does not throw.
-        if (ctx.storage && storagePathsToDelete.length > 0) {
-            for (const storagePath of storagePathsToDelete) {
-                try {
-                    await ctx.storage.delete(storagePath);
-                }
-                catch (err) {
-                    logger.error({ err, storagePath }, 'failed to delete storage file');
-                }
-            }
-        }
-        // 5. afterDelete hook.
-        await invokeHook(hooks?.afterDelete, hookCtx);
-        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 = await resolveHooks(definition);
-        // 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,
-        });
-        // 6b. Reset counter fields to freshly-allocated values. The clone
-        // currently carries the source document's counter values; without
-        // this pass, the duplicate would alias the source's facet IDs and
-        // break the "one ID per term" contract.
-        await assignCounterValues({
-            fields: definition.fields,
-            data: clonedFields,
-            counters: db.commands.counters,
-        });
-        // 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;
-        // Append-at-end order_key for `orderable: true` collections. Computed
-        // before the insert; the source row's order is intentionally not
-        // copied — duplicates land at the end of the list.
-        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
-        // Embed walker (no-op for multi-locale richtext leaves — see
-        // restoreDocumentVersion for the same caveat).
-        await applyRichTextEmbed(ctx, clonedFields);
-        try {
-            result = await db.commands.documents
-                .createDocumentVersion({
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
-                action: 'create',
-                documentData: clonedFields,
-                path: finalPath,
-                status: defaultStatus,
-                locale: 'all',
-                orderKey,
-            })
-                .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',
-                orderKey,
-            })
-                .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,
-            path: finalPath,
-            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 = await resolveHooks(definition);
-        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;
-        await applyRichTextEmbed(ctx, merged.data);
-        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,
-            // Path is sticky and source-locale-anchored; copy-to-locale never
-            // touches it. Read it off the target envelope.
-            path: targetRecord.path ?? '',
-            copyToLocale: copyToLocaleMarker,
-        });
-        return {
-            documentId: params.documentId,
-            documentVersionId,
-            sourceLocale: params.sourceLocale,
-            targetLocale: params.targetLocale,
-            fieldsUpdated: merged.fieldsUpdated,
-        };
-    });
-}
-// ---------------------------------------------------------------------------
-// deleteLocale
-// ---------------------------------------------------------------------------
-/**
- * Remove one content locale's data from a document, in place on the same
- * document, by writing a new immutable version that omits that locale's
- * store rows (every other locale and all non-localized `'all'` rows are
- * carried forward by the storage primitive).
- *
- * The default content locale is the document's anchor (path + source_locale)
- * and can never be removed — rejected up front. The new version lands as the
- * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
- * previously-published version keeps serving — including the locale being
- * removed — until the new version is reviewed and published. The deletion is
- * recoverable: the prior version still holds the locale, so restoring it
- * brings the content back.
- *
- * Flow:
- *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
- *   2. Reject `locale === defaultLocale`.
- *   3. Read the document in the target locale (validates existence; supplies
- *      `originalData` for hooks and the availability set for the presence
- *      check).
- *   4. Reject when the locale has no content to delete.
- *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
- *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
- *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
- */
-export async function deleteLocale(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        // The default locale anchors the document's path and source_locale —
-        // it cannot be deleted (the other locales fall back to it).
-        if (params.locale === defaultLocale) {
-            throw ERR_VALIDATION({
-                message: `cannot delete the default content locale ('${defaultLocale}')`,
-                details: { documentId: params.documentId, locale: params.locale, collectionPath },
-            }).log(ctx.logger);
-        }
-        // Read the document in the locale being removed — validates existence,
-        // supplies originalData for hooks, and the availability set for the
-        // content-presence check below.
-        const target = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale,
-            reconstruct: true,
-            lenient: true,
-            requestContext: ctx.requestContext,
-        });
-        if (target == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId, collectionPath },
-            }).log(ctx.logger);
-        }
-        const targetRecord = target;
-        // `_availableVersionLocales` is the derived (path-coverage) set; it is
-        // the same source the editor's Delete-Locale picker is built from, so a
-        // locale offered in the UI resolves here. A partially-translated locale
-        // that never reached full coverage is not deletable through this path.
-        const available = targetRecord._availableVersionLocales ?? [];
-        if (!available.includes(params.locale)) {
-            throw ERR_NOT_FOUND({
-                message: `locale '${params.locale}' has no content to delete`,
-                details: { documentId: params.documentId, locale: params.locale, collectionPath },
-            }).log(ctx.logger);
-        }
-        const hooks = await resolveHooks(definition);
-        const deleteLocaleMarker = { locale: params.locale };
-        const originalData = targetRecord.fields ?? {};
-        await invokeHook(hooks?.beforeUpdate, {
-            data: originalData,
-            originalData,
-            collectionPath,
-            deleteLocale: deleteLocaleMarker,
-        });
-        const result = await db.commands.documents.deleteDocumentLocale({
-            documentId: params.documentId,
-            locale: params.locale,
-            status: getDefaultStatus(definition),
-        });
-        if (result == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId, collectionPath },
-            }).log(ctx.logger);
-        }
-        await invokeHook(hooks?.afterUpdate, {
-            data: originalData,
-            originalData,
-            collectionPath,
-            documentId: params.documentId,
-            documentVersionId: result.newVersionId,
-            // Path is sticky and source-locale-anchored; deleting a translation
-            // never touches it. Read it off the target envelope.
-            path: targetRecord.path ?? '',
-            deleteLocale: deleteLocaleMarker,
-        });
-        return {
-            documentId: params.documentId,
-            documentVersionId: result.newVersionId,
-            locale: params.locale,
-        };
-    });
-}