@byline/core 4.18.0 → 5.0.0

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

@@ -5,103 +5,170 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
-import { withLogContext } from '../../lib/logger.js';
+import { resolveHooks } from '../../@types/index.js';
+import { DbErrorCodes, ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ERR_VALIDATION, } from '../../lib/errors.js';
+import { documentRevisionFromDatabase, parseDocumentRevision, } from '../../storage/document-revision.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed } from '../document-lifecycle/internals.js';
+import { runCommittedDocumentHook } from '../document-lifecycle/committed-hook.js';
+import { applyRichTextEmbed, extractDocumentId, extractVersionId, } from '../document-lifecycle/internals.js';
 import { persistExistingDocumentVersion, persistInitialDocumentVersion, } from '../document-lifecycle/persistence.js';
+import { assertLifecycleTransactionOwnership } from '../document-lifecycle/revision-guard.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
-import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
-/** Materialise or update a singleton slot as one immutable document version. */
+import { authorizeSingletonUpdate } from './internals.js';
+/** Prepare outside locks; recheck the observed slot/document under S → D before committing. */
 export async function updateSingleton(ctx, params) {
-    return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'updateSingleton' }, async () => {
-        const definition = authorizeSingletonUpdate(ctx);
-        const locale = params.locale ?? ctx.defaultLocale;
-        const data = params.data;
-        return commitSingletonSave({
-            ctx,
-            definition,
-            operation: { type: 'save' },
-            prepare: async (slot) => {
-                if (slot.documentId == null && locale !== ctx.defaultLocale) {
-                    throw ERR_VALIDATION({
-                        message: `a singleton's first save must use the default content locale ` +
-                            `('${ctx.defaultLocale}'); received '${locale}'`,
-                        details: {
-                            singletonPath: ctx.collectionPath,
-                            defaultLocale: ctx.defaultLocale,
-                            providedLocale: locale,
-                        },
-                    }).log(ctx.logger);
-                }
-                if (params.expectedVersionId != null) {
-                    const currentVersionId = slot.currentVersion?.document_version_id;
-                    if (currentVersionId !== params.expectedVersionId) {
-                        throw ERR_CONFLICT({
-                            message: 'singleton version conflict',
-                            details: {
-                                singletonPath: ctx.collectionPath,
-                                expectedVersionId: params.expectedVersionId,
-                                currentVersionId: currentVersionId ?? null,
-                            },
-                        }).log(ctx.logger);
-                    }
-                }
-                const current = slot.documentId == null
-                    ? null
-                    : await ctx.db.queries.documents.getDocumentById({
-                        collection_id: ctx.collectionId,
-                        document_id: slot.documentId,
-                        locale,
-                        reconstruct: true,
-                        lenient: true,
-                        requestContext: ctx.requestContext,
-                    });
-                if (slot.documentId != null && current == null) {
-                    throw ERR_CONFLICT({
-                        message: `singleton '${ctx.collectionPath}' could not reconstruct its mapped document`,
-                        details: { singletonPath: ctx.collectionPath, documentId: slot.documentId },
-                    }).log(ctx.logger);
-                }
-                const currentRecord = current;
-                const originalData = currentRecord?.fields ?? null;
-                normaliseDateFields(data);
-                normalizeNumericFields(definition.fields, data);
-                return {
-                    data,
-                    originalData,
-                    locale,
-                    write: async () => {
-                        normalizeNumericFields(definition.fields, data);
-                        await assignCounterValues({
-                            fields: definition.fields,
-                            data,
-                            previousData: originalData ?? undefined,
-                            counters: ctx.db.commands.counters,
-                        });
-                        await applyRichTextEmbed(ctx, data);
-                        if (slot.documentId == null) {
-                            return persistInitialDocumentVersion(ctx, {
-                                action: 'create',
-                                documentData: data,
-                                path: crypto.randomUUID(),
-                                status: getDefaultStatus(definition),
-                                locale,
-                            });
-                        }
-                        return persistExistingDocumentVersion(ctx, {
-                            documentId: slot.documentId,
-                            action: 'update',
-                            documentData: data,
-                            status: getDefaultStatus(definition),
-                            locale,
-                            previousVersionId: slot.currentVersion?.document_version_id,
-                        });
-                    },
-                };
-            },
+    params = { ...params };
+    const definition = authorizeSingletonUpdate(ctx);
+    assertLifecycleTransactionOwnership(ctx);
+    const expectedEmpty = params.expectedState === 'empty';
+    if (expectedEmpty && params.expectedRevision !== undefined)
+        throw ERR_VALIDATION({ message: 'Specify an empty slot or a document revision, not both' });
+    if (params.expectedState !== undefined && !expectedEmpty)
+        throw ERR_VALIDATION({ message: 'Invalid singleton slot expectation' });
+    const expectedRevision = expectedEmpty
+        ? undefined
+        : parseDocumentRevision(params.expectedRevision);
+    const locale = params.locale ?? ctx.defaultLocale;
+    const staleSlot = () => ERR_DOCUMENT_STALE({
+        message: 'This singleton has changed. Reload it before saving.',
+        details: {
+            reason: 'singleton_slot_changed',
+            singletonPath: ctx.collectionPath,
+            expectedState: 'empty',
+            currentState: 'document',
+        },
+    });
+    const observed = await ctx.db.withReadSnapshot(async (queries) => {
+        const documentId = await queries.singletons.getMappedDocumentId(ctx.collectionId);
+        if (expectedEmpty && documentId !== null)
+            throw staleSlot();
+        if (!expectedEmpty && documentId === null)
+            throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' });
+        if (documentId === null)
+            return { documentId: null, current: null, revision: undefined };
+        const current = await queries.documents.getDocumentById({
+            collection_id: ctx.collectionId,
+            document_id: documentId,
+            locale,
+            reconstruct: true,
+            readMode: 'any',
+            lenient: true,
+        });
+        if (current === null)
+            throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' });
+        const revision = documentRevisionFromDatabase(await queries.documents.getDocumentRevision({
+            collection_id: ctx.collectionId,
+            document_id: documentId,
+        }));
+        if (revision !== expectedRevision)
+            throw ERR_DOCUMENT_STALE({
+                message: 'This singleton has changed. Reload it before saving.',
+                details: {
+                    reason: 'revision_mismatch',
+                    documentId,
+                    expectedRevision: expectedRevision,
+                    currentRevision: revision,
+                },
+            });
+        return { documentId, current, revision };
+    });
+    if (expectedEmpty && locale !== ctx.defaultLocale)
+        throw ERR_VALIDATION({
+            message: `A singleton's first save must use the default content locale ('${ctx.defaultLocale}')`,
         });
+    const previousVersionId = observed.current?.document_version_id;
+    const data = params.data;
+    const originalData = observed.current?.fields ?? null;
+    normaliseDateFields(data);
+    normalizeNumericFields(definition.fields, data);
+    const hooks = await resolveHooks(definition);
+    const before = {
+        data,
+        originalData,
+        singletonPath: ctx.collectionPath,
+        locale,
+        requestContext: ctx.requestContext,
+        isInitialSave: expectedEmpty,
+        operation: { type: 'save' },
+        documentId: observed.documentId,
+    };
+    const beforeHooks = hooks?.beforeSave == null
+        ? []
+        : Array.isArray(hooks.beforeSave)
+            ? hooks.beforeSave
+            : [hooks.beforeSave];
+    for (const hook of beforeHooks)
+        await hook(before);
+    normalizeNumericFields(definition.fields, data);
+    await assignCounterValues({
+        fields: definition.fields,
+        data,
+        previousData: originalData ?? undefined,
+        counters: ctx.db.commands.counters,
+    });
+    await applyRichTextEmbed(ctx, data);
+    const committed = await ctx.db.withTransaction(async () => {
+        await ctx.db.commands.singletons.lockSlot(ctx.collectionId);
+        const mappedDocumentId = await ctx.db.queries.singletons.getMappedDocumentId(ctx.collectionId);
+        if (expectedEmpty && mappedDocumentId !== null)
+            throw staleSlot();
+        if (mappedDocumentId !== observed.documentId)
+            throw ERR_NOT_FOUND({ message: 'Singleton document mapping changed; reload before saving' });
+        const locked = mappedDocumentId === null
+            ? null
+            : (await ctx.db.revisions.lock([
+                {
+                    documentId: mappedDocumentId,
+                    collectionId: ctx.collectionId,
+                    expectedRevision: expectedRevision,
+                    previousVersionId,
+                    locale,
+                },
+            ]))[0];
+        const write = { documentData: data, status: getDefaultStatus(definition), locale };
+        const result = mappedDocumentId === null
+            ? await persistInitialDocumentVersion(ctx, {
+                ...write,
+                action: 'create',
+                path: crypto.randomUUID(),
+            })
+            : await persistExistingDocumentVersion(ctx, {
+                ...write,
+                action: 'update',
+                documentId: mappedDocumentId,
+                previousVersionId,
+            });
+        const documentId = extractDocumentId(result.document);
+        const documentVersionId = extractVersionId(result.document);
+        if (!documentId || !documentVersionId)
+            throw new Error('Singleton persistence returned no document/version identity');
+        if (mappedDocumentId === null) {
+            try {
+                await ctx.db.commands.singletons.setMapping(ctx.collectionId, documentId);
+            }
+            catch (error) {
+                if (ctx.db.classifyError?.(error).code === DbErrorCodes.UNIQUE_VIOLATION)
+                    throw staleSlot();
+                throw error;
+            }
+        }
+        const revision = locked === null ? 1 : (await ctx.db.revisions.advance(locked)).revision;
+        return { documentId, documentVersionId, revision };
+    });
+    await runCommittedDocumentHook(ctx, { phase: 'afterSave', ...committed }, async () => {
+        const afterHooks = hooks?.afterSave == null
+            ? []
+            : Array.isArray(hooks.afterSave)
+                ? hooks.afterSave
+                : [hooks.afterSave];
+        for (const hook of afterHooks)
+            await hook({
+                ...before,
+                documentId: committed.documentId,
+                documentVersionId: committed.documentVersionId,
+            });
     });
+    return committed;
 }

package/dist/services/singleton-lifecycle.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/singleton-lifecycle.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
@@ -7,7 +8,8 @@
  */
 import { AdminAuth, createRequestContext } from '@byline/auth';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { DbErrorCodes } from '../lib/errors.js';
+import { DbErrorCodes, ERR_DOCUMENT_STALE, ErrorCodes, } from '../lib/errors.js';
+import { runReadSnapshot } from '../storage/read-snapshot.js';
 import { copySingletonToLocale, resolveSingletonDocumentId, restoreSingletonVersion, updateSingleton, } from './singleton-lifecycle/index.js';
 const noopLogger = {
     log: vi.fn(),
@@ -47,10 +49,13 @@ function createHarness(options = {}) {
         views.set('en', { fields: { title: 'Before', count: 1 } });
         views.set('all', { fields: { title: { en: 'Before' }, count: 1 } });
     }
+    let revision = 1;
     let transactionDepth = 0;
     let committedTransactions = 0;
     let versionCounter = 0;
-    const withTransaction = vi.fn(async (operation) => {
+    const withTransaction = vi.fn();
+    const transact = async (operation) => {
+        withTransaction();
         const isOuter = transactionDepth === 0;
         const snapshot = isOuter
             ? {
@@ -58,6 +63,7 @@ function createHarness(options = {}) {
                 currentVersion,
                 views: new Map(views),
                 versionCounter,
+                revision,
             }
             : null;
         transactionDepth++;
@@ -77,10 +83,11 @@ function createHarness(options = {}) {
                 for (const [locale, view] of snapshot.views)
                     views.set(locale, view);
                 versionCounter = snapshot.versionCounter;
+                revision = snapshot.revision;
             }
             throw error;
         }
-    });
+    };
     const lockSlot = vi.fn(async () => {
         expect(transactionDepth).toBeGreaterThan(0);
     });
@@ -122,9 +129,38 @@ function createHarness(options = {}) {
     });
     const getDocumentByVersion = vi.fn(async (params) => versions.get(params.document_version_id));
     const classifyError = vi.fn((_error) => ({ code: DbErrorCodes.UNKNOWN }));
-    const db = {
+    const db = testAdapter({
         classifyError,
+        revisions: {
+            isInTransaction: () => transactionDepth > 0,
+            lock: vi.fn(async (targets) => targets.map((target) => {
+                expect(transactionDepth).toBeGreaterThan(0);
+                if (target.expectedRevision !== revision)
+                    throw ERR_DOCUMENT_STALE({
+                        message: 'Reload before saving',
+                        details: {
+                            reason: 'revision_mismatch',
+                            documentId: target.documentId,
+                            expectedRevision: target.expectedRevision,
+                            currentRevision: revision,
+                        },
+                    });
+                return {
+                    documentId: target.documentId,
+                    collectionId: 'col-1',
+                    revision,
+                    currentVersionId: currentVersion?.document_version_id ?? null,
+                    status: currentVersion?.status ?? null,
+                    sourceLocale: 'en',
+                    path: 'settings',
+                    availableLocales: ['en'],
+                };
+            })),
+            advance: vi.fn(async (locked) => ({ documentId: locked.documentId, revision: ++revision })),
+        },
+        withReadSnapshot: ((callback) => runReadSnapshot(db.queries, callback)),
         commands: {
+            collections: { lockCollectionRegistration: vi.fn(async () => { }) },
             documents: {
                 createDocumentVersion,
                 publishSchedules: {
@@ -146,13 +182,14 @@ function createHarness(options = {}) {
         queries: {
             documents: {
                 getCurrentVersionMetadata,
+                getDocumentRevision: vi.fn(async () => revision),
                 getDocumentById,
                 getDocumentByVersion,
             },
             singletons: { getMappedDocumentId },
         },
-        withTransaction,
-    };
+        withTransaction: transact,
+    });
     const actor = new AdminAuth({
         id: 'editor',
         abilities: ['singletons.site-settings.update'],
@@ -200,7 +237,7 @@ describe('singleton lifecycle service', () => {
         harness = createHarness({
             hooks: {
                 beforeSave: (context) => {
-                    expect(harness.isInTransaction()).toBe(true);
+                    expect(harness.isInTransaction()).toBe(false);
                     contexts.push({ phase: 'before', ...context });
                     context.data.title = 'Mutated by hook';
                 },
@@ -211,8 +248,11 @@ describe('singleton lifecycle service', () => {
                 },
             },
         });
-        const result = await updateSingleton(harness.ctx, { data: { title: 'Incoming' } });
-        expect(result).toEqual({ documentId: 'doc-1', documentVersionId: 'ver-1' });
+        const result = await updateSingleton(harness.ctx, {
+            expectedState: 'empty',
+            data: { title: 'Incoming' },
+        });
+        expect(result).toEqual({ documentId: 'doc-1', documentVersionId: 'ver-1', revision: 1 });
         expect(harness.lockSlot).toHaveBeenCalledOnce();
         expect(harness.setMapping).toHaveBeenCalledWith('col-1', 'doc-1');
         expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({
@@ -249,9 +289,9 @@ describe('singleton lifecycle service', () => {
             code: DbErrorCodes.UNIQUE_VIOLATION,
             constraint,
         });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'Losing write' } })).rejects.toMatchObject({
-            code: 'ERR_CONFLICT',
-            message: "singleton 'site-settings' was materialised concurrently",
+        await expect(updateSingleton(harness.ctx, { expectedState: 'empty', data: { title: 'Losing write' } })).rejects.toMatchObject({
+            code: 'ERR_DOCUMENT_STALE',
+            details: { reason: 'singleton_slot_changed' },
         });
         expect(harness.classifyError).toHaveBeenCalledWith(uniqueViolation);
         expect(harness.committedTransactions()).toBe(0);
@@ -268,7 +308,7 @@ describe('singleton lifecycle service', () => {
         const harness = createHarness({ mapped: true, hooks: { beforeSave, afterSave } });
         await updateSingleton(harness.ctx, {
             data: { title: 'After', count: '2' },
-            expectedVersionId: 'ver-current',
+            expectedRevision: 1,
         });
         expect(harness.setMapping).not.toHaveBeenCalled();
         expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({
@@ -289,39 +329,39 @@ describe('singleton lifecycle service', () => {
         harness.ctx.requestContext = createRequestContext({
             actor: new AdminAuth({ id: 'reader', abilities: ['singletons.site-settings.read'] }),
         });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'No' } })).rejects.toMatchObject({
+        await expect(updateSingleton(harness.ctx, { expectedState: 'empty', data: { title: 'No' } })).rejects.toMatchObject({
             code: 'ERR_FORBIDDEN',
         });
         expect(harness.lockSlot).not.toHaveBeenCalled();
         expect(harness.getMappedDocumentId).not.toHaveBeenCalled();
     });
-    it('enforces expectedVersionId under the locked slot state', async () => {
+    it('requires the observed revision or an explicitly empty slot', async () => {
         const current = createHarness({ mapped: true });
         await expect(updateSingleton(current.ctx, {
             data: { title: 'Yes' },
-            expectedVersionId: 'ver-current',
+            expectedRevision: 1,
         })).resolves.toMatchObject({ documentId: 'doc-1' });
         const stale = createHarness({ mapped: true });
-        await expect(updateSingleton(stale.ctx, { data: { title: 'No' }, expectedVersionId: 'ver-stale' })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+        await expect(updateSingleton(stale.ctx, { data: { title: 'No' }, expectedRevision: 2 })).rejects.toMatchObject({ code: 'ERR_DOCUMENT_STALE' });
         expect(stale.createDocumentVersion).not.toHaveBeenCalled();
         const unmaterialised = createHarness();
         await expect(updateSingleton(unmaterialised.ctx, {
             data: { title: 'No' },
-            expectedVersionId: 'ver-believed-current',
-        })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+            expectedRevision: 1,
+        })).rejects.toMatchObject({ code: 'ERR_NOT_FOUND' });
         expect(unmaterialised.createDocumentVersion).not.toHaveBeenCalled();
     });
     it('rejects a non-default first locale before document or mapping writes', async () => {
         const beforeSave = vi.fn();
         const harness = createHarness({ hooks: { beforeSave } });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'ไทย' }, locale: 'th' })).rejects.toMatchObject({ code: 'ERR_VALIDATION' });
+        await expect(updateSingleton(harness.ctx, { expectedState: 'empty', data: { title: 'ไทย' }, locale: 'th' })).rejects.toMatchObject({ code: 'ERR_VALIDATION' });
         expect(beforeSave).not.toHaveBeenCalled();
         expect(harness.createDocumentVersion).not.toHaveBeenCalled();
         expect(harness.setMapping).not.toHaveBeenCalled();
     });
     it('keeps a soft-deleted document mapped and rejects a replacement save', async () => {
         const harness = createHarness({ mapped: true, softDeleted: true });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'Replacement' } })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+        await expect(updateSingleton(harness.ctx, { expectedRevision: 1, data: { title: 'Replacement' } })).rejects.toMatchObject({ code: 'ERR_NOT_FOUND' });
         expect(harness.mappedDocumentId()).toBe('doc-1');
         expect(harness.createDocumentVersion).not.toHaveBeenCalled();
         expect(harness.setMapping).not.toHaveBeenCalled();
@@ -334,7 +374,15 @@ describe('singleton lifecycle service', () => {
                 },
             },
         });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'Committed' } })).rejects.toThrow('notification failed');
+        await expect(updateSingleton(harness.ctx, { expectedState: 'empty', data: { title: 'Committed' } })).rejects.toMatchObject({
+            code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+            details: {
+                phase: 'afterSave',
+                documentId: 'doc-1',
+                documentVersionId: 'ver-1',
+                sideEffectCode: ErrorCodes.UNHANDLED,
+            },
+        });
         expect(harness.committedTransactions()).toBe(1);
         expect(harness.mappedDocumentId()).toBe('doc-1');
         expect(harness.currentVersion()?.document_version_id).toBe('ver-1');
@@ -348,7 +396,10 @@ describe('singleton lifecycle service', () => {
             document_id: 'doc-1',
             fields: { title: { en: 'Historic', th: 'อดีต' }, count: 1 },
         });
-        await restoreSingletonVersion(harness.ctx, { sourceVersionId: 'ver-source' });
+        await restoreSingletonVersion(harness.ctx, {
+            expectedRevision: 1,
+            sourceVersionId: 'ver-source',
+        });
         const hookShape = expect.objectContaining({
             data: { title: { en: 'Historic', th: 'อดีต' }, count: 1 },
             originalData: { title: { en: 'Current', th: 'ปัจจุบัน' }, count: 2 },
@@ -367,6 +418,7 @@ describe('singleton lifecycle service', () => {
             harness.views.set('en', { fields: { title: 'Source', count: 1 } });
             harness.views.set('th', { fields: { title: 'Target', count: 1 } });
             await copySingletonToLocale(harness.ctx, {
+                expectedRevision: 1,
                 sourceLocale: 'en',
                 targetLocale: 'th',
                 overwrite,

package/dist/storage/db-adapter.test-helper.d.ts

@@ -0,0 +1,26 @@
+import type { IDbAdapter } from '../@types/db-types.js';
+/** Unit fixture only: unused capabilities throw, including transactions and snapshots.
+ * Tests must explicitly implement every operation they exercise. Live adapter tests
+ * supply the transaction/rollback evidence; this helper cannot simulate it. */
+type Overrides = Partial<Omit<IDbAdapter, 'commands' | 'queries' | 'revisions'>> & {
+    revisions?: Partial<IDbAdapter['revisions']>;
+    commands?: {
+        collections?: Partial<IDbAdapter['commands']['collections']>;
+        documents?: Partial<Omit<IDbAdapter['commands']['documents'], 'publishSchedules'>> & {
+            publishSchedules?: Partial<IDbAdapter['commands']['documents']['publishSchedules']>;
+        };
+        counters?: Partial<IDbAdapter['commands']['counters']>;
+        audit?: Partial<IDbAdapter['commands']['audit']>;
+        singletons?: Partial<IDbAdapter['commands']['singletons']>;
+    };
+    queries?: {
+        collections?: Partial<IDbAdapter['queries']['collections']>;
+        documents?: Partial<Omit<IDbAdapter['queries']['documents'], 'publishSchedules'>> & {
+            publishSchedules?: Partial<IDbAdapter['queries']['documents']['publishSchedules']>;
+        };
+        audit?: Partial<IDbAdapter['queries']['audit']>;
+        singletons?: Partial<IDbAdapter['queries']['singletons']>;
+    };
+};
+export declare function testAdapter(overrides?: Overrides): IDbAdapter;
+export {};

package/dist/storage/db-adapter.test-helper.js

@@ -0,0 +1,117 @@
+export function testAdapter(overrides = {}) {
+    const unused = () => {
+        throw new Error('Unexpected adapter operation in unit fixture');
+    };
+    return {
+        withTransaction: unused,
+        withReadSnapshot: unused,
+        ...overrides,
+        revisions: {
+            readStructure: unused,
+            assertCompatibleSchema: unused,
+            isInTransaction: () => false,
+            lock: unused,
+            advance: unused,
+            ...overrides.revisions,
+        },
+        commands: {
+            collections: {
+                lockCollectionRegistration: unused,
+                create: unused,
+                update: unused,
+                delete: unused,
+                ...overrides.commands?.collections,
+            },
+            documents: {
+                createDocumentVersion: unused,
+                updateDocumentPath: unused,
+                setDocumentAvailableLocales: unused,
+                setDocumentStatus: unused,
+                archivePublishedVersions: unused,
+                softDeleteDocument: unused,
+                restoreSoftDeletedDocument: unused,
+                deleteDocumentLocale: unused,
+                setOrderKey: unused,
+                placeTreeNode: unused,
+                removeFromTree: unused,
+                promoteChildrenAndRemoveFromTree: unused,
+                ...overrides.commands?.documents,
+                publishSchedules: {
+                    lockDocuments: unused,
+                    schedule: unused,
+                    confirm: unused,
+                    cancel: unused,
+                    suspendForContentEdit: unused,
+                    claimDue: unused,
+                    lockClaim: unused,
+                    deleteClaim: unused,
+                    suspendClaimForContentEdit: unused,
+                    releaseClaim: unused,
+                    ...overrides.commands?.documents?.publishSchedules,
+                },
+            },
+            counters: {
+                ensureCounterGroup: unused,
+                nextCounterValue: unused,
+                nextScopedCounterValue: unused,
+                ...overrides.commands?.counters,
+            },
+            audit: {
+                append: unused,
+                ...overrides.commands?.audit,
+            },
+            singletons: {
+                lockSlot: unused,
+                setMapping: unused,
+                clearMapping: unused,
+                ...overrides.commands?.singletons,
+            },
+        },
+        queries: {
+            collections: {
+                getAllCollections: unused,
+                getCollectionByPath: unused,
+                getCollectionById: unused,
+                ...overrides.queries?.collections,
+            },
+            documents: {
+                getDocumentRevision: unused,
+                getDocumentSystemFieldsForUpdate: unused,
+                getDocumentById: unused,
+                getCurrentVersionMetadata: unused,
+                getCurrentPath: unused,
+                getDocumentByPath: unused,
+                getDocumentByVersion: unused,
+                getDocumentsByVersionIds: unused,
+                getDocumentsByDocumentIds: unused,
+                getDocumentHistory: unused,
+                getPublishedVersion: unused,
+                getPublishedDocumentIds: unused,
+                getDocumentCountsByStatus: unused,
+                findDocuments: unused,
+                getLastOrderKey: unused,
+                getNeighborOrderKeys: unused,
+                getCanonicalDocumentOrder: unused,
+                getTreeAncestors: unused,
+                getTreeChildren: unused,
+                getTreeParent: unused,
+                getTreeSubtree: unused,
+                ...overrides.queries?.documents,
+                publishSchedules: {
+                    get: unused,
+                    list: unused,
+                    ...overrides.queries?.documents?.publishSchedules,
+                },
+            },
+            audit: {
+                getDocumentAuditLog: unused,
+                findAuditLog: unused,
+                ...overrides.queries?.audit,
+            },
+            singletons: {
+                getMappedDocumentId: unused,
+                ...overrides.queries?.singletons,
+            },
+        },
+    };
+}

package/dist/storage/document-revision-capability.d.ts

@@ -0,0 +1,3 @@
+import type { IDbAdapter } from '../@types/db-types.js';
+/** Must run before collection reconciliation, counters, or boot maintenance writes. */
+export declare function assertDocumentRevisionCapability(db: IDbAdapter): Promise<void>;