@byline/core 3.20.4 → 4.0.0

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

@@ -7,13 +7,31 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { ERR_NOT_FOUND, ErrorCodes } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { hasUploadField, isUploadField } from '../../utils/storage-utils.js';
 import { walkFieldTree } from '../walk-field-tree.js';
-import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability, requireTreeAuditCapability, } from './audit.js';
 import { invokeHook } from './internals.js';
-import { promoteChildrenAndRemove } from './tree.js';
+import { firePromoteTreeChange, reconcileTreeOnDeleteInTransaction } from './tree.js';
+function readErrorCode(error) {
+    try {
+        if ((typeof error !== 'object' || error === null) && typeof error !== 'function') {
+            return undefined;
+        }
+        const value = Reflect.get(error, 'code');
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function serializeSideEffectFailure(phase, error) {
+    return {
+        phase,
+        code: readErrorCode(error) === ErrorCodes.STORAGE ? ErrorCodes.STORAGE : ErrorCodes.UNHANDLED,
+    };
+}
 /**
  * Soft-delete a document.
  *
@@ -47,7 +65,8 @@ export async function deleteDocument(ctx, params) {
         //    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 isUploadCollection = hasUploadField(definition) && ctx.storage != null;
+        const storage = ctx.storage;
+        const isUploadCollection = hasUploadField(definition) && storage != null;
         const latest = await db.queries.documents.getDocumentById({
             collection_id: ctx.collectionId,
             document_id: params.documentId,
@@ -99,15 +118,20 @@ export async function deleteDocument(ctx, params) {
         };
         // 2. beforeDelete hook.
         await invokeHook(hooks?.beforeDelete, hookCtx);
-        // 3. Soft-delete all versions, atomically with the audit record. A
+        // 3. Soft-delete all versions atomically with the document audit and,
+        //    for tree collections, locked child promotion/removal plus every
+        //    parent/child tree audit row. Any failure rolls the entire delete
+        //    back, so soft-deleted documents cannot leak live edges.
         //    whole-document delete mints no new version, so the version stream
         //    never records it — the audit log is the only place a deletion is
         //    accountable (docs/06-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
         //    DB↔external side-effect and stays OUTSIDE the transaction — it is
         //    post-commit, best-effort compensation (docs/03-architecture/03-transactions.md).
-        const audit = requireAuditCapability(db);
+        const treeAudit = definition.tree === true ? requireTreeAuditCapability(db) : undefined;
+        const audit = treeAudit ?? requireAuditCapability(db);
         const actor = auditActor(ctx);
         let deletedVersionCount = 0;
+        let treeResult;
         await audit.withTransaction(async () => {
             deletedVersionCount = await db.commands.documents.softDeleteDocument({
                 document_id: params.documentId,
@@ -119,36 +143,77 @@ export async function deleteDocument(ctx, params) {
                 actorRealm: actor.actorRealm,
                 action: AUDIT_ACTIONS.deleted,
             });
+            if (treeAudit != null) {
+                treeResult = await reconcileTreeOnDeleteInTransaction(ctx, params.documentId, treeAudit);
+            }
         });
-        // 4. Clean up storage files. Non-fatal: logs errors but does not throw.
-        if (ctx.storage && storagePathsToDelete.length > 0) {
+        // Everything below is post-commit. Each operation and the logger get an
+        // independent attempt; none can turn the committed delete into a rejection.
+        const sideEffectFailures = [];
+        // 4. Clean up every storage file. Returned failures omit paths, while
+        // internal logs retain the target needed for operational reconciliation.
+        if (storage && storagePathsToDelete.length > 0) {
             for (const storagePath of storagePathsToDelete) {
                 try {
-                    await ctx.storage.delete(storagePath);
+                    await storage.delete(storagePath);
                 }
-                catch (err) {
-                    logger.error({ err, storagePath }, 'failed to delete storage file');
+                catch (error) {
+                    sideEffectFailures.push(serializeSideEffectFailure('storageCleanup', error));
+                    try {
+                        logger.error({ err: error, documentId: params.documentId, storagePath }, 'failed to delete storage file');
+                    }
+                    catch {
+                        // Diagnostic logging must not interrupt the remaining cleanup attempts.
+                    }
                 }
             }
         }
-        // 5. Reconcile the document tree for `tree: true` collections. Byline
-        //    deletes are soft (the document row survives), so the table's
-        //    promote/cascade foreign keys never fire — promote the node's
-        //    children to root and remove its edge here instead, firing the
-        //    structural-change invalidation event. Post-commit and best-effort,
-        //    like file cleanup: a failure here leaves the soft-delete intact
-        //    (status-at-edge already hides the deleted node's subtree from
-        //    reads) and is logged rather than thrown. See docs/04-collections/03-document-trees.md.
-        if (definition.tree === true) {
+        // 5-6. Both post-commit hook families get an independent attempt. A tree
+        // invalidation failure must not prevent afterDelete consumers (search,
+        // cache removal) from running, or vice versa.
+        try {
+            if (treeResult != null) {
+                await firePromoteTreeChange(ctx, params.documentId, treeResult);
+            }
+        }
+        catch (error) {
+            sideEffectFailures.push(serializeSideEffectFailure('afterTreeChange', error));
+            try {
+                logger.error({ err: error, documentId: params.documentId }, 'afterTreeChange hook failed after document delete');
+            }
+            catch {
+                // Diagnostic logging must not affect the committed result.
+            }
+        }
+        try {
+            await invokeHook(hooks?.afterDelete, hookCtx);
+        }
+        catch (error) {
+            sideEffectFailures.push(serializeSideEffectFailure('afterDelete', error));
+            try {
+                logger.error({ err: error, documentId: params.documentId }, 'afterDelete hook failed after document delete');
+            }
+            catch {
+                // Diagnostic logging must not affect the committed result.
+            }
+        }
+        const [firstFailure, ...remainingFailures] = sideEffectFailures;
+        if (firstFailure != null) {
             try {
-                await promoteChildrenAndRemove(ctx, { documentId: params.documentId });
+                logger.error({
+                    documentId: params.documentId,
+                    sideEffectFailures: [firstFailure, ...remainingFailures],
+                }, 'post-commit delete side effects failed');
             }
-            catch (err) {
-                logger.error({ err, documentId: params.documentId }, 'failed to reconcile document tree on delete');
+            catch {
+                // A reporting failure cannot change the already-committed outcome.
             }
+            return {
+                deletedVersionCount,
+                outcome: 'committed-with-side-effect-failures',
+                sideEffectFailures: [firstFailure, ...remainingFailures],
+            };
         }
-        // 6. afterDelete hook.
-        await invokeHook(hooks?.afterDelete, hookCtx);
-        return { deletedVersionCount };
+        return { deletedVersionCount, outcome: 'committed', sideEffectFailures: [] };
     });
 }

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

@@ -35,7 +35,7 @@ export { updateDocument, updateDocumentWithPatches } from './update.js';
 export type { DocumentLifecycleContext } from './context.js';
 export type { CopyToLocaleResult } from './copy-to-locale.js';
 export type { CreateDocumentResult } from './create.js';
-export type { DeleteDocumentResult } from './delete.js';
+export type { DeleteDocumentCommittedResult, DeleteDocumentCommittedWithSideEffectFailuresResult, DeleteDocumentOutcome, DeleteDocumentResult, DeleteDocumentSideEffectCode, DeleteDocumentSideEffectFailure, DeleteDocumentSideEffectPhase, } from './delete.js';
 export type { DeleteLocaleResult } from './delete-locale.js';
 export type { DuplicateDocumentResult } from './duplicate.js';
 export type { RestoreVersionResult } from './restore.js';

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

@@ -59,26 +59,6 @@ export declare function applyRichTextEmbed(ctx: DocumentLifecycleContext, data:
  * gets `order_key = NULL` and the existing "no ordering" behavior holds.
  */
 export declare function maybeAppendOrderKey(ctx: DocumentLifecycleContext, collectionPath: string): Promise<string | undefined>;
-/**
- * Append a document as the **last root** of its `tree: true` collection's tree.
- * Mints a fresh root-group `order_key` after the current trailing root. Used by
- * create's auto-place and update's self-heal so a tree collection never strands a
- * document in the "unplaced" limbo. Issues the storage command directly — the
- * caller has already asserted the relevant ability and this is a system step.
- */
-export declare function appendTreeRoot(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
-/**
- * Self-heal a genuinely-*unplaced* document on update: if the collection is a
- * tree and the document has no edge row, append it as a root (mirroring create's
- * auto-place). `getTreeParent` distinguishes unplaced from root, so an existing
- * root or child is left exactly where it is — only strays (e.g. docs created
- * before the flag, or whose create-time auto-place failed) are re-treed.
- *
- * No-op for non-tree collections. Best-effort and post-version: a failure leaves
- * the document saved-but-unplaced and is logged, never thrown. See
- * docs/04-collections/03-document-trees.md.
- */
-export declare function selfHealTreePlacement(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 export declare function extractVersionId(document: any): string;
 /** Extract the logical document id from the document object returned by `createDocumentVersion`. */

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

@@ -17,6 +17,7 @@ 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';
+import { createRichTextDocumentReader } from '../richtext-populate.js';
 /**
  * Matches a canonical UUID (any version). Real admin / end-user actors carry
  * UUID ids (`uuidv7`); synthetic actors do not.
@@ -70,20 +71,38 @@ export async function applyRichTextEmbed(ctx, data) {
     // `initBylineCore()` (unit tests, isolated tooling) — they have no
     // adapter to invoke, so this is a soft no-op.
     let embed;
+    let richTextPopulate;
+    let collections;
     try {
-        embed = getServerConfig().fields?.richText?.embed;
+        const config = getServerConfig();
+        embed = config.fields?.richText?.embed;
+        richTextPopulate = config.fields?.richText?.populate;
+        collections = config.collections;
     }
     catch {
         return;
     }
-    if (embed == null)
+    if (embed == null || ctx.requestContext == null)
         return;
+    const readContext = createReadContext();
+    const requestContext = { ...ctx.requestContext, readMode: 'published' };
     await embedRichTextFields({
         fields: ctx.definition.fields,
         collectionPath: ctx.collectionPath,
         data,
         embed,
-        readContext: createReadContext(),
+        readContext,
+        requestContext,
+        readMode: 'published',
+        readDocuments: createRichTextDocumentReader({
+            db: ctx.db,
+            collections,
+            requestContext,
+            readContext,
+            readMode: 'published',
+            locale: ctx.defaultLocale,
+            richTextPopulate,
+        }),
         logger: ctx.logger,
     });
 }
@@ -103,49 +122,6 @@ export async function maybeAppendOrderKey(ctx, collectionPath) {
     });
     return generateKeyBetween(last, null);
 }
-/**
- * Append a document as the **last root** of its `tree: true` collection's tree.
- * Mints a fresh root-group `order_key` after the current trailing root. Used by
- * create's auto-place and update's self-heal so a tree collection never strands a
- * document in the "unplaced" limbo. Issues the storage command directly — the
- * caller has already asserted the relevant ability and this is a system step.
- */
-export async function appendTreeRoot(ctx, documentId) {
-    const roots = await ctx.db.queries.documents.getTreeChildren({
-        collectionId: ctx.collectionId,
-        parentDocumentId: null,
-    });
-    await ctx.db.commands.documents.placeTreeNode({
-        collectionId: ctx.collectionId,
-        documentId,
-        parentDocumentId: null,
-        beforeDocumentId: roots.at(-1)?.document_id ?? null,
-    });
-}
-/**
- * Self-heal a genuinely-*unplaced* document on update: if the collection is a
- * tree and the document has no edge row, append it as a root (mirroring create's
- * auto-place). `getTreeParent` distinguishes unplaced from root, so an existing
- * root or child is left exactly where it is — only strays (e.g. docs created
- * before the flag, or whose create-time auto-place failed) are re-treed.
- *
- * No-op for non-tree collections. Best-effort and post-version: a failure leaves
- * the document saved-but-unplaced and is logged, never thrown. See
- * docs/04-collections/03-document-trees.md.
- */
-export async function selfHealTreePlacement(ctx, documentId) {
-    if (ctx.definition.tree !== true)
-        return;
-    try {
-        const { placed } = await ctx.db.queries.documents.getTreeParent({ document_id: documentId });
-        if (placed)
-            return;
-        await appendTreeRoot(ctx, documentId);
-    }
-    catch (err) {
-        ctx.logger.error({ err, documentId }, 'failed to self-heal tree placement on update');
-    }
-}
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 export function extractVersionId(document) {
     return document?.id ?? document?.document_version_id ?? '';

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

@@ -33,7 +33,7 @@ export declare function changeDocumentStatus(ctx: DocumentLifecycleContext, para
  *
  * Flow:
  *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. `db.commands.documents.archivePublishedVersions(...)`
+ *   2. Archive published versions and append the status audit atomically
  *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
  */
 export declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {

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

@@ -124,7 +124,7 @@ export async function changeDocumentStatus(ctx, params) {
  *
  * Flow:
  *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. `db.commands.documents.archivePublishedVersions(...)`
+ *   2. Archive published versions and append the status audit atomically
  *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
  */
 export async function unpublishDocument(ctx, params) {
@@ -153,8 +153,25 @@ export async function unpublishDocument(ctx, params) {
             collectionPath,
             path,
         });
-        const archivedCount = await db.commands.documents.archivePublishedVersions({
-            document_id: params.documentId,
+        const audit = requireAuditCapability(db);
+        const actor = auditActor(ctx);
+        const archivedCount = await audit.withTransaction(async () => {
+            const count = await db.commands.documents.archivePublishedVersions({
+                document_id: params.documentId,
+            });
+            if (count > 0) {
+                await audit.append({
+                    documentId: params.documentId,
+                    collectionId,
+                    actorId: actor.actorId,
+                    actorRealm: actor.actorRealm,
+                    action: AUDIT_ACTIONS.statusChanged,
+                    field: 'status',
+                    before: 'published',
+                    after: 'archived',
+                });
+            }
+            return count;
         });
         await invokeHook(hooks?.afterUnpublish, {
             documentId: params.documentId,

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

@@ -10,7 +10,13 @@ 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. */
+    /** Whether either system field actually changed. */
+    changed: boolean;
+    /** Whether a no-op request emitted the reconciliation hook. */
+    reconciliation: boolean;
+    pathChanged: boolean;
+    availableLocalesChanged: boolean;
+    /** Whether the advertised-locale set was actually rewritten this call. */
     availableLocalesWritten: boolean;
 }
 /**
@@ -29,7 +35,8 @@ export interface UpdateDocumentSystemFieldsResult {
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
+ *   2. Inside the audit transaction, lock the logical document and read its
+ *      authoritative source locale, path, and advertised locales.
  *   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
@@ -37,10 +44,14 @@ export interface UpdateDocumentSystemFieldsResult {
  *   4. `availableLocales` (when supplied): rewritten wholesale via
  *      `setDocumentAvailableLocales`.
  *
- * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the document-grain audit log: each field that actually
- * changes records a `document.path.changed` / `document.locales.changed` row
- * atomically with the write (docs/06-auth-and-security/02-auditability.md — Workstream 2).
+ * Content hooks do not fire because these are not content writes. Actual
+ * changes emit `afterSystemFieldsChange` after the audited write commits. A
+ * caller can pass `reconcile: true` to emit the same hook for a no-op retry
+ * after an earlier post-commit hook failure. Hook failures reject the call but
+ * never roll back the already-committed write/audit.
+ * Accountability for these mutations is the document-grain audit log: each
+ * changed field records a `document.path.changed` /
+ * `document.locales.changed` row atomically with the write.
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
@@ -61,4 +72,6 @@ export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext
      * included — replaces the set wholesale.
      */
     availableLocales?: string[];
+    /** Re-run `afterSystemFieldsChange` when requested values are already current. */
+    reconcile?: boolean;
 }): Promise<UpdateDocumentSystemFieldsResult>;

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

@@ -5,11 +5,12 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { ERR_AUDIT_UNSUPPORTED, ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability, sameLocaleSet } from './audit.js';
-import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
+import { invokeHook, 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
@@ -26,7 +27,8 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
+ *   2. Inside the audit transaction, lock the logical document and read its
+ *      authoritative source locale, path, and advertised locales.
  *   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
@@ -34,58 +36,67 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  *   4. `availableLocales` (when supplied): rewritten wholesale via
  *      `setDocumentAvailableLocales`.
  *
- * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the document-grain audit log: each field that actually
- * changes records a `document.path.changed` / `document.locales.changed` row
- * atomically with the write (docs/06-auth-and-security/02-auditability.md — Workstream 2).
+ * Content hooks do not fire because these are not content writes. Actual
+ * changes emit `afterSystemFieldsChange` after the audited write commits. A
+ * caller can pass `reconcile: true` to emit the same hook for a no-op retry
+ * after an earlier post-commit hook failure. Hook failures reject the call but
+ * never roll back the already-committed write/audit.
+ * Accountability for these mutations is the document-grain audit log: each
+ * changed field records a `document.path.changed` /
+ * `document.locales.changed` row atomically with the write.
  *
  * @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;
+        const { db, definition, 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,
-        });
-        // Both document-grain writes and their audit rows commit atomically.
-        // These fields are non-versioned, so the version stream never records
-        // them — the audit log is their only accountability home. One audit row
-        // per field that actually changed (docs/06-auth-and-security/02-auditability.md).
-        const currentPath = originalData.path;
-        const currentLocales = originalData.availableLocales ?? [];
-        const availableLocalesWritten = params.availableLocales !== undefined;
+        const requested = {
+            path: explicitPath !== null,
+            availableLocales: params.availableLocales !== undefined,
+        };
+        const requestedLocales = params.availableLocales === undefined ? undefined : [...new Set(params.availableLocales)];
         const audit = requireAuditCapability(db);
+        const getDocumentSystemFieldsForUpdate = db.queries.documents.getDocumentSystemFieldsForUpdate;
+        if (typeof getDocumentSystemFieldsForUpdate !== 'function') {
+            throw ERR_AUDIT_UNSUPPORTED({
+                message: 'audited system-field writes require a transaction-scoped lock/read capability',
+            });
+        }
+        const lockSystemFields = getDocumentSystemFieldsForUpdate.bind(db.queries.documents);
         const actor = auditActor(ctx);
-        await audit.withTransaction(async () => {
-            if (pathForCommand !== undefined) {
+        // The logical document row is the mutex for both document-grain fields.
+        // Reading after that lock prevents concurrent writers from auditing a
+        // stale before value or omitting an intermediate old path from the event.
+        const outcome = await audit.withTransaction(async () => {
+            const snapshot = await lockSystemFields({
+                collection_id: collectionId,
+                document_id: params.documentId,
+            });
+            if (snapshot == null) {
+                throw ERR_NOT_FOUND({
+                    message: 'document not found',
+                    details: { documentId: params.documentId },
+                }).log(ctx.logger);
+            }
+            const sourceLocale = snapshot.source_locale ?? defaultLocale;
+            const currentPath = snapshot.path ?? undefined;
+            const currentLocales = snapshot.availableLocales;
+            const nextLocales = requestedLocales ?? currentLocales;
+            const pathForCommand = resolvePathForUpdate({
+                explicitPath,
+                currentPath,
+                requestLocale,
+                sourceLocale,
+                documentId: params.documentId,
+                logger: ctx.logger,
+            });
+            const pathChanged = pathForCommand !== undefined && pathForCommand !== currentPath;
+            const availableLocalesChanged = requestedLocales !== undefined && !sameLocaleSet(currentLocales, nextLocales);
+            if (pathChanged) {
                 await db.commands.documents
                     .updateDocumentPath({
                     documentId: params.documentId,
@@ -93,45 +104,72 @@ export async function updateDocumentSystemFields(ctx, params) {
                     locale: sourceLocale,
                     path: pathForCommand,
                 })
-                    .catch((err) => rethrowPathConflict(err, pathForCommand, defaultLocale));
-                if (pathForCommand !== currentPath) {
-                    await audit.append({
-                        documentId: params.documentId,
-                        collectionId,
-                        actorId: actor.actorId,
-                        actorRealm: actor.actorRealm,
-                        action: AUDIT_ACTIONS.pathChanged,
-                        field: 'path',
-                        before: currentPath ?? null,
-                        after: pathForCommand,
-                    });
-                }
+                    .catch((err) => rethrowPathConflict(err, pathForCommand, sourceLocale));
+                await audit.append({
+                    documentId: params.documentId,
+                    collectionId,
+                    actorId: actor.actorId,
+                    actorRealm: actor.actorRealm,
+                    action: AUDIT_ACTIONS.pathChanged,
+                    field: 'path',
+                    before: currentPath ?? null,
+                    after: pathForCommand,
+                });
             }
-            // Advertised locales: rewrite the document-grain set wholesale.
-            if (params.availableLocales !== undefined) {
+            if (availableLocalesChanged) {
                 await db.commands.documents.setDocumentAvailableLocales({
                     documentId: params.documentId,
                     collectionId,
-                    availableLocales: params.availableLocales,
+                    availableLocales: nextLocales,
+                });
+                await audit.append({
+                    documentId: params.documentId,
+                    collectionId,
+                    actorId: actor.actorId,
+                    actorRealm: actor.actorRealm,
+                    action: AUDIT_ACTIONS.localesChanged,
+                    field: 'availableLocales',
+                    before: currentLocales,
+                    after: nextLocales,
                 });
-                if (!sameLocaleSet(currentLocales, params.availableLocales)) {
-                    await audit.append({
-                        documentId: params.documentId,
-                        collectionId,
-                        actorId: actor.actorId,
-                        actorRealm: actor.actorRealm,
-                        action: AUDIT_ACTIONS.localesChanged,
-                        field: 'availableLocales',
-                        before: currentLocales,
-                        after: params.availableLocales,
-                    });
-                }
             }
+            return {
+                pathForCommand,
+                pathChanged,
+                availableLocalesChanged,
+                previousPath: currentPath,
+                currentPath: pathChanged ? pathForCommand : currentPath,
+                previousAvailableLocales: [...currentLocales],
+                currentAvailableLocales: [...nextLocales],
+            };
         });
+        const changed = outcome.pathChanged || outcome.availableLocalesChanged;
+        const reconciliation = !changed && params.reconcile === true;
+        if (changed || reconciliation) {
+            const hooks = await resolveHooks(definition);
+            await invokeHook(hooks?.afterSystemFieldsChange, {
+                documentId: params.documentId,
+                collectionPath,
+                requested,
+                changed: {
+                    path: outcome.pathChanged,
+                    availableLocales: outcome.availableLocalesChanged,
+                },
+                reconciliation,
+                previousPath: outcome.previousPath,
+                currentPath: outcome.currentPath,
+                previousAvailableLocales: outcome.previousAvailableLocales,
+                currentAvailableLocales: outcome.currentAvailableLocales,
+            });
+        }
         return {
             documentId: params.documentId,
-            path: pathForCommand,
-            availableLocalesWritten,
+            path: outcome.pathChanged ? outcome.pathForCommand : undefined,
+            changed,
+            reconciliation,
+            pathChanged: outcome.pathChanged,
+            availableLocalesChanged: outcome.availableLocalesChanged,
+            availableLocalesWritten: outcome.availableLocalesChanged,
         };
     });
 }