@byline/core 4.19.0 → 5.1.0

package/dist/scheduler/scheduled-publication.js

@@ -9,6 +9,7 @@ import { createSuperAdminContext } from '@byline/auth';
 import { AUDIT_ACTIONS, requireAuditCapability } from '../services/document-lifecycle/audit.js';
 import { publishScheduleAuditValue } from '../services/document-lifecycle/publish-schedule-consistency.js';
 import { publishClaimedScheduledDocument } from '../services/document-lifecycle/scheduled-publish.js';
+import { documentRevisionFromDatabase } from '../storage/document-revision.js';
 import { SCHEDULED_PUBLICATION_LEASE_MS } from './scheduled-publication-constants.js';
 const DEFAULT_BATCH_SIZE = 25;
 const DEFAULT_BUDGET_MS = 45_000;
@@ -50,6 +51,28 @@ function buildSystemContext(core, claim, logger) {
 async function finalizeClaim(params) {
     const audit = requireAuditCapability(params.core.db);
     return audit.withTransaction(async () => {
+        const db = params.core.db;
+        const definition = resolveCollection(params.core, params.claim.collectionId)?.definition;
+        await db.commands.collections.lockCollectionRegistration(params.claim.collectionId, definition?.tree || definition?.singleton ? 'exclusive' : 'shared');
+        const observed = await db.withReadSnapshot(async (queries) => ({
+            current: await queries.documents.getCurrentVersionMetadata({
+                collection_id: params.claim.collectionId,
+                document_id: params.claim.documentId,
+            }),
+            revision: await queries.documents.getDocumentRevision({
+                collection_id: params.claim.collectionId,
+                document_id: params.claim.documentId,
+            }),
+        }));
+        const [document] = observed.current === null
+            ? []
+            : await db.revisions.lock([
+                {
+                    documentId: params.claim.documentId,
+                    collectionId: params.claim.collectionId,
+                    expectedRevision: documentRevisionFromDatabase(observed.revision),
+                },
+            ]);
         const locked = await params.core.db.commands.documents.publishSchedules.lockClaim({
             documentId: params.claim.documentId,
             executionToken: params.claim.executionToken,
@@ -60,6 +83,7 @@ async function finalizeClaim(params) {
             ? await params.core.db.commands.documents.publishSchedules.suspendClaimForContentEdit({
                 documentId: params.claim.documentId,
                 executionToken: params.claim.executionToken,
+                reason: params.reason === 'content_edited' ? 'content_edited' : 'document_metadata_changed',
             })
             : await params.core.db.commands.documents.publishSchedules.deleteClaim({
                 documentId: params.claim.documentId,
@@ -80,6 +104,8 @@ async function finalizeClaim(params) {
                 ? { state: 'needs_reconfirm', reason: params.reason }
                 : { reason: params.reason },
         });
+        if (document)
+            await db.revisions.advance(document);
         return true;
     });
 }
@@ -109,7 +135,7 @@ async function processClaim(params) {
                 core: params.core,
                 claim: params.claim,
                 outcome: 'suspend',
-                reason: 'content_edited',
+                reason: result.reason,
             });
             return 'handled';
         }

package/dist/scheduler/scheduled-publication.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/scheduler/scheduled-publication.test.node.js

@@ -1,3 +1,5 @@
+import { testAdapter } from '../storage/db-adapter.test-helper.js';
+import { runReadSnapshot } from '../storage/read-snapshot.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
@@ -21,7 +23,7 @@ function emptyCore() {
     const claimDue = vi.fn().mockResolvedValue([]);
     return {
         core: {
-            db: { commands: { documents: { publishSchedules: { claimDue } } } },
+            db: testAdapter({ commands: { documents: { publishSchedules: { claimDue } } } }),
             logger,
         },
         claimDue,
@@ -33,6 +35,7 @@ function claim(documentId) {
         documentId,
         collectionId: 'unregistered-collection',
         targetVersionId: `version-${documentId}`,
+        authorizedRevision: 1,
         publishAt: now,
         state: 'armed',
         suspendedAt: null,
@@ -91,15 +94,27 @@ describe('runScheduledPublicationSweep', () => {
         const core = {
             collections: [],
             collectionRecords: new Map(),
-            db: {
+            db: testAdapter({
+                withReadSnapshot: async (fn) => {
+                    const db = testAdapter({
+                        queries: {
+                            documents: {
+                                getCurrentVersionMetadata: async () => null,
+                                getDocumentRevision: async () => 1,
+                            },
+                        },
+                    });
+                    return runReadSnapshot(db.queries, fn);
+                },
                 withTransaction: async (fn) => fn(),
                 commands: {
+                    collections: { lockCollectionRegistration: vi.fn(async () => { }) },
                     audit: { append: vi.fn().mockResolvedValue({ id: 'audit-1' }) },
                     documents: {
                         publishSchedules: { claimDue, lockClaim, deleteClaim, releaseClaim },
                     },
                 },
-            },
+            }),
             logger,
         };
         await expect(runScheduledPublicationSweep(core, { batchSize: 10, budgetMs: 5_000 })).resolves.toEqual({ published: 0, failed: 1, workRemaining: false });

package/dist/scheduler/scheduler-boot.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/scheduler/scheduler-boot.test.node.js

@@ -1,12 +1,7 @@
-/**
- * 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
- */
+import { testAdapter } from '../storage/db-adapter.test-helper.js';
 import { describe, expect, it } from 'vitest';
 import { initBylineCore } from '../core.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { defineRecurringTask } from './define-recurring-task.js';
 // Boot-level coverage for the scheduler wiring inside `initBylineCore()`,
 // complementing the pure-function coverage in `validate-scheduler-config.test.node.ts`.
@@ -31,16 +26,41 @@ const task = defineRecurringTask({
     run: async () => { },
 });
 describe('initBylineCore scheduler wiring', () => {
+    it('rejects missing password-sign-in cleanup registration before database initialization', async () => {
+        const config = serverConfig(testAdapter({}));
+        config.passwordSignIn = {
+            resolveClientIp: () => '192.0.2.1',
+            limiter: {
+                requiredCleanupTask: 'auth.sign-in-counters.cleanup',
+                acquire: async () => () => { },
+                consume: async () => ({ allowed: true, retryAfterSeconds: 0 }),
+            },
+        };
+        await expect(initBylineCore(config, {})).rejects.toThrow(/Register the limiter's cleanupTask/);
+        config.recurringTasks = [{ ...task, name: 'auth.sign-in-counters.cleanup' }];
+        await expect(initBylineCore(config, {})).rejects.toThrow(/scheduler capability/);
+    });
     it('rejects recurring tasks registered against an adapter without the scheduler capability', async () => {
-        const config = serverConfig({});
+        const config = serverConfig(testAdapter({}));
         config.recurringTasks = [task];
         await expect(initBylineCore(config, {})).rejects.toThrow(/analytics\.rollup/);
     });
     it('gates scheduled publication on the scheduler capability and contributes its built-in task', async () => {
-        const unsupported = serverConfig({});
+        const unsupported = serverConfig(testAdapter({}));
         unsupported.scheduledPublication = { enabled: true };
         await expect(initBylineCore(unsupported, {})).rejects.toThrow(/documents\.publish-scheduled/);
-        const capable = serverConfig({ scheduler: {} });
+        const capable = serverConfig(testAdapter({
+            scheduler: {},
+            withTransaction: async (fn) => fn(),
+            withReadSnapshot: async () => {
+                throw new Error('Unexpected editable read');
+            },
+            commands: {
+                collections: { lockCollectionRegistration: async () => { } },
+                documents: { publishSchedules: { lockDocuments: async () => { } } },
+            },
+            revisions: { ...unusedRevisionStore, assertCompatibleSchema: async () => { } },
+        }));
         capable.scheduledPublication = { enabled: true };
         capable.recurringTasks = [task];
         const core = await initBylineCore(capable, {});
@@ -54,7 +74,18 @@ describe('initBylineCore scheduler wiring', () => {
         });
     });
     it('populates core.recurringTasks with the registered set when the adapter is capable', async () => {
-        const db = { scheduler: {} };
+        const db = testAdapter({
+            scheduler: {},
+            withTransaction: async (fn) => fn(),
+            withReadSnapshot: async () => {
+                throw new Error('Unexpected editable read');
+            },
+            commands: {
+                collections: { lockCollectionRegistration: async () => { } },
+                documents: { publishSchedules: { lockDocuments: async () => { } } },
+            },
+            revisions: { ...unusedRevisionStore, assertCompatibleSchema: async () => { } },
+        });
         const config = serverConfig(db);
         config.recurringTasks = [task];
         const core = await initBylineCore(config, {});
@@ -63,7 +94,18 @@ describe('initBylineCore scheduler wiring', () => {
         expect(registered).toMatchObject({ name: 'analytics.rollup', intervalMs: 3_600_000 });
     });
     it('freezes the validated snapshot so post-init mutation of the caller input cannot alter it', async () => {
-        const db = { scheduler: {} };
+        const db = testAdapter({
+            scheduler: {},
+            withTransaction: async (fn) => fn(),
+            withReadSnapshot: async () => {
+                throw new Error('Unexpected editable read');
+            },
+            commands: {
+                collections: { lockCollectionRegistration: async () => { } },
+                documents: { publishSchedules: { lockDocuments: async () => { } } },
+            },
+            revisions: { ...unusedRevisionStore, assertCompatibleSchema: async () => { } },
+        });
         const localTask = defineRecurringTask({
             name: 'analytics.local',
             intervalMs: 3_600_000,

package/dist/scheduler/ticker.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/scheduler/ticker.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
@@ -229,7 +230,7 @@ describe('startBylineScheduler', () => {
         const injectedRun = vi.fn(async () => { });
         const store = fakeStore({ claim: vi.fn(async ({ name }) => claimed(name)) });
         const core = {
-            db: { scheduler: store },
+            db: testAdapter({ scheduler: store }),
             recurringTasks: [task('core-task', coreRun)],
             logger: silentLogger,
         };
@@ -242,7 +243,7 @@ describe('startBylineScheduler', () => {
         expect(coreRun).toHaveBeenCalledTimes(1);
         expect(injectedRun).not.toHaveBeenCalled();
         await controller.stop();
-        expect(() => startBylineScheduler({ ...core, db: {} }, {
+        expect(() => startBylineScheduler({ ...core, db: testAdapter() }, {
             startupJitterMs: 0,
         })).toThrow(/scheduler capability/i);
     });

package/dist/scheduler/validate-scheduler-config.d.ts

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { PasswordSignInProtection } from '@byline/auth';
 import type { ISchedulerStore, RecurringTaskDefinition } from './types.js';
 /**
  * Boot-time gate. Recurring tasks registered against an adapter that does not
@@ -12,6 +13,7 @@ import type { ISchedulerStore, RecurringTaskDefinition } from './types.js';
  * fails loudly at `initBylineCore()` instead.
  */
 export declare function validateSchedulerConfig(params: {
+    passwordSignIn?: PasswordSignInProtection;
     tasks?: readonly RecurringTaskDefinition[];
     adapter: {
         scheduler?: ISchedulerStore;

package/dist/scheduler/validate-scheduler-config.js

@@ -13,6 +13,11 @@ import { validateRecurringTasks } from './validate-tasks.js';
  */
 export function validateSchedulerConfig(params) {
     const tasks = params.tasks ?? [];
+    const cleanup = params.passwordSignIn?.limiter.requiredCleanupTask;
+    if (cleanup && !tasks.some((task) => task.name === cleanup)) {
+        throw new Error(`Password sign-in requires recurring task "${cleanup}". Register the limiter's cleanupTask ` +
+            'in recurringTasks and start the host scheduler (or invoke runDueTasks externally).');
+    }
     if (tasks.length === 0)
         return;
     validateRecurringTasks(tasks);

package/dist/scheduler/validate-scheduler-config.test.node.js

@@ -16,6 +16,22 @@ const task = defineRecurringTask({
 });
 const store = {};
 describe('validateSchedulerConfig', () => {
+    it('accepts matching cleanup registration and permits self-expiring custom limiters', () => {
+        const passwordSignIn = {
+            resolveClientIp: () => '192.0.2.1',
+            limiter: {
+                requiredCleanupTask: task.name,
+                acquire: async () => () => { },
+                consume: async () => ({ allowed: true, retryAfterSeconds: 0 }),
+            },
+        };
+        expect(() => validateSchedulerConfig({ passwordSignIn, tasks: [task], adapter: { scheduler: store } })).not.toThrow();
+        const { requiredCleanupTask: _, ...ttlLimiter } = passwordSignIn.limiter;
+        expect(() => validateSchedulerConfig({
+            passwordSignIn: { ...passwordSignIn, limiter: ttlLimiter },
+            adapter: {},
+        })).not.toThrow();
+    });
     it('passes when tasks are registered against a scheduler-capable adapter', () => {
         expect(() => validateSchedulerConfig({ tasks: [task], adapter: { scheduler: store } })).not.toThrow();
     });

package/dist/services/collection-bootstrap.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/collection-bootstrap.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,6 +8,7 @@
  */
 import { describe, expect, it, vi } from 'vitest';
 import { fingerprintCollection } from '../storage/collection-fingerprint.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { ensureCollections } from './collection-bootstrap.js';
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -37,10 +39,14 @@ function createMockDb(options) {
         ? vi.fn(fail)
         : vi.fn().mockResolvedValue([{ id: options.existingRow?.id ?? 'col-new' }]);
     const db = {
+        revisions: unusedRevisionStore,
+        withReadSnapshot: async () => {
+            throw new Error('Unexpected editable snapshot in this test');
+        },
         commands: {
-            collections: { create, update, delete: vi.fn(fail) },
+            collections: { lockCollectionRegistration: vi.fn(fail), create, update, delete: vi.fn(fail) },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().commands.documents.publishSchedules,
                 createDocumentVersion: vi.fn(fail),
                 updateDocumentPath: vi.fn(fail),
                 setDocumentAvailableLocales: vi.fn(fail),
@@ -82,7 +88,10 @@ function createMockDb(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().queries.documents.publishSchedules,
+                getDocumentRevision: async () => {
+                    throw new Error('Unexpected revision read in this test');
+                },
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),

package/dist/services/discover-counter-groups.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/discover-counter-groups.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
@@ -6,6 +7,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it, vi } from 'vitest';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { discoverCounterGroups } from './discover-counter-groups.js';
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -20,10 +22,21 @@ function makeAdapter(options) {
         throw new Error('unexpected call');
     };
     const db = {
+        revisions: unusedRevisionStore,
+        withReadSnapshot: async () => {
+            throw new Error('Unexpected editable snapshot in this test');
+        },
         commands: {
-            collections: { create: vi.fn(fail), update: vi.fn(fail), delete: vi.fn(fail) },
+            collections: {
+                lockCollectionRegistration: vi.fn(async () => {
+                    throw new Error('Unexpected collection lock');
+                }),
+                create: vi.fn(fail),
+                update: vi.fn(fail),
+                delete: vi.fn(fail),
+            },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().commands.documents.publishSchedules,
                 createDocumentVersion: vi.fn(fail),
                 updateDocumentPath: vi.fn(fail),
                 setDocumentAvailableLocales: vi.fn(fail),
@@ -65,7 +78,10 @@ function makeAdapter(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().queries.documents.publishSchedules,
+                getDocumentRevision: async () => {
+                    throw new Error('Unexpected revision read in this test');
+                },
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),

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

@@ -10,6 +10,7 @@ import type { DocumentLifecycleContext } from './context.js';
 /** Namespaced audit actions for document-grain changes. */
 export declare const AUDIT_ACTIONS: {
     readonly pathChanged: 'document.path.changed';
+    readonly orderChanged: 'document.order.changed';
     readonly localesChanged: 'document.locales.changed';
     readonly statusChanged: 'document.status.changed';
     readonly publishScheduled: 'document.publish.scheduled';

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

@@ -19,6 +19,7 @@ import { actorId } from './internals.js';
 /** Namespaced audit actions for document-grain changes. */
 export const AUDIT_ACTIONS = {
     pathChanged: 'document.path.changed',
+    orderChanged: 'document.order.changed',
     localesChanged: 'document.locales.changed',
     statusChanged: 'document.status.changed',
     publishScheduled: 'document.publish.scheduled',

package/dist/services/document-lifecycle/committed-hook.d.ts

@@ -7,12 +7,13 @@
  */
 import { ErrorCodes } from '../../lib/errors.js';
 import type { DocumentLifecycleContext } from './context.js';
-export type DocumentHookCommittedPhase = 'afterCreate' | 'afterUpdate' | 'afterSave';
+export type DocumentHookCommittedPhase = 'afterCreate' | 'afterUpdate' | 'afterSave' | 'afterSystemFieldsChange' | 'afterStatusChange' | 'afterUnpublish';
 export type DocumentHookSideEffectCode = typeof ErrorCodes.STORAGE | typeof ErrorCodes.UNHANDLED;
 export interface DocumentHookCommittedDetails {
     phase: DocumentHookCommittedPhase;
     documentId: string;
     documentVersionId: string;
+    revision: number;
     sideEffectCode: DocumentHookSideEffectCode;
 }
 /** Read and validate the public, non-sensitive metadata from a committed hook failure. */

package/dist/services/document-lifecycle/committed-hook.js

@@ -40,9 +40,25 @@ export function getDocumentHookCommittedDetails(error) {
     const documentId = readStringProperty(details, 'documentId');
     const documentVersionId = readStringProperty(details, 'documentVersionId');
     const failureCode = readStringProperty(details, 'sideEffectCode');
-    if (phase !== 'afterCreate' && phase !== 'afterUpdate' && phase !== 'afterSave')
+    if (phase !== 'afterCreate' &&
+        phase !== 'afterUpdate' &&
+        phase !== 'afterSave' &&
+        phase !== 'afterSystemFieldsChange' &&
+        phase !== 'afterStatusChange' &&
+        phase !== 'afterUnpublish')
         return null;
-    if (!documentId || !documentVersionId)
+    if (!documentId ||
+        (phase !== 'afterSystemFieldsChange' && !documentVersionId) ||
+        documentVersionId === undefined)
+        return null;
+    let revision;
+    try {
+        revision = Reflect.get(details, 'revision');
+    }
+    catch {
+        return null;
+    }
+    if (typeof revision !== 'number' || !Number.isSafeInteger(revision) || revision < 1)
         return null;
     if (failureCode !== ErrorCodes.STORAGE && failureCode !== ErrorCodes.UNHANDLED)
         return null;
@@ -51,6 +67,7 @@ export function getDocumentHookCommittedDetails(error) {
         documentId,
         documentVersionId,
         sideEffectCode: failureCode,
+        revision,
     };
 }
 /**

package/dist/services/document-lifecycle/copy-to-locale.d.ts

@@ -7,6 +7,7 @@
  */
 import type { DocumentLifecycleContext } from './context.js';
 export interface CopyToLocaleResult {
+    revision: number;
     documentId: string;
     documentVersionId: string;
     /** Source locale read for the copy. */
@@ -56,6 +57,7 @@ export interface CopyToLocaleResult {
  */
 export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     sourceLocale: string;
     targetLocale: string;
     overwrite: boolean;

package/dist/services/document-lifecycle/copy-to-locale.js

@@ -7,13 +7,15 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
 import { persistExistingDocumentVersion } from './persistence.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
+import { sameDocumentData } from './same-document-data.js';
 /**
  * Copy a document's content from one locale into another, in place on
  * the same document.
@@ -47,6 +49,7 @@ import { persistExistingDocumentVersion } from './persistence.js';
  *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
  */
 export async function copyToLocale(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'copyToLocale' }, async () => {
         const { db, definition, collectionId, collectionPath } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'update');
@@ -61,48 +64,22 @@ export async function copyToLocale(ctx, params) {
             }).log(ctx.logger);
         }
         // 1. Source read.
-        const source = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
+        const source = await readDocumentForMutation(ctx, {
+            ...params,
             locale: params.sourceLocale,
-            reconstruct: true,
             lenient: true,
-            requestContext: ctx.requestContext,
         });
-        if (source == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found in source locale',
-                details: {
-                    documentId: params.documentId,
-                    sourceLocale: params.sourceLocale,
-                    collectionPath,
-                },
-            }).log(ctx.logger);
-        }
-        // 2. Target read — needed for both originalData (hooks) and to
-        //    preserve non-localized values + structural shape.
-        const target = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
+        const target = await readDocumentForMutation(ctx, {
+            ...params,
             locale: params.targetLocale,
-            reconstruct: true,
             lenient: true,
-            requestContext: ctx.requestContext,
         });
-        if (target == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found in target locale',
-                details: {
-                    documentId: params.documentId,
-                    targetLocale: params.targetLocale,
-                    collectionPath,
-                },
-            }).log(ctx.logger);
-        }
+        const previousVersionId = target.document_version_id;
         const sourceRecord = source;
         const targetRecord = target;
         const sourceFields = sourceRecord.fields ?? {};
         const targetFields = targetRecord.fields ?? {};
+        const baseline = structuredClone(targetFields);
         // 3. Merge.
         const merged = mergeLocaleData(definition.fields, sourceFields, targetFields, params.overwrite);
         // 4. Hooks see the target-locale view as originalData (consistent
@@ -123,18 +100,25 @@ export async function copyToLocale(ctx, params) {
         //    storage primitive's cross-locale carry-forward fires for every
         //    *other* locale (not source, not target — those rows are
         //    rewritten by this call).
-        const previousVersionId = targetRecord.document_version_id ?? undefined;
         await applyRichTextEmbed(ctx, merged.data);
-        const writeResult = await persistExistingDocumentVersion(ctx, {
-            documentId: params.documentId,
-            action: 'copy_to_locale',
-            documentData: merged.data,
-            status: getDefaultStatus(definition),
-            locale: params.targetLocale,
-            previousVersionId,
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId, locale: params.targetLocale }, async () => {
+            if ((targetRecord._availableVersionLocales?.includes(params.targetLocale) ||
+                targetRecord._localeAgnostic === true) &&
+                sameDocumentData(merged.data, baseline))
+                return { value: previousVersionId, changed: false };
+            const writeResult = await persistExistingDocumentVersion(ctx, {
+                documentId: params.documentId,
+                action: 'copy_to_locale',
+                documentData: merged.data,
+                status: getDefaultStatus(definition),
+                locale: params.targetLocale,
+                previousVersionId,
+            });
+            return { value: extractVersionId(writeResult.document), changed: true };
         });
-        const documentVersionId = extractVersionId(writeResult.document);
-        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId: params.documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
+        const documentVersionId = committed.value;
+        const revision = committed.revision;
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId: params.documentId, documentVersionId, revision }, () => invokeHook(hooks?.afterUpdate, {
             data: merged.data,
             originalData: targetFields,
             collectionPath,
@@ -151,6 +135,7 @@ export async function copyToLocale(ctx, params) {
             sourceLocale: params.sourceLocale,
             targetLocale: params.targetLocale,
             fieldsUpdated: merged.fieldsUpdated,
+            revision,
         };
     });
 }

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

@@ -7,6 +7,7 @@
  */
 import type { DocumentLifecycleContext } from './context.js';
 export interface CreateDocumentResult {
+    revision: number;
     documentId: string;
     documentVersionId: string;
 }