@byline/core 3.5.1 → 3.7.0

package/dist/services/document-lifecycle/internals.js

@@ -0,0 +1,218 @@
+/**
+ * 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
+ */
+/**
+ * Helpers shared by the per-operation lifecycle modules. Internal to the
+ * `document-lifecycle/` directory — nothing here is re-exported through
+ * the barrel (`index.ts`), so the package's public surface is unchanged
+ * by the per-operation split.
+ */
+import { normalizeCollectionHook, } from '../../@types/index.js';
+import { getCollectionDefinition, getServerConfig } from '../../config/config.js';
+import { ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
+import { generateKeyBetween } from '../../lib/fractional-index.js';
+import { createReadContext } from '../populate.js';
+import { embedRichTextFields } from '../richtext-embed.js';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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`. */
+export function extractVersionId(document) {
+    return document?.id ?? document?.document_version_id ?? '';
+}
+/** Extract the logical document id from the document object returned by `createDocumentVersion`. */
+export function extractDocumentId(document) {
+    return document?.document_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`.
+ */
+export 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;
+}
+/**
+ * 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.
+ */
+export function isPathConflictError(err) {
+    return (err != null &&
+        typeof err === 'object' &&
+        err.code === ErrorCodes.PATH_CONFLICT);
+}
+/**
+ * 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).
+ */
+export 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;
+}
+/**
+ * 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.
+ */
+export 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();
+}
+/**
+ * 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.
+ */
+export 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]);
+        }
+    }
+}

package/dist/services/document-lifecycle/merge-locale-data.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ */
+/**
+ * Copy-to-Locale merge walker.
+ *
+ * Schema-aware, pure tree merge used by `copyToLocale` to decide, leaf by
+ * leaf, whether to take the source locale's value or keep the target's.
+ */
+import { type FieldSet } from '../../@types/index.js';
+/**
+ * Result of merging source-locale and target-locale data trees for
+ * `copyToLocale`. `data` is the payload to hand to
+ * `createDocumentVersion`; `fieldsUpdated` counts every localized leaf
+ * the merge rule chose to overwrite (used for UI toasts).
+ */
+export interface CopyToLocaleMergeResult {
+    data: Record<string, any>;
+    fieldsUpdated: number;
+}
+/**
+ * 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`.
+ */
+export declare function mergeLocaleData(fields: FieldSet, sourceData: Record<string, any> | null | undefined, targetData: Record<string, any> | null | undefined, overwrite: boolean): CopyToLocaleMergeResult;

package/dist/services/document-lifecycle/merge-locale-data.js

@@ -0,0 +1,147 @@
+/**
+ * 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
+ */
+/**
+ * Copy-to-Locale merge walker.
+ *
+ * Schema-aware, pure tree merge used by `copyToLocale` to decide, leaf by
+ * leaf, whether to take the source locale's value or keep the target's.
+ */
+import { isArrayField, isBlocksField, isGroupField, } from '../../@types/index.js';
+/**
+ * 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`.
+ */
+export 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);
+}

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

@@ -0,0 +1,57 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface RestoreVersionResult {
+    documentId: string;
+    documentVersionId: string;
+    sourceVersionId: string;
+}
+/**
+ * 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 declare function restoreDocumentVersion(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    sourceVersionId: string;
+}): Promise<RestoreVersionResult>;

package/dist/services/document-lifecycle/restore.js

@@ -0,0 +1,162 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
+/**
+ * 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,
+        };
+    });
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface ChangeStatusResult {
+    previousStatus: string;
+    newStatus: string;
+}
+export interface UnpublishResult {
+    archivedCount: number;
+}
+/**
+ * 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 declare function changeDocumentStatus(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    nextStatus: string;
+}): Promise<ChangeStatusResult>;
+/**
+ * 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 declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+}): Promise<UnpublishResult>;