@byline/core 4.19.0 → 5.1.0

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

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 /** Atomic, audited lifecycle orchestration for document-tree mutations. */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
@@ -60,7 +61,7 @@ async function runCommittedTreeHook(event, callback) {
         throw ERR_TREE_HOOK_COMMITTED({
             message: `${TREE_HOOK_COMMITTED_MARKER} tree mutation committed but afterTreeChange failed: ${message}`,
             cause,
-            details: event,
+            details: { ...event },
         });
     }
 }
@@ -89,23 +90,24 @@ async function appendPlacementAudit(ctx, capability, params, mutation) {
         },
     });
 }
-/** Locked storage inspection/mutation and audit append in one transaction. */
+/** Locked storage inspection/mutation, derived revisions and audit in one transaction. */
 async function auditedPlace(ctx, params) {
     const capability = requireTreeAuditCapability(ctx.db);
-    let mutation;
-    await capability.withTransaction(async () => {
-        mutation = await capability.place({
-            collectionId: ctx.collectionId,
-            documentId: params.documentId,
-            parentDocumentId: params.parentDocumentId,
-            beforeDocumentId: params.beforeDocumentId ?? null,
-            afterDocumentId: params.afterDocumentId ?? null,
-            ifUnplaced: params.ifUnplaced,
-        });
+    const committed = await commitGuardedDocumentMutation(ctx, params, async () => {
+        const mutation = await capability.place({ collectionId: ctx.collectionId, ...params });
         if (mutation.changed)
             await appendPlacementAudit(ctx, capability, params, mutation);
-    });
-    return mutation;
+        return { value: mutation, changed: mutation.changed };
+    }, { collectionLock: 'exclusive' });
+    return {
+        mutation: committed.value,
+        receipt: {
+            documentId: params.documentId,
+            revision: committed.revision,
+            affectedDocuments: committed.affectedDocuments,
+            scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
+        },
+    };
 }
 /** Place, re-parent, or reorder a node; explicit no-op retries may reconcile hooks. */
 export async function placeTreeNode(ctx, params) {
@@ -113,13 +115,14 @@ export async function placeTreeNode(ctx, params) {
         assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
         const hooks = await resolveHooks(ctx.definition);
         const wantsEvent = hooks?.afterTreeChange != null;
-        const mutation = await auditedPlace(ctx, params);
+        await readDocumentForMutation(ctx, params);
+        const { mutation, receipt } = await auditedPlace(ctx, params);
         const orderKey = mutation.after.orderKey;
         if (orderKey == null)
             throw new Error('placed tree mutation did not return an order key');
         if (!mutation.changed) {
             if (wantsEvent && params.reconcile === true) {
-                await runCommittedTreeHook({ change: 'place', documentId: params.documentId }, async () => {
+                await runCommittedTreeHook({ ...receipt, change: 'place', documentId: params.documentId }, async () => {
                     await fireTreeChange(ctx, ctx.definition, {
                         change: 'place',
                         documentId: params.documentId,
@@ -127,10 +130,10 @@ export async function placeTreeNode(ctx, params) {
                     });
                 });
             }
-            return { orderKey };
+            return { orderKey, ...receipt };
         }
         if (wantsEvent) {
-            await runCommittedTreeHook({ change: 'place', documentId: params.documentId }, async () => {
+            await runCommittedTreeHook({ ...receipt, change: 'place', documentId: params.documentId }, async () => {
                 const [subtree, newSiblings] = await Promise.all([
                     subtreeIds(ctx, params.documentId),
                     childIds(ctx, params.parentDocumentId),
@@ -148,41 +151,46 @@ export async function placeTreeNode(ctx, params) {
                 });
             });
         }
-        return { orderKey };
+        return { orderKey, ...receipt };
     });
 }
-/** Best-effort create/self-heal primitive that never moves an already-placed node. */
+/** Internal placement, only inside the initiating create/save transaction. */
 export async function appendTreeRoot(ctx, documentId) {
-    await auditedPlace(ctx, { documentId, parentDocumentId: null, ifUnplaced: true });
+    if (!ctx.db.revisions.isInTransaction())
+        throw new Error('Automatic tree placement requires the initiating transaction');
+    const capability = requireTreeAuditCapability(ctx.db);
+    const mutation = await capability.place({
+        collectionId: ctx.collectionId,
+        documentId,
+        parentDocumentId: null,
+        ifUnplaced: true,
+    });
+    if (mutation.changed)
+        await appendPlacementAudit(ctx, capability, { documentId, parentDocumentId: null }, mutation);
 }
-/** Best-effort post-version repair; locked `ifUnplaced` closes the check/write race. */
+/** Placement failure aborts the initiating save, including its version and audit. */
 export async function selfHealTreePlacement(ctx, documentId) {
-    if (ctx.definition.tree !== true)
-        return;
-    try {
+    if (ctx.definition.tree === true)
         await appendTreeRoot(ctx, documentId);
-    }
-    catch (err) {
-        ctx.logger.error({ err, documentId }, 'failed to self-heal tree placement on update');
-    }
 }
 /** Remove a node to the unplaced state; an already-unplaced node is a true no-op. */
 export async function removeFromTree(ctx, params) {
     return withLogContext({ domain: 'services', module: 'tree', function: 'removeFromTree' }, async () => {
         assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+        await readDocumentForMutation(ctx, params);
         const hooks = await resolveHooks(ctx.definition);
         const wantsEvent = hooks?.afterTreeChange != null;
         const capability = requireTreeAuditCapability(ctx.db);
         const actor = auditActor(ctx);
         let mutation;
-        await capability.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, params, async () => {
             mutation = await capability.remove({
                 collectionId: ctx.collectionId,
                 documentId: params.documentId,
                 includeSubtree: wantsEvent,
             });
             if (!mutation.changed)
-                return;
+                return { value: mutation, changed: false };
             await capability.append({
                 documentId: params.documentId,
                 collectionId: ctx.collectionId,
@@ -193,13 +201,20 @@ export async function removeFromTree(ctx, params) {
                 before: { ...mutation.before, mode: 'remove' },
                 after: { ...mutation.after, mode: 'remove' },
             });
-        });
+            return { value: mutation, changed: true };
+        }, { collectionLock: 'exclusive' });
+        const receipt = {
+            documentId: params.documentId,
+            revision: committed.revision,
+            affectedDocuments: committed.affectedDocuments,
+            scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
+        };
         if (!mutation || !wantsEvent)
-            return;
+            return receipt;
         const committedMutation = mutation;
         if (!committedMutation.changed) {
             if (params.reconcile === true) {
-                await runCommittedTreeHook({ change: 'remove', documentId: params.documentId }, async () => {
+                await runCommittedTreeHook({ ...receipt, change: 'remove', documentId: params.documentId }, async () => {
                     await fireTreeChange(ctx, ctx.definition, {
                         change: 'remove',
                         documentId: params.documentId,
@@ -210,9 +225,9 @@ export async function removeFromTree(ctx, params) {
                     });
                 });
             }
-            return;
+            return receipt;
         }
-        await runCommittedTreeHook({ change: 'remove', documentId: params.documentId }, async () => {
+        await runCommittedTreeHook({ ...receipt, change: 'remove', documentId: params.documentId }, async () => {
             await fireTreeChange(ctx, ctx.definition, {
                 change: 'remove',
                 documentId: params.documentId,
@@ -225,6 +240,7 @@ export async function removeFromTree(ctx, params) {
                 ],
             });
         });
+        return receipt;
     });
 }
 /**
@@ -295,11 +311,21 @@ export async function firePromoteTreeChange(ctx, documentId, result) {
 /** Standalone audited reconciliation used by internal tooling and tests. */
 export async function promoteChildrenAndRemove(ctx, params) {
     return withLogContext({ domain: 'services', module: 'tree', function: 'promoteChildrenAndRemove' }, async () => {
+        assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+        await readDocumentForMutation(ctx, params);
         const capability = requireTreeAuditCapability(ctx.db);
         let result;
-        await capability.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, params, async () => {
             result = await reconcileTreeOnDeleteInTransaction(ctx, params.documentId, capability);
-        });
-        await firePromoteTreeChange(ctx, params.documentId, result);
+            return { value: result, changed: result.removed.changed || result.promoted.length > 0 };
+        }, { collectionLock: 'exclusive' });
+        const receipt = {
+            documentId: params.documentId,
+            revision: committed.revision,
+            affectedDocuments: committed.affectedDocuments,
+            scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
+        };
+        await runCommittedTreeHook({ ...receipt, change: 'promote-on-delete' }, () => firePromoteTreeChange(ctx, params.documentId, committed.value));
+        return receipt;
     });
 }

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

@@ -1,8 +1 @@
-/**
- * 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
- */
 export {};

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

@@ -1,3 +1,4 @@
+import { testAdapter } from '../../storage/db-adapter.test-helper.js';
 /**
  * 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
@@ -9,6 +10,8 @@ import { createSuperAdminContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { isSingleton } from '../../@types/index.js';
 import { TREE_HOOK_COMMITTED_MARKER } from '../../lib/errors.js';
+import { runReadSnapshot } from '../../storage/read-snapshot.js';
+import { unusedRevisionStore } from '../../storage/revision-store.test-helper.js';
 import { validateTreeAuditCapability } from './audit.js';
 import { createDocument } from './create.js';
 import { deleteDocument } from './delete.js';
@@ -20,6 +23,8 @@ function createHarness(options = {}) {
     let key = 0;
     let writes = 0;
     let deleted = false;
+    let revisions = new Map();
+    let transactionDepth = 0;
     const calls = [];
     const snapshot = (documentId) => {
         const placement = placements.get(documentId);
@@ -172,13 +177,22 @@ function createHarness(options = {}) {
                 .filter(([, placement]) => placement.parentDocumentId == null)
                 .flatMap(([id]) => subtree(id))
             : subtree(rootDocumentId);
-        return ids.map((document_id) => ({ document_id }));
+        return ids.map((document_id) => ({
+            document_id,
+            parent_document_id: placements.get(document_id)?.parentDocumentId ?? null,
+            depth: 0,
+            order_key: placements.get(document_id)?.orderKey ?? 'a0',
+        }));
     });
-    const withTransaction = vi.fn(async (fn) => {
+    const withTransaction = vi.fn();
+    const transact = async (fn) => {
+        withTransaction();
+        transactionDepth++;
         calls.push('tx:start');
         const placementSnapshot = new Map(placements);
         const auditSnapshot = [...auditRows];
         const deletedSnapshot = deleted;
+        const revisionSnapshot = new Map(revisions);
         try {
             const result = await fn();
             calls.push('tx:commit');
@@ -188,10 +202,14 @@ function createHarness(options = {}) {
             placements = placementSnapshot;
             auditRows = auditSnapshot;
             deleted = deletedSnapshot;
+            revisions = revisionSnapshot;
             calls.push('tx:rollback');
             throw error;
         }
-    });
+        finally {
+            transactionDepth--;
+        }
+    };
     const definition = {
         path: 'pages',
         labels: { singular: 'Page', plural: 'Pages' },
@@ -211,11 +229,15 @@ function createHarness(options = {}) {
         trace: vi.fn(),
         silent: vi.fn(),
     };
-    const db = {
+    const db = testAdapter({
         commands: {
+            collections: { lockCollectionRegistration: vi.fn(async () => { }) },
+            singletons: { lockSlot: vi.fn(async () => { }) },
             documents: {
                 publishSchedules: {
+                    lockDocuments: vi.fn(async () => { }),
                     cancel: vi.fn(async () => null),
+                    suspendForContentEdit: vi.fn(async () => ({ status: 'schedule_not_found' })),
                 },
                 placeTreeNode: place,
                 removeFromTree: remove,
@@ -228,15 +250,60 @@ function createHarness(options = {}) {
             audit: { append },
         },
         queries: {
+            collections: {},
+            audit: {},
+            singletons: {},
             documents: {
                 getTreeParent,
                 getTreeChildren,
                 getTreeSubtree,
-                getDocumentById: vi.fn(async () => ({ path: '/node', fields: {} })),
+                getDocumentById: vi.fn(async () => ({
+                    document_version_id: 'version-1',
+                    path: '/node',
+                    fields: {},
+                })),
+                getDocumentRevision: async ({ document_id }) => revisions.get(document_id) ?? 1,
+                publishSchedules: {},
             },
         },
-        withTransaction,
-    };
+        withReadSnapshot: (fn) => runReadSnapshot(db.queries, fn),
+        revisions: {
+            ...unusedRevisionStore,
+            isInTransaction: () => transactionDepth > 0,
+            readStructure: async ({ documentIds, parentDocumentId }) => {
+                const ids = new Set(documentIds ?? [...placements.keys()]);
+                if (parentDocumentId)
+                    for (const [id, placement] of placements)
+                        if (placement.parentDocumentId === parentDocumentId)
+                            ids.add(id);
+                return [...ids].map((documentId) => ({
+                    documentId,
+                    revision: revisions.get(documentId) ?? 1,
+                    orderKey: null,
+                    placed: placements.has(documentId),
+                    parentDocumentId: placements.get(documentId)?.parentDocumentId ?? null,
+                    treeOrderKey: placements.get(documentId)?.orderKey ?? null,
+                    live: true,
+                }));
+            },
+            lock: async (targets) => targets.map((target) => ({
+                documentId: target.documentId,
+                collectionId: target.collectionId,
+                revision: revisions.get(target.documentId) ?? 1,
+                currentVersionId: 'version-1',
+                status: 'draft',
+                sourceLocale: 'en',
+                path: '/node',
+                availableLocales: ['en'],
+            })),
+            advance: async (locked) => {
+                const revision = locked.revision + 1;
+                revisions.set(locked.documentId, revision);
+                return { documentId: locked.documentId, revision };
+            },
+        },
+        withTransaction: transact,
+    });
     const ctx = {
         db,
         definition,
@@ -266,7 +333,7 @@ function createHarness(options = {}) {
 describe('document-tree lifecycle audit contract', () => {
     it('validates the full tree audit capability only for tree-enabled collections', () => {
         const harness = createHarness();
-        const unsupported = {
+        const unsupported = testAdapter({
             ...harness.ctx.db,
             commands: {
                 ...harness.ctx.db.commands,
@@ -275,7 +342,7 @@ describe('document-tree lifecycle audit contract', () => {
                     promoteChildrenAndRemoveFromTree: undefined,
                 },
             },
-        };
+        });
         const definition = harness.ctx.definition;
         if (isSingleton(definition)) {
             throw new Error('tree lifecycle harness must use a multi-document collection');
@@ -287,9 +354,18 @@ describe('document-tree lifecycle audit contract', () => {
         const harness = createHarness({
             initial: { left: { parentDocumentId: 'parent', orderKey: 'left-key' } },
         });
-        await placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: null });
-        await placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: 'parent' });
         await placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: null,
+        });
+        await placeTreeNode(harness.ctx, {
+            expectedRevision: 2,
+            documentId: 'node',
+            parentDocumentId: 'parent',
+        });
+        await placeTreeNode(harness.ctx, {
+            expectedRevision: 3,
             documentId: 'node',
             parentDocumentId: 'parent',
             afterDocumentId: 'left',
@@ -321,8 +397,8 @@ describe('document-tree lifecycle audit contract', () => {
         const harness = createHarness({
             initial: { node: { parentDocumentId: 'parent', orderKey: 'old-key' } },
         });
-        await removeFromTree(harness.ctx, { documentId: 'node' });
-        await removeFromTree(harness.ctx, { documentId: 'node' });
+        await removeFromTree(harness.ctx, { expectedRevision: 1, documentId: 'node' });
+        await removeFromTree(harness.ctx, { expectedRevision: 2, documentId: 'node' });
         expect(harness.remove).toHaveBeenCalledTimes(2);
         expect(harness.writes()).toBe(1);
         expect(harness.auditRows()).toHaveLength(1);
@@ -348,7 +424,17 @@ describe('document-tree lifecycle audit contract', () => {
             },
             afterTreeChange: hook,
         });
-        await expect(placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: null })).resolves.toEqual({ orderKey: 'b-key' });
+        await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: null,
+        })).resolves.toEqual({
+            orderKey: 'b-key',
+            documentId: 'node',
+            revision: 1,
+            affectedDocuments: [],
+            scheduledPublicationsNeedReconfirmation: false,
+        });
         expect(harness.writes()).toBe(0);
         expect(harness.auditRows()).toEqual([]);
         expect(hook).not.toHaveBeenCalled();
@@ -360,12 +446,23 @@ describe('document-tree lifecycle audit contract', () => {
             .mockRejectedValueOnce(new Error('hook failed'))
             .mockResolvedValue(undefined);
         const harness = createHarness({ afterTreeChange: hook });
-        await expect(placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: null })).rejects.toThrow('hook failed');
         await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: null,
+        })).rejects.toThrow('hook failed');
+        await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 2,
             documentId: 'node',
             parentDocumentId: null,
             reconcile: true,
-        })).resolves.toEqual({ orderKey: 'key-1' });
+        })).resolves.toEqual({
+            orderKey: 'key-1',
+            documentId: 'node',
+            revision: 2,
+            affectedDocuments: [],
+            scheduledPublicationsNeedReconfirmation: false,
+        });
         expect(harness.writes()).toBe(1);
         expect(harness.auditRows()).toHaveLength(1);
         expect(hook).toHaveBeenCalledTimes(2);
@@ -394,9 +491,9 @@ describe('document-tree lifecycle audit contract', () => {
             },
             afterTreeChange: hook,
         });
-        await expect(removeFromTree(harness.ctx, { documentId: 'node' })).rejects.toThrow('hook failed');
+        await expect(removeFromTree(harness.ctx, { expectedRevision: 1, documentId: 'node' })).rejects.toThrow('hook failed');
         expect(events[0]?.affectedDocumentIds).toEqual(expect.arrayContaining(['node', 'child', 'grandchild', 'parent']));
-        await removeFromTree(harness.ctx, { documentId: 'node', reconcile: true });
+        await removeFromTree(harness.ctx, { expectedRevision: 2, documentId: 'node', reconcile: true });
         expect(harness.writes()).toBe(1);
         expect(harness.auditRows()).toHaveLength(1);
         expect(events).toHaveLength(2);
@@ -410,7 +507,7 @@ describe('document-tree lifecycle audit contract', () => {
                 childB: { parentDocumentId: 'deleted', orderKey: 'b-key' },
             },
         });
-        await promoteChildrenAndRemove(harness.ctx, { documentId: 'deleted' });
+        await promoteChildrenAndRemove(harness.ctx, { expectedRevision: 1, documentId: 'deleted' });
         expect(harness.placement('deleted')).toBeUndefined();
         expect(harness.placement('childA')?.parentDocumentId).toBeNull();
         expect(harness.placement('childB')?.parentDocumentId).toBeNull();
@@ -455,8 +552,10 @@ describe('document-tree lifecycle audit contract', () => {
                 child: { parentDocumentId: 'deleted', orderKey: 'child-key' },
             },
         });
-        await expect(deleteDocument(harness.ctx, { documentId: 'deleted' })).resolves.toEqual({
+        await expect(deleteDocument(harness.ctx, { expectedRevision: 1, documentId: 'deleted' })).resolves.toMatchObject({
             deletedVersionCount: 1,
+            documentId: 'deleted',
+            revision: 2,
             outcome: 'committed',
             sideEffectFailures: [],
         });
@@ -478,7 +577,7 @@ describe('document-tree lifecycle audit contract', () => {
             },
             failAuditAt: 3,
         });
-        await expect(deleteDocument(harness.ctx, { documentId: 'deleted' })).rejects.toThrow('audit failed');
+        await expect(deleteDocument(harness.ctx, { expectedRevision: 1, documentId: 'deleted' })).rejects.toThrow('audit failed');
         expect(harness.deleted()).toBe(false);
         expect(harness.placement('deleted')).toEqual({
             parentDocumentId: null,
@@ -502,8 +601,10 @@ describe('document-tree lifecycle audit contract', () => {
             },
             afterDelete,
         });
-        await expect(deleteDocument(harness.ctx, { documentId: 'deleted' })).resolves.toEqual({
+        await expect(deleteDocument(harness.ctx, { expectedRevision: 1, documentId: 'deleted' })).resolves.toMatchObject({
             deletedVersionCount: 1,
+            documentId: 'deleted',
+            revision: 2,
             outcome: 'committed-with-side-effect-failures',
             sideEffectFailures: [{ phase: 'afterTreeChange', code: 'ERR_UNHANDLED' }],
         });
@@ -529,9 +630,11 @@ describe('document-tree lifecycle audit contract', () => {
             afterTreeChange,
             afterDelete,
         });
-        const result = await deleteDocument(harness.ctx, { documentId: 'deleted' });
-        expect(result).toEqual({
+        const result = await deleteDocument(harness.ctx, { expectedRevision: 1, documentId: 'deleted' });
+        expect(result).toMatchObject({
             deletedVersionCount: 1,
+            documentId: 'deleted',
+            revision: 2,
             outcome: 'committed-with-side-effect-failures',
             sideEffectFailures: [
                 { phase: 'afterTreeChange', code: 'ERR_UNHANDLED' },
@@ -564,8 +667,10 @@ describe('document-tree lifecycle audit contract', () => {
             throw new Error('logger failed');
         });
         harness.ctx.logger.error = loggerError;
-        await expect(deleteDocument(harness.ctx, { documentId: 'deleted' })).resolves.toEqual({
+        await expect(deleteDocument(harness.ctx, { expectedRevision: 1, documentId: 'deleted' })).resolves.toMatchObject({
             deletedVersionCount: 1,
+            documentId: 'deleted',
+            revision: 2,
             outcome: 'committed-with-side-effect-failures',
             sideEffectFailures: [{ phase: 'afterDelete', code: 'ERR_UNHANDLED' }],
         });
@@ -579,7 +684,11 @@ describe('document-tree lifecycle audit contract', () => {
             failAudit: true,
             afterTreeChange: hook,
         });
-        await expect(placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: 'new-parent' })).rejects.toThrow('audit failed');
+        await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: 'new-parent',
+        })).rejects.toThrow('audit failed');
         expect(harness.placement('node')).toEqual({ parentDocumentId: null, orderKey: 'old-key' });
         expect(harness.auditRows()).toEqual([]);
         expect(hook).not.toHaveBeenCalled();
@@ -590,7 +699,7 @@ describe('document-tree lifecycle audit contract', () => {
             initial: { node: { parentDocumentId: 'parent', orderKey: 'old-key' } },
             failAudit: true,
         });
-        await expect(removeFromTree(removeHarness.ctx, { documentId: 'node' })).rejects.toThrow('audit failed');
+        await expect(removeFromTree(removeHarness.ctx, { expectedRevision: 1, documentId: 'node' })).rejects.toThrow('audit failed');
         expect(removeHarness.placement('node')).toEqual({
             parentDocumentId: 'parent',
             orderKey: 'old-key',
@@ -602,7 +711,7 @@ describe('document-tree lifecycle audit contract', () => {
             },
             failAudit: true,
         });
-        await expect(promoteChildrenAndRemove(promoteHarness.ctx, { documentId: 'deleted' })).rejects.toThrow('audit failed');
+        await expect(promoteChildrenAndRemove(promoteHarness.ctx, { expectedRevision: 1, documentId: 'deleted' })).rejects.toThrow('audit failed');
         expect(promoteHarness.placement('deleted')).toEqual({
             parentDocumentId: null,
             orderKey: 'deleted-key',
@@ -614,7 +723,11 @@ describe('document-tree lifecycle audit contract', () => {
     });
     it('does not append audit on a failed storage mutation', async () => {
         const harness = createHarness({ failPlace: true });
-        await expect(placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: null })).rejects.toThrow('tree write failed');
+        await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: null,
+        })).rejects.toThrow('tree write failed');
         expect(harness.append).not.toHaveBeenCalled();
         expect(harness.auditRows()).toEqual([]);
     });
@@ -623,7 +736,11 @@ describe('document-tree lifecycle audit contract', () => {
             throw new Error('hook failed');
         });
         const harness = createHarness({ afterTreeChange: hook });
-        await expect(placeTreeNode(harness.ctx, { documentId: 'node', parentDocumentId: null })).rejects.toMatchObject({
+        await expect(placeTreeNode(harness.ctx, {
+            expectedRevision: 1,
+            documentId: 'node',
+            parentDocumentId: null,
+        })).rejects.toMatchObject({
             name: 'BylineError',
             code: 'ERR_TREE_HOOK_COMMITTED',
             message: expect.stringMatching(new RegExp(`^${TREE_HOOK_COMMITTED_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*hook failed`)),
@@ -638,7 +755,7 @@ describe('document-tree lifecycle audit contract', () => {
             document: { id: 'version-1', document_id: 'created-node' },
             fieldCount: 1,
         }));
-        harness.ctx.db = {
+        harness.ctx.db = testAdapter({
             ...harness.ctx.db,
             commands: {
                 ...harness.ctx.db.commands,
@@ -649,23 +766,23 @@ describe('document-tree lifecycle audit contract', () => {
                 audit: undefined,
             },
             withTransaction: undefined,
-        };
+        });
         await expect(createDocument(harness.ctx, { data: { title: 'Created' }, locale: 'en' })).rejects.toMatchObject({ code: 'ERR_AUDIT_UNSUPPORTED' });
         expect(createDocumentVersion).not.toHaveBeenCalled();
         expect(harness.place).not.toHaveBeenCalled();
         expect(harness.ctx.logger.error).not.toHaveBeenCalled();
     });
-    it('keeps create-time placement best-effort and unplaced when audit append fails', async () => {
+    it('rolls back initiating creation and placement when its audit append fails', async () => {
         const harness = createHarness({ failAudit: true });
         const createDocumentVersion = vi.fn(async () => ({
             document: { id: 'version-1', document_id: 'created-node' },
             fieldCount: 1,
         }));
         harness.ctx.db.commands.documents.createDocumentVersion = createDocumentVersion;
-        await expect(createDocument(harness.ctx, { data: { title: 'Created' }, locale: 'en' })).resolves.toEqual({ documentId: 'created-node', documentVersionId: 'version-1' });
+        await expect(createDocument(harness.ctx, { data: { title: 'Created' }, locale: 'en' })).rejects.toThrow('audit failed');
         expect(harness.place).toHaveBeenCalledOnce();
         expect(harness.placement('created-node')).toBeUndefined();
         expect(harness.auditRows()).toEqual([]);
-        expect(harness.ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'created-node' }), 'failed to auto-place new document in tree');
+        expect(harness.calls).toContain('tx:rollback');
     });
 });