@byline/core 4.18.0 → 5.0.0

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

@@ -7,185 +7,142 @@
  */
 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 { ERR_INVALID_TRANSITION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getWorkflow, validateStatusTransition } from '../../workflow/workflow.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
+import { runCommittedDocumentHook } from './committed-hook.js';
 import { invokeHook } from './internals.js';
 import { appendPublishScheduleCancellationAudit, cancelPublishScheduleInTransaction, } from './publish-schedule-consistency.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 import { commitDocumentStatusTransition } from './status-transition.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 })`
- */
+function validateWorkflow(ctx) {
+    if (getWorkflow(ctx.definition).statuses.length <= 1)
+        throw ERR_INVALID_TRANSITION({
+            message: `collection '${ctx.collectionPath}' has a single-status workflow; status transitions are not supported`,
+            details: { collectionPath: ctx.collectionPath },
+        });
+}
+function validateTransition(ctx, previousStatus, nextStatus) {
+    validateWorkflow(ctx);
+    const result = validateStatusTransition(getWorkflow(ctx.definition), previousStatus, nextStatus);
+    if (!result.valid)
+        throw ERR_INVALID_TRANSITION({
+            message: result.reason ?? 'Invalid status transition',
+            details: { currentStatus: previousStatus, nextStatus },
+        });
+}
 export async function changeDocumentStatus(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'changeDocumentStatus' }, async () => {
+        params = { ...params };
         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, definition, 'changeStatus');
-        if (params.nextStatus === 'published') {
+        if (params.nextStatus === 'published')
             assertActorCanPerform(ctx.requestContext, definition, '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 latest = await readDocumentForMutation(ctx, { ...params, lenient: true });
+        const previousStatus = 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,
-        })) ?? '';
+        validateTransition(ctx, previousStatus, params.nextStatus);
         const hookCtx = {
             documentId: params.documentId,
             documentVersionId,
             collectionPath,
-            path,
-            previousStatus: currentStatus,
+            path: latest.path ?? '',
+            previousStatus,
             nextStatus: params.nextStatus,
         };
-        // 3. beforeStatusChange hook.
+        const hooks = await resolveHooks(definition);
         await invokeHook(hooks?.beforeStatusChange, hookCtx);
-        // 4–5. Mutate status in-place + auto-archive, atomically with the audit
-        //      record. Status mutates the version row rather than minting a new
-        //      version, so the version stream never captures *who* changed it —
-        //      the audit log is its only accountability home (docs/07-auth-and-security/02-auditability.md).
-        const transitionAudit = requireAuditCapability(db);
-        let cancelledSchedule = null;
-        await commitDocumentStatusTransition({
-            db,
-            documentId: params.documentId,
-            documentVersionId,
-            collectionId,
-            previousStatus: currentStatus,
-            nextStatus: params.nextStatus,
-            actor: auditActor(ctx),
-            contributions: {
-                beforeStatusWrite: async () => {
-                    cancelledSchedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
-                },
-                afterAuditAppend: () => appendPublishScheduleCancellationAudit({
+        const audit = requireAuditCapability(db);
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId: documentVersionId }, async (locked) => {
+            const status = locked.status ?? 'draft';
+            validateTransition(ctx, status, params.nextStatus);
+            const schedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
+            if (status !== params.nextStatus)
+                await commitDocumentStatusTransition({
+                    db,
+                    documentId: params.documentId,
+                    documentVersionId: locked.currentVersionId,
+                    collectionId,
+                    previousStatus: status,
+                    nextStatus: params.nextStatus,
+                    actor: auditActor(ctx),
+                    contributions: {
+                        afterAuditAppend: () => appendPublishScheduleCancellationAudit({
+                            ctx,
+                            audit,
+                            schedule,
+                            reason: 'status_changed',
+                        }),
+                    },
+                });
+            else
+                await appendPublishScheduleCancellationAudit({
                     ctx,
-                    audit: transitionAudit,
-                    schedule: cancelledSchedule,
+                    audit,
+                    schedule,
                     reason: 'status_changed',
-                }),
-            },
+                });
+            return {
+                value: { previousStatus: status, newStatus: params.nextStatus },
+                changed: status !== params.nextStatus || schedule !== null,
+            };
         });
-        // 6. afterStatusChange hook.
-        await invokeHook(hooks?.afterStatusChange, hookCtx);
-        return { previousStatus: currentStatus, newStatus: params.nextStatus };
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterStatusChange',
+            documentId: params.documentId,
+            documentVersionId,
+            revision: committed.revision,
+        }, () => invokeHook(hooks?.afterStatusChange, hookCtx));
+        return { ...committed.value, documentId: params.documentId, revision: committed.revision };
     });
 }
-/**
- * Unpublish a document by archiving its published version(s).
- *
- * Flow:
- *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. Archive published versions and append the status audit atomically
- *   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.
+        params = { ...params };
+        const { db, definition, collectionId, collectionPath } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, '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 latest = await readDocumentForMutation(ctx, { ...params, lenient: true });
+        validateWorkflow(ctx);
+        const documentVersionId = latest.document_version_id;
+        const hookCtx = { documentId: params.documentId, collectionPath, path: latest.path ?? '' };
         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,
-        });
+        await invokeHook(hooks?.beforeUnpublish, hookCtx);
         const audit = requireAuditCapability(db);
         const actor = auditActor(ctx);
-        const archivedCount = await audit.withTransaction(async () => {
-            const cancelledSchedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
-            const count = await db.commands.documents.archivePublishedVersions({
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId: documentVersionId }, async () => {
+            const schedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
+            const archivedCount = await db.commands.documents.archivePublishedVersions({
                 document_id: params.documentId,
             });
-            if (count > 0) {
+            if (archivedCount > 0)
                 await audit.append({
                     documentId: params.documentId,
                     collectionId,
-                    actorId: actor.actorId,
-                    actorRealm: actor.actorRealm,
+                    ...actor,
                     action: AUDIT_ACTIONS.statusChanged,
                     field: 'status',
                     before: 'published',
                     after: 'archived',
                 });
-            }
             await appendPublishScheduleCancellationAudit({
                 ctx,
                 audit,
-                schedule: cancelledSchedule,
+                schedule,
                 reason: 'unpublished',
             });
-            return count;
+            return { value: archivedCount, changed: archivedCount > 0 || schedule !== null };
         });
-        await invokeHook(hooks?.afterUnpublish, {
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterUnpublish',
             documentId: params.documentId,
-            collectionPath,
-            path,
-            archivedCount,
-        });
-        return { archivedCount };
+            documentVersionId,
+            revision: committed.revision,
+        }, () => invokeHook(hooks?.afterUnpublish, { ...hookCtx, archivedCount: committed.value }));
+        return {
+            archivedCount: committed.value,
+            documentId: params.documentId,
+            revision: committed.revision,
+        };
     });
 }

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

@@ -5,9 +5,11 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { LockedDocumentRevision } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
 export interface UpdateDocumentSystemFieldsResult {
     documentId: string;
+    revision: number;
     /** The path actually written, or `undefined` when no path write occurred. */
     path?: string;
     /** Whether either system field actually changed. */
@@ -58,6 +60,7 @@ export interface UpdateDocumentSystemFieldsResult {
  */
 export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     locale?: string;
     /**
      * Explicit path override from the path widget. `null` / empty / omitted
@@ -75,3 +78,21 @@ export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext
     /** Re-run `afterSystemFieldsChange` when requested values are already current. */
     reconcile?: boolean;
 }): Promise<UpdateDocumentSystemFieldsResult>;
+export type SystemFieldMutationParams = Parameters<typeof updateDocumentSystemFields>[1];
+/** Internal storage phase; caller owns the document guard and revision advancement. */
+export declare function writeSystemFieldsInTransaction(ctx: DocumentLifecycleContext, params: SystemFieldMutationParams, locked: LockedDocumentRevision): Promise<{
+    requested: {
+        path: boolean;
+        availableLocales: boolean;
+    };
+    pathForCommand: string | undefined;
+    pathChanged: boolean;
+    availableLocalesChanged: boolean;
+    previousPath: string | undefined;
+    currentPath: string | undefined;
+    previousAvailableLocales: string[];
+    currentAvailableLocales: string[];
+}>;
+export declare function finishSystemFieldMutation(ctx: DocumentLifecycleContext, params: SystemFieldMutationParams, outcome: Awaited<ReturnType<typeof writeSystemFieldsInTransaction>> & {
+    documentVersionId: string;
+}, revision: number): Promise<UpdateDocumentSystemFieldsResult>;

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

@@ -7,10 +7,11 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.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 { runCommittedDocumentHook } from './committed-hook.js';
 import { invokeHook, resolvePathForUpdate, rethrowPathConflict } from './internals.js';
+import { suspendPublishScheduleForEdit } from './publish-schedule-consistency.js';
+import { commitGuardedDocumentMutation } from './revision-guard.js';
 /**
  * Write a document's system-managed, document-grain fields — `path` and the
  * editorial `availableLocales` set — **without** minting a new version or
@@ -49,127 +50,128 @@ import { invokeHook, resolvePathForUpdate, rethrowPathConflict } from './interna
  * @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, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, definition, 'update');
-        const requestLocale = params.locale ?? defaultLocale;
-        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        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);
-        // 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,
-                    collectionId,
-                    locale: sourceLocale,
-                    path: pathForCommand,
-                })
-                    .catch((err) => rethrowPathConflict(db, err, pathForCommand, sourceLocale, 'update'));
-                await audit.append({
-                    documentId: params.documentId,
-                    collectionId,
-                    actorId: actor.actorId,
-                    actorRealm: actor.actorRealm,
-                    action: AUDIT_ACTIONS.pathChanged,
-                    field: 'path',
-                    before: currentPath ?? null,
-                    after: pathForCommand,
-                });
-            }
-            if (availableLocalesChanged) {
-                await db.commands.documents.setDocumentAvailableLocales({
-                    documentId: params.documentId,
-                    collectionId,
-                    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,
-                });
-            }
-            return {
-                pathForCommand,
-                pathChanged,
-                availableLocalesChanged,
-                previousPath: currentPath,
-                currentPath: pathChanged ? pathForCommand : currentPath,
-                previousAvailableLocales: [...currentLocales],
-                currentAvailableLocales: [...nextLocales],
-            };
+    params = { ...params, availableLocales: params.availableLocales?.slice() };
+    assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+    // Locale controls path semantics, not version ancestry: metadata-only writes
+    // do not create a version and carry only a document revision precondition.
+    const committed = await commitGuardedDocumentMutation(ctx, {
+        documentId: params.documentId,
+        expectedRevision: params.expectedRevision,
+    }, async (locked) => {
+        const value = await writeSystemFieldsInTransaction(ctx, params, locked);
+        const changed = value.pathChanged || value.availableLocalesChanged;
+        if (changed)
+            await suspendPublishScheduleForEdit(ctx, requireAuditCapability(ctx.db), params.documentId, 'document_metadata_changed');
+        return { value: { ...value, documentVersionId: locked.currentVersionId ?? '' }, changed };
+    });
+    return finishSystemFieldMutation(ctx, params, committed.value, committed.revision);
+}
+/** Internal storage phase; caller owns the document guard and revision advancement. */
+export async function writeSystemFieldsInTransaction(ctx, params, locked) {
+    const { db, collectionId, defaultLocale } = ctx;
+    const audit = requireAuditCapability(db);
+    const actor = auditActor(ctx);
+    const requestLocale = params.locale ?? defaultLocale;
+    const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
+    const requested = {
+        path: explicitPath !== null,
+        availableLocales: params.availableLocales !== undefined,
+    };
+    const requestedLocales = params.availableLocales === undefined ? undefined : [...new Set(params.availableLocales)];
+    const sourceLocale = locked.sourceLocale;
+    const currentPath = locked.path ?? undefined;
+    const currentLocales = [...locked.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,
+            collectionId,
+            locale: sourceLocale,
+            path: pathForCommand,
+        })
+            .catch((error) => rethrowPathConflict(db, error, pathForCommand, sourceLocale, 'update'));
+        await audit.append({
+            documentId: params.documentId,
+            collectionId,
+            actorId: actor.actorId,
+            actorRealm: actor.actorRealm,
+            action: AUDIT_ACTIONS.pathChanged,
+            field: 'path',
+            before: currentPath ?? null,
+            after: pathForCommand,
         });
-        const changed = outcome.pathChanged || outcome.availableLocalesChanged;
-        const reconciliation = !changed && params.reconcile === true;
-        if (changed || reconciliation) {
-            const hooks = await resolveHooks(definition);
+    }
+    if (availableLocalesChanged) {
+        await db.commands.documents.setDocumentAvailableLocales({
+            documentId: params.documentId,
+            collectionId,
+            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,
+        });
+    }
+    return {
+        requested,
+        pathForCommand,
+        pathChanged,
+        availableLocalesChanged,
+        previousPath: currentPath,
+        currentPath: pathChanged ? pathForCommand : currentPath,
+        previousAvailableLocales: currentLocales,
+        currentAvailableLocales: nextLocales,
+    };
+}
+export async function finishSystemFieldMutation(ctx, params, outcome, revision) {
+    const changed = outcome.pathChanged || outcome.availableLocalesChanged;
+    const reconciliation = !changed && params.reconcile === true;
+    if (changed || reconciliation) {
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterSystemFieldsChange',
+            documentId: params.documentId,
+            documentVersionId: outcome.documentVersionId,
+            revision,
+        }, async () => {
+            const hooks = await resolveHooks(ctx.definition);
             await invokeHook(hooks?.afterSystemFieldsChange, {
                 documentId: params.documentId,
-                collectionPath,
-                requested,
-                changed: {
-                    path: outcome.pathChanged,
-                    availableLocales: outcome.availableLocalesChanged,
-                },
+                collectionPath: ctx.collectionPath,
+                requested: outcome.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: outcome.pathChanged ? outcome.pathForCommand : undefined,
-            changed,
-            reconciliation,
-            pathChanged: outcome.pathChanged,
-            availableLocalesChanged: outcome.availableLocalesChanged,
-            availableLocalesWritten: outcome.availableLocalesChanged,
-        };
-    });
+        });
+    }
+    return {
+        documentId: params.documentId,
+        revision,
+        path: outcome.pathChanged ? outcome.pathForCommand : undefined,
+        changed,
+        reconciliation,
+        pathChanged: outcome.pathChanged,
+        availableLocalesChanged: outcome.availableLocalesChanged,
+        availableLocalesWritten: outcome.availableLocalesChanged,
+    };
 }

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

@@ -6,9 +6,10 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { type TreeAuditCapability } from './audit.js';
-import type { TreeDeleteMutationResult } from '../../@types/index.js';
+import type { StructuralMutationReceipt, TreeDeleteMutationResult } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
 interface PlaceParams {
+    expectedRevision: number;
     documentId: string;
     parentDocumentId: string | null;
     beforeDocumentId?: string | null;
@@ -20,16 +21,17 @@ interface PlaceParams {
 /** Place, re-parent, or reorder a node; explicit no-op retries may reconcile hooks. */
 export declare function placeTreeNode(ctx: DocumentLifecycleContext, params: PlaceParams): Promise<{
     orderKey: string;
-}>;
-/** Best-effort create/self-heal primitive that never moves an already-placed node. */
+} & StructuralMutationReceipt>;
+/** Internal placement, only inside the initiating create/save transaction. */
 export declare function appendTreeRoot(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
-/** Best-effort post-version repair; locked `ifUnplaced` closes the check/write race. */
+/** Placement failure aborts the initiating save, including its version and audit. */
 export declare function selfHealTreePlacement(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
 /** Remove a node to the unplaced state; an already-unplaced node is a true no-op. */
 export declare function removeFromTree(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     reconcile?: boolean;
-}): Promise<void>;
+}): Promise<StructuralMutationReceipt>;
 /**
  * Reconcile delete-time edges and append parent plus child-specific audit rows.
  * The caller owns the transaction; delete uses this beside soft-delete/audit.
@@ -40,5 +42,6 @@ export declare function firePromoteTreeChange(ctx: DocumentLifecycleContext, doc
 /** Standalone audited reconciliation used by internal tooling and tests. */
 export declare function promoteChildrenAndRemove(ctx: DocumentLifecycleContext, params: {
     documentId: string;
-}): Promise<void>;
+    expectedRevision: number;
+}): Promise<StructuralMutationReceipt>;
 export {};