@byline/core 4.18.0 → 5.0.0

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

@@ -7,7 +7,9 @@
  */
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
-import { BylineError, DbErrorCodes, ErrorCodes } from '../lib/errors.js';
+import { BylineError, DbErrorCodes, ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ErrorCodes, } from '../lib/errors.js';
+import { runReadSnapshot } from '../storage/read-snapshot.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copyToLocale, createDocument, deleteDocument, deleteLocale, duplicateDocument, listDocumentPublishSchedules, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
@@ -38,6 +40,7 @@ function publishScheduleRow(overrides = {}) {
         documentId: 'doc-1',
         collectionId: 'col-1',
         targetVersionId: 'ver-1',
+        authorizedRevision: 1,
         publishAt: new Date('2026-08-23T12:00:00.000Z'),
         state: 'armed',
         suspendedAt: null,
@@ -66,7 +69,10 @@ function createMockDb() {
     const archivePublishedVersions = vi.fn().mockResolvedValue(0);
     const softDeleteDocument = vi.fn().mockResolvedValue(1);
     const deleteDocumentLocale = vi.fn().mockResolvedValue({ newVersionId: 'ver-2' });
-    const getDocumentById = vi.fn().mockResolvedValue(null);
+    const getDocumentById = vi.fn().mockImplementation(async () => {
+        const metadata = await getCurrentVersionMetadata();
+        return metadata == null ? null : { ...metadata, fields: {}, path: await getCurrentPath() };
+    });
     const getDocumentSystemFieldsForUpdate = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
     const getCurrentPath = vi.fn().mockResolvedValue('current-path');
@@ -85,7 +91,20 @@ function createMockDb() {
     // in unit tests (runs the unit of work immediately, no real tx); `append`
     // records the calls so write-point tests can assert the audit rows emitted.
     const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
-    const withTransaction = vi.fn(async (fn) => fn());
+    let transactionDepth = 0;
+    const revisions = new Map();
+    const transaction = {
+        run: async (fn) => {
+            transactionDepth++;
+            try {
+                return await fn();
+            }
+            finally {
+                transactionDepth--;
+            }
+        },
+    };
+    const withTransaction = vi.spyOn(transaction, 'run');
     const fail = () => {
         throw new Error('unexpected singleton mapping call');
     };
@@ -103,14 +122,60 @@ function createMockDb() {
     });
     const db = {
         classifyError,
+        revisions: {
+            ...unusedRevisionStore,
+            isInTransaction: () => transactionDepth > 0,
+            lock: vi.fn(async (targets) => {
+                const observations = [];
+                for (const target of targets) {
+                    const revision = revisions.get(target.documentId) ?? 1;
+                    if (target.expectedRevision !== revision)
+                        throw ERR_DOCUMENT_STALE({
+                            message: 'stale',
+                            details: {
+                                reason: 'revision_mismatch',
+                                documentId: target.documentId,
+                                expectedRevision: target.expectedRevision,
+                                currentRevision: revision,
+                            },
+                        });
+                    const system = await getDocumentSystemFieldsForUpdate({
+                        collection_id: target.collectionId,
+                        document_id: target.documentId,
+                    });
+                    const source = await getDocumentById.mock.results.at(-1)?.value;
+                    if (!system && !source)
+                        throw ERR_NOT_FOUND({ message: 'document not found' });
+                    observations.push({
+                        documentId: target.documentId,
+                        collectionId: target.collectionId,
+                        revision,
+                        currentVersionId: source?.document_version_id ?? 'ver-1',
+                        status: source?.status ?? 'draft',
+                        sourceLocale: system?.source_locale ?? source?.source_locale ?? 'en',
+                        path: system?.path ?? source?.path ?? null,
+                        availableLocales: system?.availableLocales ?? source?.availableLocales ?? [],
+                    });
+                }
+                return observations;
+            }),
+            advance: vi.fn(async (locked) => {
+                const revision = locked.revision + 1;
+                revisions.set(locked.documentId, revision);
+                return { documentId: locked.documentId, revision };
+            }),
+        },
+        withReadSnapshot: (fn) => runReadSnapshot(db.queries, fn),
         commands: {
             collections: {
+                lockCollectionRegistration: vi.fn(async () => { }),
                 create: vi.fn(),
                 update: vi.fn(),
                 delete: vi.fn(),
             },
             documents: {
                 publishSchedules: {
+                    lockDocuments: vi.fn(async () => { }),
                     schedule: publishSchedule,
                     confirm: confirmPublishSchedule,
                     cancel: cancelPublishSchedule,
@@ -150,12 +215,12 @@ function createMockDb() {
             },
             audit: { append: auditAppend },
             singletons: {
-                lockSlot: vi.fn(fail),
+                lockSlot: vi.fn(async () => { }),
                 setMapping: vi.fn(fail),
                 clearMapping: vi.fn(fail),
             },
         },
-        withTransaction: withTransaction,
+        withTransaction: transaction.run,
         queries: {
             collections: {
                 getAllCollections: vi.fn(),
@@ -167,6 +232,7 @@ function createMockDb() {
                     get: getPublishSchedule,
                     list: listPublishSchedules,
                 },
+                getDocumentRevision: async ({ document_id }) => revisions.get(document_id) ?? 1,
                 getDocumentSystemFieldsForUpdate,
                 getDocumentById,
                 getCurrentVersionMetadata,
@@ -335,6 +401,36 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('classifies an afterCreate failure as post-commit and retains committed ids', async () => {
+            const afterCreate = vi.fn().mockRejectedValue(new Error('cache unavailable'));
+            const { db, createDocumentVersion } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            await expect(createDocument(buildCtx(db, definition), { data: { title: 'X' } })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterCreate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
+        it('preserves committed classification when diagnostic logging also fails', async () => {
+            const afterCreate = vi.fn().mockRejectedValue(new Error('cache unavailable'));
+            const { db } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            const ctx = buildCtx(db, definition);
+            ctx.logger = {
+                ...noopLogger,
+                log: vi.fn(() => {
+                    throw new Error('logger failed');
+                }),
+            };
+            await expect(createDocument(ctx, { data: { title: 'X' } })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+            });
+        });
         it('afterCreate receives the resolved canonical path', async () => {
             const afterCreate = vi.fn();
             const { db } = createMockDb();
@@ -529,11 +625,48 @@ describe('Document lifecycle service', () => {
     // updateDocument (PUT)
     // -----------------------------------------------------------------------
     describe('updateDocument', () => {
+        it('normalizes a stale parent from persistence without firing success hooks', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'observed',
+                status: 'draft',
+                fields: { title: 'Old' },
+            });
+            const raw = new BylineError(ErrorCodes.CONFLICT, {
+                message: 'previous document version is stale',
+                details: {
+                    reason: 'stale',
+                    documentId: 'doc-1',
+                    previousVersionId: 'observed',
+                    currentVersionId: 'concurrent',
+                },
+            });
+            createDocumentVersion.mockRejectedValue(raw);
+            const afterUpdate = vi.fn();
+            await expect(updateDocument(buildCtx(db, { ...minimalCollection, hooks: { afterUpdate } }), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_STALE,
+                cause: raw,
+                details: {
+                    reason: 'version_parent_mismatch',
+                    documentId: 'doc-1',
+                    previousVersionId: 'observed',
+                    currentVersionId: 'concurrent',
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+            expect(afterUpdate).not.toHaveBeenCalled();
+            expect(db.commands.documents.publishSchedules.suspendForContentEdit).not.toHaveBeenCalled();
+        });
         it('passes the acting user id as createdBy for the audit trail', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });
             const ctx = buildCtx(db);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'New' },
             });
@@ -546,6 +679,7 @@ describe('Document lifecycle service', () => {
             const definition = { ...minimalCollection, hooks: { beforeUpdate } };
             const ctx = buildCtx(db, definition);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'New' },
             });
@@ -567,6 +701,7 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...numericCollection, hooks: { beforeUpdate } };
             await updateDocument(buildCtx(db, definition), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { quantity: '2', score: '2.5e1', price: 4.25 },
             });
@@ -583,6 +718,7 @@ describe('Document lifecycle service', () => {
             const definition = { ...minimalCollection, hooks: { afterUpdate } };
             const ctx = buildCtx(db, definition);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'New' },
             });
@@ -591,6 +727,26 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('classifies an afterUpdate failure as post-commit and retains committed ids', async () => {
+            const afterUpdate = vi.fn().mockRejectedValue(new Error('search unavailable'));
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ fields: { title: 'Old' } });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            await expect(updateDocument(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('afterUpdate carries the sticky path forward when none is supplied', async () => {
             const afterUpdate = vi.fn();
             const { db, getDocumentById } = createMockDb();
@@ -601,7 +757,11 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...minimalCollection, hooks: { afterUpdate } };
             const ctx = buildCtx(db, definition);
-            await updateDocument(ctx, { documentId: 'doc-1', data: { title: 'New' } });
+            await updateDocument(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            });
             expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({ path: 'sticky-path' }));
         });
         it('afterUpdate surfaces an explicitly-supplied path', async () => {
@@ -615,6 +775,7 @@ describe('Document lifecycle service', () => {
             const definition = { ...minimalCollection, hooks: { afterUpdate } };
             const ctx = buildCtx(db, definition);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'New' },
                 path: 'new-path',
@@ -632,6 +793,7 @@ describe('Document lifecycle service', () => {
             const definition = { ...minimalCollection, useAsPath: 'title' };
             const ctx = buildCtx(db, definition);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'Brand New Title' },
             });
@@ -649,6 +811,7 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(db);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'New' },
                 path: 'manually-set',
@@ -663,6 +826,7 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(db);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'Updated' },
             });
@@ -681,6 +845,7 @@ describe('Document lifecycle service', () => {
             const warn = ctx.logger?.warn;
             warn.mockClear();
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'À propos' },
                 locale: 'fr',
@@ -714,6 +879,7 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(db);
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'Über uns — neu' },
                 locale: 'de',
@@ -733,6 +899,7 @@ describe('Document lifecycle service', () => {
             const warn = ctx.logger?.warn;
             warn.mockClear();
             await updateDocument(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'À propos' },
                 locale: 'fr',
@@ -755,6 +922,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(db);
             try {
                 await updateDocument(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     data: { title: 'About' },
                     path: 'home', // collides
@@ -785,21 +953,32 @@ describe('Document lifecycle service', () => {
             const original = new Error('connection refused');
             createDocumentVersion.mockRejectedValueOnce(original);
             const ctx = buildCtx(db);
-            await expect(updateDocument(ctx, { documentId: 'doc-1', data: { title: 'X' }, path: 'home' })).rejects.toBe(original);
+            await expect(updateDocument(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                data: { title: 'X' },
+                path: 'home',
+            })).rejects.toBe(original);
         });
         it('supports an array of beforeUpdate and afterUpdate hooks', async () => {
             const callOrder = [];
             const hooks = {
                 beforeUpdate: [
                     vi.fn(async () => {
+                        expect(db.revisions.isInTransaction()).toBe(false);
                         callOrder.push('before-1');
                     }),
                     vi.fn(async () => {
                         callOrder.push('before-2');
                     }),
                 ],
+                afterSystemFieldsChange: () => {
+                    expect(db.revisions.isInTransaction()).toBe(false);
+                    callOrder.push('after-system');
+                },
                 afterUpdate: [
                     vi.fn(async () => {
+                        expect(db.revisions.isInTransaction()).toBe(false);
                         callOrder.push('after-1');
                     }),
                     vi.fn(async () => {
@@ -815,8 +994,20 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await updateDocument(ctx, { documentId: 'doc-1', data: { title: 'New' } });
-            expect(callOrder).toEqual(['before-1', 'before-2', 'persist', 'after-1', 'after-2']);
+            await updateDocument(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                data: { title: 'New' },
+                availableLocales: ['en', 'fr'],
+            });
+            expect(callOrder).toEqual([
+                'before-1',
+                'before-2',
+                'persist',
+                'after-system',
+                'after-1',
+                'after-2',
+            ]);
         });
     });
     // -----------------------------------------------------------------------
@@ -828,22 +1019,44 @@ describe('Document lifecycle service', () => {
             getDocumentById.mockResolvedValue(null);
             const ctx = buildCtx(db);
             await expect(updateDocumentWithPatches(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-missing',
                 patches: [],
             })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND);
         });
-        it('throws ERR_CONFLICT on version mismatch', async () => {
+        it('classifies a post-patch afterUpdate failure without replaying the version write', async () => {
+            const afterUpdate = vi
+                .fn()
+                .mockRejectedValue(Object.assign(new Error('storage unavailable'), { code: ErrorCodes.STORAGE }));
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'previous-version',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            await expect(updateDocumentWithPatches(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                patches: [{ kind: 'field.set', path: 'title', value: 'New' }],
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.STORAGE,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
+        it('throws ERR_DOCUMENT_STALE on revision mismatch', async () => {
             const { db, getDocumentById } = createMockDb();
             getDocumentById.mockResolvedValue({
                 document_version_id: 'ver-current',
                 fields: { title: 'Old' },
             });
             const ctx = buildCtx(db);
-            await expect(updateDocumentWithPatches(ctx, {
-                documentId: 'doc-1',
-                patches: [],
-                documentVersionId: 'ver-stale',
-            })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.CONFLICT);
+            await expect(updateDocumentWithPatches(ctx, { expectedRevision: 2, documentId: 'doc-1', patches: [] })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.DOCUMENT_STALE);
         });
         it('throws ERR_PATCH_FAILED when applyPatches returns errors', async () => {
             const { db, getDocumentById } = createMockDb();
@@ -851,6 +1064,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(db);
             // array.move on a top-level (non-array) field should produce an error
             await expect(updateDocumentWithPatches(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 patches: [{ kind: 'array.move', path: 'title', itemId: 'x', toIndex: 0 }],
             })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.PATCH_FAILED);
@@ -862,6 +1076,7 @@ describe('Document lifecycle service', () => {
             const definition = { ...minimalCollection, hooks: { afterUpdate } };
             const ctx = buildCtx(db, definition);
             await updateDocumentWithPatches(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 patches: [{ kind: 'field.set', path: 'title', value: 'Patched' }],
             });
@@ -884,6 +1099,7 @@ describe('Document lifecycle service', () => {
             createDocumentVersion.mockRejectedValueOnce(pathUniqueViolation());
             const ctx = buildCtx(db);
             await expect(updateDocumentWithPatches(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 patches: [],
                 path: 'new-slug',
@@ -909,6 +1125,7 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...numericCollection, hooks: { beforeUpdate } };
             await updateDocumentWithPatches(buildCtx(db, definition), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 patches: [
                     { kind: 'field.set', path: 'quantity', value: '7.0' },
@@ -941,10 +1158,11 @@ describe('Document lifecycle service', () => {
             publishSchedule.mockResolvedValue({ status: 'scheduled', schedule, previous: null });
             const ctx = buildCtx(db);
             await expect(scheduleDocumentPublish(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
                 publishAt: schedule.publishAt.toISOString(),
-            })).resolves.toEqual(schedule);
+            })).resolves.toEqual({ ...schedule, revision: 2 });
             expect(publishSchedule).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 collectionId: 'col-1',
@@ -961,6 +1179,7 @@ describe('Document lifecycle service', () => {
                 }),
             });
             await expect(scheduleDocumentPublish(restricted, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
                 publishAt: schedule.publishAt.toISOString(),
@@ -971,6 +1190,7 @@ describe('Document lifecycle service', () => {
             getCurrentVersionMetadata.mockResolvedValue(metadataRow);
             publishSchedule.mockResolvedValue({ status: 'publish_at_not_future' });
             await expect(scheduleDocumentPublish(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
                 publishAt: new Date(Date.now() + 60_000).toISOString(),
@@ -980,15 +1200,20 @@ describe('Document lifecycle service', () => {
                 document_version_id: 'ver-2',
             });
             await expect(scheduleDocumentPublish(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
                 publishAt: new Date(Date.now() + 60_000).toISOString(),
-            })).rejects.toMatchObject({ code: ErrorCodes.CONFLICT });
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_STALE,
+                details: { reason: 'version_parent_mismatch' },
+            });
         });
         it('rejects date strings that are valid to JavaScript but are not ISO instants', async () => {
             const { db, getCurrentVersionMetadata, publishSchedule } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue(metadataRow);
             await expect(scheduleDocumentPublish(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
                 publishAt: 'August 23, 2026 12:00:00 UTC',
@@ -1011,10 +1236,11 @@ describe('Document lifecycle service', () => {
             });
             cancelPublishSchedule.mockResolvedValue(confirmed);
             await expect(confirmDocumentScheduledPublish(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 expectedVersionId: 'ver-1',
-            })).resolves.toEqual(confirmed);
-            await expect(cancelDocumentScheduledPublish(buildCtx(db), { documentId: 'doc-1' })).resolves.toEqual(confirmed);
+            })).resolves.toEqual({ ...confirmed, revision: 2 });
+            await expect(cancelDocumentScheduledPublish(buildCtx(db), { expectedRevision: 2, documentId: 'doc-1' })).resolves.toEqual({ schedule: confirmed, revision: 3 });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({ action: 'document.publish.reconfirmed' }));
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({ action: 'document.publish.schedule.cancelled' }));
             expect(suspended.state).toBe('needs_reconfirm');
@@ -1035,10 +1261,12 @@ describe('Document lifecycle service', () => {
             });
             suspendPublishSchedule.mockResolvedValue({ status: 'suspended', schedule });
             await updateDocument(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 data: { title: 'After' },
             });
             expect(suspendPublishSchedule).toHaveBeenCalledWith({
+                reason: 'content_edited',
                 documentId: 'doc-1',
                 collectionId: 'col-1',
             });
@@ -1061,19 +1289,49 @@ describe('Document lifecycle service', () => {
                     suspendedReason: 'content_edited',
                 }),
             });
-            await deleteLocale(buildCtx(db), { documentId: 'doc-1', locale: 'fr' });
+            await deleteLocale(buildCtx(db), { expectedRevision: 1, documentId: 'doc-1', locale: 'fr' });
             expect(deleteDocumentLocale).toHaveBeenCalledOnce();
             expect(suspendPublishSchedule).toHaveBeenCalledWith({
+                reason: 'content_edited',
                 documentId: 'doc-1',
                 collectionId: 'col-1',
             });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({ action: 'document.publish.schedule.suspended' }));
         });
+        it('classifies a delete-locale afterUpdate failure after the new version commits', async () => {
+            const { db, deleteDocumentLocale, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'current-path',
+                _availableVersionLocales: ['en', 'fr'],
+                fields: { title: 'Bonjour' },
+            });
+            const definition = {
+                ...minimalCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            await expect(deleteLocale(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                locale: 'fr',
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-2',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(deleteDocumentLocale).toHaveBeenCalledOnce();
+        });
         it('cancels an active schedule as an effect of an ordinary status transition', async () => {
             const { db, getCurrentVersionMetadata, cancelPublishSchedule, auditAppend } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue(metadataRow);
             cancelPublishSchedule.mockResolvedValue(publishScheduleRow());
             await changeDocumentStatus(buildCtx(db), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 nextStatus: 'published',
             });
@@ -1137,6 +1395,7 @@ describe('Document lifecycle service', () => {
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
             const result = await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 nextStatus: 'published',
             });
@@ -1151,9 +1410,13 @@ describe('Document lifecycle service', () => {
             const { db, getCurrentVersionMetadata, auditAppend, withTransaction } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
-            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
-            // The mutation + audit row run inside one withTransaction (docs/07-auth-and-security/02-auditability.md).
-            expect(withTransaction).toHaveBeenCalledOnce();
+            await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'published',
+            });
+            // The guarded transaction contains a nested status savepoint (docs/07-auth-and-security/02-auditability.md).
+            expect(withTransaction).toHaveBeenCalledTimes(2);
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 collectionId: 'col-1',
@@ -1169,14 +1432,22 @@ describe('Document lifecycle service', () => {
             const { db, getCurrentVersionMetadata } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue(null);
             const ctx = buildCtx(db);
-            await expect(changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND);
+            await expect(changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'published',
+            })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND);
         });
         it('throws ERR_INVALID_TRANSITION for an invalid transition', async () => {
             const { db, getCurrentVersionMetadata } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
             // draft → archived skips 'published', which is not ±1
-            await expect(changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'archived' })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.INVALID_TRANSITION);
+            await expect(changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'archived',
+            })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.INVALID_TRANSITION);
         });
         it('invokes beforeStatusChange and afterStatusChange hooks', async () => {
             const callOrder = [];
@@ -1195,7 +1466,11 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
+            await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'published',
+            });
             expect(callOrder).toEqual(['before', 'persist', 'after']);
             expect(hooks.beforeStatusChange).toHaveBeenCalledWith(expect.objectContaining({
                 previousStatus: 'draft',
@@ -1215,7 +1490,11 @@ describe('Document lifecycle service', () => {
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await expect(changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'archived' })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.INVALID_TRANSITION);
+            await expect(changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'archived',
+            })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.INVALID_TRANSITION);
             expect(hooks.beforeStatusChange).not.toHaveBeenCalled();
             expect(hooks.afterStatusChange).not.toHaveBeenCalled();
         });
@@ -1223,7 +1502,11 @@ describe('Document lifecycle service', () => {
             const { db, getCurrentVersionMetadata, archivePublishedVersions } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
-            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
+            await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'published',
+            });
             expect(archivePublishedVersions).toHaveBeenCalledWith({
                 document_id: 'doc-1',
                 excludeVersionId: 'ver-1',
@@ -1256,7 +1539,11 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
+            await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'published',
+            });
             expect(callOrder).toEqual(['before-1', 'before-2', 'persist', 'after-1', 'after-2']);
         });
     });
@@ -1266,16 +1553,30 @@ describe('Document lifecycle service', () => {
     describe('unpublishDocument', () => {
         it('calls archivePublishedVersions and returns count', async () => {
             const { db, archivePublishedVersions } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockResolvedValue(1);
             const ctx = buildCtx(db);
-            const result = await unpublishDocument(ctx, { documentId: 'doc-1' });
+            const result = await unpublishDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(result.archivedCount).toBe(1);
             expect(archivePublishedVersions).toHaveBeenCalledWith({ document_id: 'doc-1' });
         });
         it('records an atomic published to archived status audit when versions change', async () => {
             const { db, archivePublishedVersions, auditAppend, withTransaction } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockResolvedValue(2);
-            await unpublishDocument(buildCtx(db), { documentId: 'doc-1' });
+            await unpublishDocument(buildCtx(db), { expectedRevision: 1, documentId: 'doc-1' });
             expect(withTransaction).toHaveBeenCalledOnce();
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
@@ -1290,16 +1591,31 @@ describe('Document lifecycle service', () => {
         });
         it('does not record an audit row when no published version changes', async () => {
             const { db, archivePublishedVersions, auditAppend } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockResolvedValue(0);
-            await unpublishDocument(buildCtx(db), { documentId: 'doc-1' });
+            await unpublishDocument(buildCtx(db), { expectedRevision: 1, documentId: 'doc-1' });
             expect(auditAppend).not.toHaveBeenCalled();
         });
         it('does not run afterUnpublish when the atomic audit unit fails', async () => {
             const afterUnpublish = vi.fn();
             const { db, archivePublishedVersions, auditAppend } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockResolvedValue(1);
             auditAppend.mockRejectedValue(new Error('audit failed'));
             await expect(unpublishDocument(buildCtx(db, { ...minimalCollection, hooks: { afterUnpublish } }), {
+                expectedRevision: 1,
                 documentId: 'doc-1',
             })).rejects.toThrow('audit failed');
             expect(afterUnpublish).not.toHaveBeenCalled();
@@ -1315,13 +1631,20 @@ describe('Document lifecycle service', () => {
                 }),
             };
             const { db, archivePublishedVersions } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockImplementation(async () => {
                 callOrder.push('archive');
                 return 2;
             });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await unpublishDocument(ctx, { documentId: 'doc-1' });
+            await unpublishDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(callOrder).toEqual(['before', 'archive', 'after']);
             expect(hooks.beforeUnpublish).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'current-path' }));
             expect(hooks.afterUnpublish).toHaveBeenCalledWith(expect.objectContaining({
@@ -1332,9 +1655,16 @@ describe('Document lifecycle service', () => {
         });
         it('works when no hooks are defined', async () => {
             const { db, archivePublishedVersions } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockResolvedValue(0);
             const ctx = buildCtx(db);
-            const result = await unpublishDocument(ctx, { documentId: 'doc-1' });
+            const result = await unpublishDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(result.archivedCount).toBe(0);
         });
         it('supports an array of beforeUnpublish and afterUnpublish hooks', async () => {
@@ -1358,13 +1688,20 @@ describe('Document lifecycle service', () => {
                 ],
             };
             const { db, archivePublishedVersions } = createMockDb();
+            vi.mocked(db.queries.documents.getDocumentById).mockResolvedValue({
+                document_id: 'doc-1',
+                document_version_id: 'ver-1',
+                status: 'published',
+                path: 'current-path',
+                fields: {},
+            });
             archivePublishedVersions.mockImplementation(async () => {
                 callOrder.push('archive');
                 return 2;
             });
             const definition = { ...minimalCollection, hooks };
             const ctx = buildCtx(db, definition);
-            await unpublishDocument(ctx, { documentId: 'doc-1' });
+            await unpublishDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(callOrder).toEqual(['before-1', 'before-2', 'archive', 'after-1', 'after-2']);
         });
     });
@@ -1384,7 +1721,7 @@ describe('Document lifecycle service', () => {
             });
             const definition = { ...minimalCollection, hooks: { beforeDelete, afterDelete } };
             const ctx = buildCtx(db, definition);
-            await deleteDocument(ctx, { documentId: 'doc-1' });
+            await deleteDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(beforeDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
             expect(afterDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
         });
@@ -1397,7 +1734,7 @@ describe('Document lifecycle service', () => {
                 fields: {},
             });
             const ctx = buildCtx(db);
-            await deleteDocument(ctx, { documentId: 'doc-1' });
+            await deleteDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(withTransaction).toHaveBeenCalledOnce();
             expect(softDeleteDocument).toHaveBeenCalledWith({ document_id: 'doc-1' });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
@@ -1420,7 +1757,7 @@ describe('Document lifecycle service', () => {
                 fields: {},
             });
             const definition = { ...minimalCollection, hooks: { beforeDelete, afterDelete } };
-            await expect(deleteDocument(buildCtx(db, definition), { documentId: 'doc-1' })).rejects.toThrow('pre-commit hook failed');
+            await expect(deleteDocument(buildCtx(db, definition), { expectedRevision: 1, documentId: 'doc-1' })).rejects.toThrow('pre-commit hook failed');
             expect(softDeleteDocument).not.toHaveBeenCalled();
             expect(afterDelete).not.toHaveBeenCalled();
         });
@@ -1466,8 +1803,8 @@ describe('Document lifecycle service', () => {
                 ...buildCtx(db, definition),
                 storage: { delete: storageDelete },
             };
-            await deleteDocument(ctx, { documentId: 'doc-1' });
-            expect(getDocumentById).toHaveBeenCalledWith(expect.objectContaining({ reconstruct: false }));
+            await deleteDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
+            expect(getDocumentById).toHaveBeenCalledWith(expect.objectContaining({ reconstruct: true }));
             expect(storageDelete).not.toHaveBeenCalled();
         });
         it('returns only allowlisted failures and keeps raw details in internal logs', async () => {
@@ -1511,9 +1848,13 @@ describe('Document lifecycle service', () => {
                 storage: { delete: storageDelete },
                 logger: { ...noopLogger, error: vi.fn() },
             };
-            const result = await deleteDocument(ctx, { documentId: 'doc-1' });
+            const result = await deleteDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
             expect(storageDelete).not.toHaveBeenCalled();
             expect(result).toEqual({
+                affectedDocuments: [{ documentId: 'doc-1', revision: 2 }],
+                scheduledPublicationsNeedReconfirmation: false,
+                documentId: 'doc-1',
+                revision: 2,
                 deletedVersionCount: 1,
                 outcome: 'committed-with-side-effect-failures',
                 sideEffectFailures: [{ phase: 'afterDelete', code: 'ERR_UNHANDLED' }],
@@ -1547,6 +1888,7 @@ describe('Document lifecycle service', () => {
             setupDoc(getDocumentSystemFieldsForUpdate);
             const ctx = buildCtx(db);
             const result = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 path: 'new-slug',
             });
@@ -1570,6 +1912,7 @@ describe('Document lifecycle service', () => {
             db.commands.documents.updateDocumentPath.mockRejectedValueOnce(pathUniqueViolation());
             const ctx = buildCtx(db);
             await expect(updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 path: 'new-slug',
             })).rejects.toMatchObject({
@@ -1591,6 +1934,7 @@ describe('Document lifecycle service', () => {
                 hooks: { afterSystemFieldsChange },
             });
             const result = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 path: 'old-slug',
             });
@@ -1605,6 +1949,7 @@ describe('Document lifecycle service', () => {
             setupDoc(getDocumentSystemFieldsForUpdate);
             const ctx = buildCtx(db);
             const result = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 availableLocales: ['en', 'fr'],
             });
@@ -1630,6 +1975,7 @@ describe('Document lifecycle service', () => {
                 hooks: { afterSystemFieldsChange },
             });
             const result = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 availableLocales: ['fr', 'en', 'fr'],
             });
@@ -1643,10 +1989,10 @@ describe('Document lifecycle service', () => {
             const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
             setupDoc(getDocumentSystemFieldsForUpdate);
             const order = [];
-            db.commands.documents.updateDocumentPath.mockImplementation(async () => {
+            vi.mocked(db.commands.documents.updateDocumentPath).mockImplementation(async () => {
                 order.push('path-write');
             });
-            db.commands.documents.setDocumentAvailableLocales.mockImplementation(async () => {
+            vi.mocked(db.commands.documents.setDocumentAvailableLocales).mockImplementation(async () => {
                 order.push('locales-write');
             });
             auditAppend.mockImplementation(async () => {
@@ -1670,6 +2016,7 @@ describe('Document lifecycle service', () => {
                 hooks: { afterSystemFieldsChange: [firstHook, secondHook] },
             });
             await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 path: 'new-slug',
                 availableLocales: ['fr', 'en', 'fr'],
@@ -1705,7 +2052,11 @@ describe('Document lifecycle service', () => {
                 ...minimalCollection,
                 hooks: { afterSystemFieldsChange },
             });
-            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' })).rejects.toThrow('audit failed');
+            await expect(updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                path: 'new-slug',
+            })).rejects.toThrow('audit failed');
             expect(db.commands.documents.updateDocumentPath).toHaveBeenCalledOnce();
             expect(afterSystemFieldsChange).not.toHaveBeenCalled();
         });
@@ -1726,7 +2077,14 @@ describe('Document lifecycle service', () => {
                 ...minimalCollection,
                 hooks: { afterSystemFieldsChange },
             });
-            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', availableLocales: ['en', 'fr'] })).rejects.toThrow('cache unavailable');
+            await expect(updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                availableLocales: ['en', 'fr'],
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: { revision: 2 },
+            });
             expect(committed).toBe(true);
             expect(db.commands.documents.setDocumentAvailableLocales).toHaveBeenCalledOnce();
             expect(afterSystemFieldsChange).toHaveBeenCalledOnce();
@@ -1742,9 +2100,17 @@ describe('Document lifecycle service', () => {
                 ...minimalCollection,
                 hooks: { afterSystemFieldsChange },
             });
-            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' })).rejects.toThrow('search unavailable');
+            await expect(updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                path: 'new-slug',
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: { revision: 2 },
+            });
             setupDoc(getDocumentSystemFieldsForUpdate, { path: 'new-slug' });
             const retry = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 2,
                 documentId: 'doc-1',
                 path: 'new-slug',
                 reconcile: true,
@@ -1778,6 +2144,7 @@ describe('Document lifecycle service', () => {
                 hooks: { afterSystemFieldsChange },
             });
             await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 path: 'final-path',
                 availableLocales: ['de'],
@@ -1811,7 +2178,7 @@ describe('Document lifecycle service', () => {
             };
             const mocks = createMockDb();
             const { db } = mocks;
-            db.queries.documents.getDocumentByVersion.mockResolvedValue({
+            vi.mocked(db.queries.documents.getDocumentByVersion).mockResolvedValue({
                 document_version_id: sourceVersionId,
                 document_id: sourceDocumentId,
                 path: 'long-ago-path',
@@ -1843,6 +2210,7 @@ describe('Document lifecycle service', () => {
             const { db, createDocumentVersion, sourceVersionId, sourceFields, currentVersionId } = setupRestore();
             const ctx = buildCtx(db);
             const result = await restoreDocumentVersion(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceVersionId,
             });
@@ -1859,13 +2227,18 @@ describe('Document lifecycle service', () => {
             expect(result).toEqual({
                 documentId: 'doc-1',
                 documentVersionId: 'ver-restored',
+                revision: 2,
                 sourceVersionId,
             });
         });
         it('hard-defaults the new version status to the workflow default (never inherits source status)', async () => {
             const { db, createDocumentVersion, sourceVersionId } = setupRestore();
             const ctx = buildCtx(db);
-            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            await restoreDocumentVersion(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceVersionId,
+            });
             // Source version was 'archived'; default status for minimalCollection is 'draft'.
             expect(createDocumentVersion.mock.calls[0]?.[0].status).toBe('draft');
         });
@@ -1874,7 +2247,11 @@ describe('Document lifecycle service', () => {
                 currentPath: 'sticky-path',
             });
             const ctx = buildCtx(db);
-            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            await restoreDocumentVersion(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceVersionId,
+            });
             // Restore never changes a document's path: the existing
             // byline_document_paths row carries forward unchanged. The storage
             // primitive only writes to document_paths when `path` is supplied.
@@ -1886,7 +2263,11 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(db);
             try {
-                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                await restoreDocumentVersion(ctx, {
+                    expectedRevision: 1,
+                    documentId: 'doc-1',
+                    sourceVersionId,
+                });
                 expect.fail('expected ERR_VALIDATION');
             }
             catch (err) {
@@ -1899,7 +2280,7 @@ describe('Document lifecycle service', () => {
             const sourceVersionId = 'ver-source';
             const mocks = createMockDb();
             const { db } = mocks;
-            db.queries.documents.getDocumentByVersion.mockResolvedValue({
+            vi.mocked(db.queries.documents.getDocumentByVersion).mockResolvedValue({
                 document_version_id: sourceVersionId,
                 document_id: 'doc-1',
                 path: 'p',
@@ -1917,7 +2298,11 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(db);
             try {
-                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                await restoreDocumentVersion(ctx, {
+                    expectedRevision: 1,
+                    documentId: 'doc-1',
+                    sourceVersionId,
+                });
                 expect.fail('expected ERR_INVALID_TRANSITION');
             }
             catch (err) {
@@ -1931,7 +2316,11 @@ describe('Document lifecycle service', () => {
             const { db, sourceVersionId } = setupRestore();
             const definition = { ...minimalCollection, hooks: { beforeUpdate, afterUpdate } };
             const ctx = buildCtx(db, definition);
-            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            await restoreDocumentVersion(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceVersionId,
+            });
             expect(beforeUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 collectionPath: 'articles',
                 restore: { sourceVersionId },
@@ -1947,6 +2336,27 @@ describe('Document lifecycle service', () => {
                 restore: { sourceVersionId },
             }));
         });
+        it('classifies a restore afterUpdate failure after the restored version commits', async () => {
+            const { db, sourceVersionId, createDocumentVersion } = setupRestore();
+            const definition = {
+                ...minimalCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            await expect(restoreDocumentVersion(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceVersionId,
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-restored',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('throws ERR_FORBIDDEN when actor lacks collections.<path>.update', async () => {
             const { db, sourceVersionId } = setupRestore();
             const ctx = buildCtx(db);
@@ -1956,7 +2366,11 @@ describe('Document lifecycle service', () => {
             });
             ctx.requestContext = createRequestContext({ actor });
             try {
-                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                await restoreDocumentVersion(ctx, {
+                    expectedRevision: 1,
+                    documentId: 'doc-1',
+                    sourceVersionId,
+                });
                 expect.fail('expected ERR_FORBIDDEN');
             }
             catch (err) {
@@ -1972,7 +2386,11 @@ describe('Document lifecycle service', () => {
                 abilities: ['collections.articles.update', 'collections.articles.read'],
             });
             ctx.requestContext = createRequestContext({ actor });
-            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            await restoreDocumentVersion(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceVersionId,
+            });
             expect(createDocumentVersion).toHaveBeenCalledOnce();
         });
     });
@@ -2017,7 +2435,7 @@ describe('Document lifecycle service', () => {
             const mocks = createMockDb();
             const { sourceDocumentId } = setupSource(mocks);
             const ctx = buildCtx(mocks.db, localizedCollection);
-            const result = await duplicateDocument(ctx, { sourceDocumentId });
+            const result = await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId });
             expect(mocks.getDocumentById).toHaveBeenCalledWith(expect.objectContaining({
                 collection_id: 'col-1',
                 document_id: sourceDocumentId,
@@ -2044,7 +2462,7 @@ describe('Document lifecycle service', () => {
                 },
             });
             const ctx = buildCtx(mocks.db, localizedCollection);
-            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
             expect(call.documentData.title).toEqual({
                 en: 'Hello (copy)',
@@ -2069,7 +2487,7 @@ describe('Document lifecycle service', () => {
                 },
             });
             const ctx = buildCtx(mocks.db, nonLocalizedCollection);
-            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
             expect(call.documentData.title).toBe('Hello (copy)');
         });
@@ -2082,7 +2500,10 @@ describe('Document lifecycle service', () => {
                 },
             });
             const ctx = buildCtx(mocks.db, localizedCollection);
-            const result = await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const result = await duplicateDocument(ctx, {
+                expectedRevision: 1,
+                sourceDocumentId: 'doc-source',
+            });
             const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
             // Default locale is 'en'; "Hello World (copy)" slugifies to "hello-world-copy".
             expect(call.path).toBe('hello-world-copy');
@@ -2108,7 +2529,7 @@ describe('Document lifecycle service', () => {
                 },
             });
             const ctx = buildCtx(mocks.db, localizedCollection);
-            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             const call = mocks.createDocumentVersion.mock.calls[0]?.[0];
             const sections = call.documentData.sections;
             expect(sections[0]._id).toBeUndefined();
@@ -2140,7 +2561,7 @@ describe('Document lifecycle service', () => {
                 fieldCount: 5,
             });
             const ctx = buildCtx(mocks.db, localizedCollection);
-            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             // Source title should be unchanged in memory.
             expect(originalFields.title).toEqual({ en: 'Hello', fr: 'Bonjour' });
             expect(originalFields.sections[0]?._id).toBe('sec-1');
@@ -2162,7 +2583,10 @@ describe('Document lifecycle service', () => {
                     fieldCount: 5,
                 });
             });
-            const result = await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            const result = await duplicateDocument(ctx, {
+                expectedRevision: 1,
+                sourceDocumentId: 'doc-source',
+            });
             expect(mocks.createDocumentVersion).toHaveBeenCalledTimes(2);
             const firstPath = mocks.createDocumentVersion.mock.calls[0]?.[0].path;
             const retryPath = mocks.createDocumentVersion.mock.calls[1]?.[0].path;
@@ -2183,7 +2607,7 @@ describe('Document lifecycle service', () => {
             });
             let thrown;
             try {
-                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+                await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             }
             catch (err) {
                 thrown = err;
@@ -2206,7 +2630,7 @@ describe('Document lifecycle service', () => {
             mocks.getDocumentById.mockResolvedValue(null);
             const ctx = buildCtx(mocks.db, localizedCollection);
             try {
-                await duplicateDocument(ctx, { sourceDocumentId: 'doc-missing' });
+                await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-missing' });
                 expect.fail('expected ERR_NOT_FOUND');
             }
             catch (err) {
@@ -2227,7 +2651,7 @@ describe('Document lifecycle service', () => {
             const mocks = createMockDb();
             setupSource(mocks, { sourceDocumentId: 'doc-source' });
             const ctx = buildCtx(mocks.db, withHooks);
-            await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
             expect(beforeCreate).toHaveBeenCalledOnce();
             const beforeCtx = beforeCreate.mock.calls[0]?.[0];
             expect(beforeCtx.duplicate).toEqual({ sourceDocumentId: 'doc-source' });
@@ -2246,6 +2670,27 @@ describe('Document lifecycle service', () => {
             expect(typeof afterCtx.path).toBe('string');
             expect(afterCtx.path).toBe(writtenPath);
         });
+        it('classifies a duplicate afterCreate failure with the committed document ids', async () => {
+            const withHooks = {
+                ...localizedCollection,
+                hooks: { afterCreate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            const mocks = createMockDb();
+            setupSource(mocks);
+            await expect(duplicateDocument(buildCtx(mocks.db, withHooks), {
+                expectedRevision: 1,
+                sourceDocumentId: 'doc-source',
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterCreate',
+                    documentId: 'doc-new',
+                    documentVersionId: 'ver-new',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('enforces collections.<path>.create — rejects an admin actor missing the ability', async () => {
             const mocks = createMockDb();
             setupSource(mocks);
@@ -2257,7 +2702,7 @@ describe('Document lifecycle service', () => {
             });
             ctx.requestContext = createRequestContext({ actor });
             try {
-                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+                await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
                 expect.fail('expected ERR_FORBIDDEN');
             }
             catch (err) {
@@ -2272,7 +2717,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(mocks.db, localizedCollection);
             ctx.requestContext = undefined;
             try {
-                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+                await duplicateDocument(ctx, { expectedRevision: 1, sourceDocumentId: 'doc-source' });
                 expect.fail('expected ERR_UNAUTHENTICATED');
             }
             catch (err) {
@@ -2351,6 +2796,7 @@ describe('Document lifecycle service', () => {
             const { mocks, currentVersionId } = setupSourceTarget();
             const ctx = buildCtx(mocks.db, mixedCollection);
             const result = await copyToLocale(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceLocale: 'en',
                 targetLocale: 'fr',
@@ -2390,6 +2836,7 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(mocks.db, mixedCollection);
             const result = await copyToLocale(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceLocale: 'en',
                 targetLocale: 'fr',
@@ -2421,6 +2868,7 @@ describe('Document lifecycle service', () => {
             });
             const ctx = buildCtx(mocks.db, mixedCollection);
             await copyToLocale(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceLocale: 'en',
                 targetLocale: 'fr',
@@ -2437,6 +2885,7 @@ describe('Document lifecycle service', () => {
             const { mocks } = setupSourceTarget();
             const ctx = buildCtx(mocks.db, mixedCollection);
             await copyToLocale(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceLocale: 'en',
                 targetLocale: 'fr',
@@ -2449,6 +2898,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(mocks.db, mixedCollection);
             try {
                 await copyToLocale(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     sourceLocale: 'en',
                     targetLocale: 'en',
@@ -2467,6 +2917,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(mocks.db, mixedCollection);
             try {
                 await copyToLocale(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     sourceLocale: 'en',
                     targetLocale: 'fr',
@@ -2497,6 +2948,7 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(mocks.db, mixedCollection);
             try {
                 await copyToLocale(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     sourceLocale: 'en',
                     targetLocale: 'fr',
@@ -2519,6 +2971,7 @@ describe('Document lifecycle service', () => {
             const { mocks } = setupSourceTarget();
             const ctx = buildCtx(mocks.db, withHooks);
             await copyToLocale(ctx, {
+                expectedRevision: 1,
                 documentId: 'doc-1',
                 sourceLocale: 'en',
                 targetLocale: 'fr',
@@ -2537,6 +2990,29 @@ describe('Document lifecycle service', () => {
             // Sticky path read off the target-locale envelope.
             expect(afterUpdate.mock.calls[0]?.[0].path).toBe('hello');
         });
+        it('classifies a copy-to-locale afterUpdate failure after the version commits', async () => {
+            const withHooks = {
+                ...mixedCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            const { mocks } = setupSourceTarget();
+            await expect(copyToLocale(buildCtx(mocks.db, withHooks), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-new',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('enforces collections.<path>.update — rejects an admin actor missing the ability', async () => {
             const { mocks } = setupSourceTarget();
             const ctx = buildCtx(mocks.db, mixedCollection);
@@ -2547,6 +3023,7 @@ describe('Document lifecycle service', () => {
             ctx.requestContext = createRequestContext({ actor });
             try {
                 await copyToLocale(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     sourceLocale: 'en',
                     targetLocale: 'fr',
@@ -2566,6 +3043,7 @@ describe('Document lifecycle service', () => {
             ctx.requestContext = undefined;
             try {
                 await copyToLocale(ctx, {
+                    expectedRevision: 1,
                     documentId: 'doc-1',
                     sourceLocale: 'en',
                     targetLocale: 'fr',
@@ -2639,7 +3117,11 @@ describe('Document lifecycle service', () => {
             });
             ctx.requestContext = createRequestContext({ actor });
             try {
-                await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
+                await changeDocumentStatus(ctx, {
+                    expectedRevision: 1,
+                    documentId: 'doc-1',
+                    nextStatus: 'published',
+                });
                 expect.fail('expected ERR_FORBIDDEN');
             }
             catch (err) {
@@ -2675,7 +3157,11 @@ describe('Document lifecycle service', () => {
                 abilities: ['collections.articles.changeStatus'],
             });
             ctx.requestContext = createRequestContext({ actor });
-            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'in_review' });
+            await changeDocumentStatus(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                nextStatus: 'in_review',
+            });
             expect(setDocumentStatus).toHaveBeenCalledOnce();
         });
         it('super-admin bypasses every check', async () => {
@@ -2700,7 +3186,7 @@ describe('Document lifecycle service', () => {
             });
             ctx.requestContext = createRequestContext({ actor });
             try {
-                await deleteDocument(ctx, { documentId: 'doc-1' });
+                await deleteDocument(ctx, { expectedRevision: 1, documentId: 'doc-1' });
                 expect.fail('expected ERR_FORBIDDEN');
             }
             catch (err) {