@byline/core 4.18.0 → 5.0.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`.
@@ -32,15 +27,26 @@ const task = defineRecurringTask({
 });
 describe('initBylineCore scheduler wiring', () => {
     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 +60,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 +80,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/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

@@ -0,0 +1,25 @@
+/**
+ * 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 { ErrorCodes } from '../../lib/errors.js';
+import type { DocumentLifecycleContext } from './context.js';
+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. */
+export declare function getDocumentHookCommittedDetails(error: unknown): DocumentHookCommittedDetails | null;
+/**
+ * Run a hook after its document version has committed, preserving rejection
+ * semantics while making the committed state machine-readable to hosts.
+ */
+export declare function runCommittedDocumentHook(ctx: DocumentLifecycleContext, details: Omit<DocumentHookCommittedDetails, 'sideEffectCode'>, callback: () => Promise<void>): Promise<void>;

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

@@ -0,0 +1,96 @@
+/**
+ * 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 { DOCUMENT_HOOK_COMMITTED_MARKER, ERR_DOCUMENT_HOOK_COMMITTED, ErrorCodes, } from '../../lib/errors.js';
+function readStringProperty(value, key) {
+    try {
+        if ((typeof value !== 'object' || value === null) && typeof value !== 'function') {
+            return undefined;
+        }
+        const property = Reflect.get(value, key);
+        return typeof property === 'string' ? property : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sideEffectCode(error) {
+    return readStringProperty(error, 'code') === ErrorCodes.STORAGE
+        ? ErrorCodes.STORAGE
+        : ErrorCodes.UNHANDLED;
+}
+/** Read and validate the public, non-sensitive metadata from a committed hook failure. */
+export function getDocumentHookCommittedDetails(error) {
+    if (readStringProperty(error, 'code') !== ErrorCodes.DOCUMENT_HOOK_COMMITTED)
+        return null;
+    let details;
+    try {
+        details = Reflect.get(error, 'details');
+    }
+    catch {
+        return null;
+    }
+    if (typeof details !== 'object' || details === null)
+        return null;
+    const phase = readStringProperty(details, 'phase');
+    const documentId = readStringProperty(details, 'documentId');
+    const documentVersionId = readStringProperty(details, 'documentVersionId');
+    const failureCode = readStringProperty(details, 'sideEffectCode');
+    if (phase !== 'afterCreate' &&
+        phase !== 'afterUpdate' &&
+        phase !== 'afterSave' &&
+        phase !== 'afterSystemFieldsChange' &&
+        phase !== 'afterStatusChange' &&
+        phase !== 'afterUnpublish')
+        return null;
+    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;
+    return {
+        phase,
+        documentId,
+        documentVersionId,
+        sideEffectCode: failureCode,
+        revision,
+    };
+}
+/**
+ * Run a hook after its document version has committed, preserving rejection
+ * semantics while making the committed state machine-readable to hosts.
+ */
+export async function runCommittedDocumentHook(ctx, details, callback) {
+    try {
+        await callback();
+    }
+    catch (cause) {
+        const committedError = ERR_DOCUMENT_HOOK_COMMITTED({
+            message: `${DOCUMENT_HOOK_COMMITTED_MARKER} document write committed but ${details.phase} failed`,
+            cause,
+            captureStack: true,
+            details: { ...details, sideEffectCode: sideEffectCode(cause) },
+        });
+        try {
+            committedError.log(ctx.logger);
+        }
+        catch {
+            // Diagnostic logging cannot erase the machine-readable committed result.
+        }
+        throw committedError;
+    }
+}

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,12 +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.
@@ -46,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');
@@ -60,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
@@ -122,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 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,
@@ -143,13 +128,14 @@ export async function copyToLocale(ctx, params) {
             // touches it. Read it off the target envelope.
             path: targetRecord.path ?? '',
             copyToLocale: copyToLocaleMarker,
-        });
+        }));
         return {
             documentId: params.documentId,
             documentVersionId,
             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;
 }