@byline/core 3.5.1 → 3.7.0

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

@@ -0,0 +1,150 @@
+/**
+ * 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 } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getWorkflow, validateStatusTransition } from '../../workflow/workflow.js';
+import { invokeHook } from './internals.js';
+/**
+ * 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 };
+    });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 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 UpdateDocumentSystemFieldsResult {
+    documentId: string;
+    /** The path actually written, or `undefined` when no path write occurred. */
+    path?: string;
+    /** Whether the advertised-locale set was rewritten this call. */
+    availableLocalesWritten: boolean;
+}
+/**
+ * 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 declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    locale?: string;
+    /**
+     * Explicit path override from the path widget. `null` / empty / omitted
+     * means "no path write" (the existing row stays sticky). A non-empty
+     * string is written when the request locale is the document's source
+     * locale; on a translation locale it is dropped with a warn.
+     */
+    path?: string | null;
+    /**
+     * The editorial advertised-locale set from the available-locales widget.
+     * `undefined` means "no advertised-locale write"; an explicit array — `[]`
+     * included — replaces the set wholesale.
+     */
+    availableLocales?: string[];
+}): Promise<UpdateDocumentSystemFieldsResult>;

package/dist/services/document-lifecycle/system-fields.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
+/**
+ * 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,
+        };
+    });
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 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 { DocumentPatch } from '../../patches/index.js';
+import type { DocumentLifecycleContext } from './context.js';
+export interface UpdateDocumentResult {
+    documentId: string;
+    documentVersionId: string;
+}
+export interface UpdateDocumentWithPatchesResult {
+    documentId: string;
+    documentVersionId: string;
+}
+/**
+ * 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 declare function updateDocument(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    data: Record<string, any>;
+    locale?: string;
+    /**
+     * Explicit path override. When omitted, the previous version's path
+     * carries forward unchanged (sticky). The lifecycle never re-derives
+     * `path` from the source field on update — that is an explicit user
+     * action driven by the admin path widget.
+     */
+    path?: string;
+    /**
+     * The editorial advertised-locale set. `undefined` leaves the existing
+     * set untouched (sticky — document-grain, like `path`); an explicit array
+     * (empty included) replaces it wholesale. Driven by the admin
+     * available-locales sidebar widget. See docs/I18N.md.
+     */
+    availableLocales?: string[];
+}): Promise<UpdateDocumentResult>;
+/**
+ * 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 declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    patches: DocumentPatch[];
+    /** Client-supplied version ID for optimistic concurrency. */
+    documentVersionId?: string;
+    locale?: string;
+    /**
+     * Explicit path override (typically supplied alongside patches when
+     * the admin path widget has been edited). When omitted, sticky from
+     * the previous version.
+     */
+    path?: string;
+    /**
+     * The editorial advertised-locale set (typically supplied alongside
+     * patches when the admin available-locales widget has been edited).
+     * `undefined` leaves the existing set untouched (sticky); an explicit
+     * array replaces it wholesale. See docs/I18N.md.
+     */
+    availableLocales?: string[];
+}): Promise<UpdateDocumentWithPatchesResult>;

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

@@ -0,0 +1,216 @@
+/**
+ * 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_CONFLICT, ERR_NOT_FOUND, ERR_PATCH_FAILED } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { applyPatches } from '../../patches/index.js';
+import { normaliseDateFields } from '../../utils/normalise-dates.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { assignCounterValues } from '../assign-counter-values.js';
+import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+/**
+ * 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 };
+    });
+}

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

@@ -8,7 +8,7 @@
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { BylineError, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
-import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle.js';
+import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
 // ---------------------------------------------------------------------------