@byline/core 4.18.0 → 5.0.0

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

@@ -15,9 +15,10 @@ import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { requireTreeAuditCapability } from './audit.js';
+import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 import { persistInitialDocumentVersion } from './persistence.js';
-import { appendTreeRoot } from './tree.js';
+import { assertLifecycleTransactionOwnership } from './revision-guard.js';
 /**
  * Create a new document.
  *
@@ -36,6 +37,7 @@ export async function createDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'createDocument' }, async () => {
         const { db, definition, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'create');
+        assertLifecycleTransactionOwnership(ctx);
         // Reject unsupported tree adapters before hooks, counters, or persistence
         // can create a document that cannot be placed and audited safely.
         if (definition.tree === true)
@@ -84,30 +86,13 @@ export async function createDocument(ctx, params) {
         }).catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale, 'create'));
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
-        // `tree: true` collections place every document in the tree by default:
-        // a new document is appended as a root (a top-level nav entry) so it is
-        // never stranded in the "unplaced" limbo. This is a system step of create
-        // (the actor already passed the `create` ability), so it uses the internal
-        // placement primitive without an `update` re-assertion or separate tree
-        // event (afterCreate covers invalidation). Placement + audit are atomic.
-        // Post-version and best-effort: a runtime audit/storage failure leaves the
-        // document created-but-unplaced and is logged. Missing capability was
-        // rejected before persistence above.
-        if (definition.tree === true) {
-            try {
-                await appendTreeRoot(ctx, documentId);
-            }
-            catch (err) {
-                ctx.logger.error({ err, documentId }, 'failed to auto-place new document in tree');
-            }
-        }
-        await invokeHook(hooks?.afterCreate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterCreate', documentId, documentVersionId, revision: 1 }, () => invokeHook(hooks?.afterCreate, {
             data,
             collectionPath,
             documentId,
             documentVersionId,
             path: resolvedPath,
-        });
-        return { documentId, documentVersionId };
+        }));
+        return { documentId, documentVersionId, revision: 1 };
     });
 }

package/dist/services/document-lifecycle/delete-locale.d.ts

@@ -7,6 +7,7 @@
  */
 import type { DocumentLifecycleContext } from './context.js';
 export interface DeleteLocaleResult {
+    revision: number;
     documentId: string;
     /** The newly-created version that omits the deleted locale's content. */
     documentVersionId: string;
@@ -19,7 +20,7 @@ export interface DeleteLocaleResult {
  * store rows (every other locale and all non-localized `'all'` rows are
  * carried forward by the storage primitive).
  *
- * The default content locale is the document's anchor (path + source_locale)
+ * The document's source content locale is its anchor (path + source_locale)
  * and can never be removed — rejected up front. The new version lands as the
  * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
  * previously-published version keeps serving — including the locale being
@@ -29,7 +30,7 @@ export interface DeleteLocaleResult {
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
- *   2. Reject `locale === defaultLocale`.
+ *   2. Reject deletion of the document’s source locale.
  *   3. Read the document in the target locale (validates existence; supplies
  *      `originalData` for hooks and the availability set for the presence
  *      check).
@@ -40,5 +41,6 @@ export interface DeleteLocaleResult {
  */
 export declare function deleteLocale(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     locale: string;
 }): Promise<DeleteLocaleResult>;

package/dist/services/document-lifecycle/delete-locale.js

@@ -10,15 +10,17 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, 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 { actorId, invokeHook } from './internals.js';
 import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 /**
  * Remove one content locale's data from a document, in place on the same
  * document, by writing a new immutable version that omits that locale's
  * store rows (every other locale and all non-localized `'all'` rows are
  * carried forward by the storage primitive).
  *
- * The default content locale is the document's anchor (path + source_locale)
+ * The document's source content locale is its anchor (path + source_locale)
  * and can never be removed — rejected up front. The new version lands as the
  * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
  * previously-published version keeps serving — including the locale being
@@ -28,7 +30,7 @@ import { commitContentVersionWithScheduleSuspension } from './publish-schedule-c
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
- *   2. Reject `locale === defaultLocale`.
+ *   2. Reject deletion of the document’s source locale.
  *   3. Read the document in the target locale (validates existence; supplies
  *      `originalData` for hooks and the availability set for the presence
  *      check).
@@ -38,34 +40,24 @@ import { commitContentVersionWithScheduleSuspension } from './publish-schedule-c
  *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
  */
 export async function deleteLocale(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'update');
-        // The default locale anchors the document's path and source_locale —
+        const target = await readDocumentForMutation(ctx, { ...params, lenient: true });
+        const previousVersionId = target.document_version_id;
+        // The document's source locale anchors its path and fallback reads —
         // it cannot be deleted (the other locales fall back to it).
-        if (params.locale === defaultLocale) {
+        const sourceLocale = target.source_locale ?? defaultLocale;
+        if (params.locale === sourceLocale) {
             throw ERR_VALIDATION({
-                message: `cannot delete the default content locale ('${defaultLocale}')`,
+                message: `cannot delete the source content locale ('${sourceLocale}')`,
                 details: { documentId: params.documentId, locale: params.locale, collectionPath },
             }).log(ctx.logger);
         }
         // Read the document in the locale being removed — validates existence,
         // supplies originalData for hooks, and the availability set for the
         // content-presence check below.
-        const target = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale,
-            reconstruct: true,
-            lenient: true,
-            requestContext: ctx.requestContext,
-        });
-        if (target == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId, collectionPath },
-            }).log(ctx.logger);
-        }
         const targetRecord = target;
         // `_availableVersionLocales` is the derived (path-coverage) set; it is
         // the same source the editor's Delete-Locale picker is built from, so a
@@ -87,26 +79,36 @@ export async function deleteLocale(ctx, params) {
             collectionPath,
             deleteLocale: deleteLocaleMarker,
         });
-        const result = await commitContentVersionWithScheduleSuspension({
-            ctx,
-            documentId: params.documentId,
-            write: async () => {
-                const deleted = await db.commands.documents.deleteDocumentLocale({
-                    documentId: params.documentId,
-                    locale: params.locale,
-                    status: getDefaultStatus(definition),
-                    createdBy: actorId(ctx),
-                });
-                if (deleted == null) {
-                    throw ERR_NOT_FOUND({
-                        message: 'document not found',
-                        details: { documentId: params.documentId, collectionPath },
-                    }).log(ctx.logger);
-                }
-                return deleted;
-            },
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId }, async () => {
+            const result = await commitContentVersionWithScheduleSuspension({
+                ctx,
+                documentId: params.documentId,
+                write: async () => {
+                    const deleted = await db.commands.documents.deleteDocumentLocale({
+                        documentId: params.documentId,
+                        locale: params.locale,
+                        status: getDefaultStatus(definition),
+                        createdBy: actorId(ctx),
+                    });
+                    if (deleted == null) {
+                        throw ERR_NOT_FOUND({
+                            message: 'document not found',
+                            details: { documentId: params.documentId, collectionPath },
+                        }).log(ctx.logger);
+                    }
+                    return deleted;
+                },
+            });
+            return { value: result, changed: true };
         });
-        await invokeHook(hooks?.afterUpdate, {
+        const result = committed.value;
+        const revision = committed.revision;
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterUpdate',
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            revision,
+        }, () => invokeHook(hooks?.afterUpdate, {
             data: originalData,
             originalData,
             collectionPath,
@@ -116,11 +118,12 @@ export async function deleteLocale(ctx, params) {
             // never touches it. Read it off the target envelope.
             path: targetRecord.path ?? '',
             deleteLocale: deleteLocaleMarker,
-        });
+        }));
         return {
             documentId: params.documentId,
             documentVersionId: result.newVersionId,
             locale: params.locale,
+            revision,
         };
     });
 }

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

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { ErrorCodes } from '../../lib/errors.js';
+import type { StructuralMutationReceipt } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
 export type DeleteDocumentOutcome = 'committed' | 'committed-with-side-effect-failures';
 export type DeleteDocumentSideEffectPhase = 'afterTreeChange' | 'afterDelete';
@@ -14,12 +15,16 @@ export interface DeleteDocumentSideEffectFailure {
     phase: DeleteDocumentSideEffectPhase;
     code: DeleteDocumentSideEffectCode;
 }
-export interface DeleteDocumentCommittedResult {
+export interface DeleteDocumentCommittedResult extends StructuralMutationReceipt {
+    documentId: string;
+    revision: number;
     deletedVersionCount: number;
     outcome: 'committed';
     sideEffectFailures: [];
 }
-export interface DeleteDocumentCommittedWithSideEffectFailuresResult {
+export interface DeleteDocumentCommittedWithSideEffectFailuresResult extends StructuralMutationReceipt {
+    documentId: string;
+    revision: number;
     deletedVersionCount: number;
     outcome: 'committed-with-side-effect-failures';
     sideEffectFailures: [DeleteDocumentSideEffectFailure, ...DeleteDocumentSideEffectFailure[]];
@@ -42,4 +47,5 @@ export type DeleteDocumentResult = DeleteDocumentCommittedResult | DeleteDocumen
  */
 export declare function deleteDocument(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
 }): Promise<DeleteDocumentResult>;

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

@@ -7,11 +7,12 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND, ErrorCodes } from '../../lib/errors.js';
+import { ErrorCodes } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability, requireTreeAuditCapability, } from './audit.js';
 import { invokeHook } from './internals.js';
 import { appendPublishScheduleCancellationAudit, cancelPublishScheduleInTransaction, } from './publish-schedule-consistency.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 import { firePromoteTreeChange, reconcileTreeOnDeleteInTransaction } from './tree.js';
 function readErrorCode(error) {
     try {
@@ -47,24 +48,16 @@ function serializeSideEffectFailure(phase, error) {
  *   5. `hooks.afterDelete({ documentId, collectionPath })`
  */
 export async function deleteDocument(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteDocument' }, async () => {
         const { db, collectionPath, definition, logger } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'delete');
+        const latest = await readDocumentForMutation(ctx, { ...params, lenient: true });
+        const previousVersionId = latest.document_version_id;
         const hooks = await resolveHooks(definition);
         // 1. Verify the document exists. Soft delete retains field rows and
         //    uploaded objects, so only the envelope and original path projection
         //    are needed for hooks.
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: ctx.collectionId,
-            document_id: params.documentId,
-            reconstruct: false,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
         const hookCtx = {
             documentId: params.documentId,
             collectionPath,
@@ -87,7 +80,7 @@ export async function deleteDocument(ctx, params) {
         const actor = auditActor(ctx);
         let deletedVersionCount = 0;
         let treeResult;
-        await audit.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId }, async () => {
             const cancelledSchedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
             deletedVersionCount = await db.commands.documents.softDeleteDocument({
                 document_id: params.documentId,
@@ -108,7 +101,11 @@ export async function deleteDocument(ctx, params) {
                 schedule: cancelledSchedule,
                 reason: 'soft_deleted',
             });
-        });
+            return {
+                value: undefined,
+                changed: deletedVersionCount > 0 || cancelledSchedule !== null,
+            };
+        }, { collectionLock: 'exclusive' });
         // Everything below is post-commit. Each operation and the logger get an
         // independent attempt; none can turn the committed delete into a rejection.
         const sideEffectFailures = [];
@@ -154,10 +151,22 @@ export async function deleteDocument(ctx, params) {
             }
             return {
                 deletedVersionCount,
+                documentId: params.documentId,
+                revision: committed.revision,
+                affectedDocuments: committed.affectedDocuments,
+                scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
                 outcome: 'committed-with-side-effect-failures',
                 sideEffectFailures: [firstFailure, ...remainingFailures],
             };
         }
-        return { deletedVersionCount, outcome: 'committed', sideEffectFailures: [] };
+        return {
+            deletedVersionCount,
+            documentId: params.documentId,
+            revision: committed.revision,
+            affectedDocuments: committed.affectedDocuments,
+            scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
+            outcome: 'committed',
+            sideEffectFailures: [],
+        };
     });
 }

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

@@ -7,6 +7,8 @@
  */
 import type { DocumentLifecycleContext } from './context.js';
 export interface DuplicateDocumentResult {
+    revision: number;
+    sourceRevision: number;
     /** The newly-created document's id. */
     documentId: string;
     /** The newly-created version id (every duplicate starts at version 1). */
@@ -57,4 +59,5 @@ export interface DuplicateDocumentResult {
  */
 export declare function duplicateDocument(ctx: DocumentLifecycleContext, params: {
     sourceDocumentId: string;
+    expectedRevision: number;
 }): Promise<DuplicateDocumentResult>;

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

@@ -7,13 +7,14 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
+import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
 import { persistInitialDocumentVersion } from './persistence.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 /**
  * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
  * duplicate's data tree. Handles both shapes:
@@ -99,26 +100,21 @@ function deriveDuplicateCandidatePath(definition, fields, defaultLocale, slugifi
  * confirmation modal that calls this out.
  */
 export async function duplicateDocument(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'duplicateDocument' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'create');
+        assertActorCanPerform(ctx.requestContext, definition, 'read');
         const slugifier = ctx.slugifier ?? slugify;
-        const hooks = await resolveHooks(definition);
         // 1. Read source with locale='all' — single read, full multi-locale tree.
-        const source = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.sourceDocumentId,
+        const source = await readDocumentForMutation(ctx, {
+            documentId: params.sourceDocumentId,
+            expectedRevision: params.expectedRevision,
             locale: 'all',
-            reconstruct: true,
             lenient: true,
-            requestContext: ctx.requestContext,
         });
-        if (source == null) {
-            throw ERR_NOT_FOUND({
-                message: 'source document not found',
-                details: { sourceDocumentId: params.sourceDocumentId, collectionPath },
-            }).log(ctx.logger);
-        }
+        const previousVersionId = source.document_version_id;
+        const hooks = await resolveHooks(definition);
         const sourceRecord = source;
         const sourceFields = sourceRecord.fields ?? {};
         // 2. Deep clone — we'll mutate (suffix titles, strip meta ids).
@@ -159,52 +155,68 @@ export async function duplicateDocument(ctx, params) {
         // Embed walker (no-op for multi-locale richtext leaves — see
         // restoreDocumentVersion for the same caveat).
         await applyRichTextEmbed(ctx, clonedFields);
-        try {
-            result = await persistInitialDocumentVersion(ctx, {
-                action: 'create',
-                documentData: clonedFields,
-                path: finalPath,
-                status: defaultStatus,
-                locale: 'all',
-                orderKey,
-            }).catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale, 'duplicate'));
-        }
-        catch (err) {
-            if (!isPathConflictError(err)) {
-                throw err;
+        const committed = await commitGuardedDocumentMutation(ctx, {
+            documentId: params.sourceDocumentId,
+            expectedRevision: params.expectedRevision,
+            previousVersionId,
+            locale: 'all',
+        }, async () => {
+            try {
+                result = await persistInitialDocumentVersion(ctx, {
+                    action: 'create',
+                    documentData: clonedFields,
+                    path: finalPath,
+                    status: defaultStatus,
+                    locale: 'all',
+                    orderKey,
+                }).catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale, 'duplicate'));
             }
-            // Single retry with a short UUID suffix. crypto.randomUUID() is
-            // 36 chars; take the first 4 hex digits for a compact disambiguator.
-            const shortDisambiguator = crypto.randomUUID().slice(0, 4);
-            finalPath = `${candidatePath}-${shortDisambiguator}`;
-            pathRetried = true;
-            ctx.logger?.info({ candidatePath, retryPath: finalPath, sourceDocumentId: params.sourceDocumentId }, 'duplicateDocument: candidate path collided, retrying with short-UUID suffix');
-            result = await persistInitialDocumentVersion(ctx, {
-                action: 'create',
-                documentData: clonedFields,
-                path: finalPath,
-                status: defaultStatus,
-                locale: 'all',
-                orderKey,
-            }).catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale, 'duplicate'));
-        }
+            catch (err) {
+                if (!isPathConflictError(err)) {
+                    throw err;
+                }
+                // Single retry with a short UUID suffix. crypto.randomUUID() is
+                // 36 chars; take the first 4 hex digits for a compact disambiguator.
+                const shortDisambiguator = crypto.randomUUID().slice(0, 4);
+                finalPath = `${candidatePath}-${shortDisambiguator}`;
+                pathRetried = true;
+                ctx.logger?.info({ candidatePath, retryPath: finalPath, sourceDocumentId: params.sourceDocumentId }, 'duplicateDocument: candidate path collided, retrying with short-UUID suffix');
+                result = await persistInitialDocumentVersion(ctx, {
+                    action: 'create',
+                    documentData: clonedFields,
+                    path: finalPath,
+                    status: defaultStatus,
+                    locale: 'all',
+                    orderKey,
+                }).catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale, 'duplicate'));
+            }
+            return { value: result, changed: false };
+        });
+        result = committed.value;
         const newDocumentId = extractDocumentId(result.document);
         const newDocumentVersionId = extractVersionId(result.document);
         // 8. afterCreate hook with duplicate marker.
-        await invokeHook(hooks?.afterCreate, {
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterCreate',
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+            revision: 1,
+        }, () => invokeHook(hooks?.afterCreate, {
             data: clonedFields,
             collectionPath,
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,
             path: finalPath,
             duplicate: duplicateMarker,
-        });
+        }));
         return {
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,
             sourceDocumentId: params.sourceDocumentId,
             newPath: finalPath,
             pathRetried,
+            revision: 1,
+            sourceRevision: committed.revision,
         };
     });
 }

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

@@ -22,17 +22,21 @@
  * One module per operation; shared helpers live in `internals.ts` (not
  * re-exported here — the public surface is exactly this barrel).
  */
+export { getDocumentHookCommittedDetails } from './committed-hook.js';
 export { copyToLocale } from './copy-to-locale.js';
 export { createDocument } from './create.js';
 export { deleteDocument } from './delete.js';
 export { deleteLocale } from './delete-locale.js';
 export { duplicateDocument } from './duplicate.js';
+export { reorderDocument } from './reorder.js';
 export { restoreDocumentVersion } from './restore.js';
 export { cancelDocumentScheduledPublish, confirmDocumentScheduledPublish, getDocumentScheduledPublish, listDocumentPublishSchedules, scheduleDocumentPublish, } from './scheduled-publish.js';
+export { getDocumentRevisionValidationDetails, getDocumentStaleDetails, } from './stale-document.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
 export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';
-export { updateDocument, updateDocumentWithPatches } from './update.js';
+export { replaceDocumentFieldsPreservingStatus, saveDocument, updateDocument, updateDocumentWithPatches, } from './update.js';
+export type { DocumentHookCommittedDetails, DocumentHookCommittedPhase, DocumentHookSideEffectCode, } from './committed-hook.js';
 export type { DocumentLifecycleContext } from './context.js';
 export type { CopyToLocaleResult } from './copy-to-locale.js';
 export type { CreateDocumentResult } from './create.js';

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

@@ -22,14 +22,17 @@
  * One module per operation; shared helpers live in `internals.ts` (not
  * re-exported here — the public surface is exactly this barrel).
  */
+export { getDocumentHookCommittedDetails } from './committed-hook.js';
 export { copyToLocale } from './copy-to-locale.js';
 export { createDocument } from './create.js';
 export { deleteDocument } from './delete.js';
 export { deleteLocale } from './delete-locale.js';
 export { duplicateDocument } from './duplicate.js';
+export { reorderDocument } from './reorder.js';
 export { restoreDocumentVersion } from './restore.js';
 export { cancelDocumentScheduledPublish, confirmDocumentScheduledPublish, getDocumentScheduledPublish, listDocumentPublishSchedules, scheduleDocumentPublish, } from './scheduled-publish.js';
+export { getDocumentRevisionValidationDetails, getDocumentStaleDetails, } from './stale-document.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
 export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';
-export { updateDocument, updateDocumentWithPatches } from './update.js';
+export { replaceDocumentFieldsPreservingStatus, saveDocument, updateDocument, updateDocumentWithPatches, } from './update.js';

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

@@ -5,21 +5,30 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { requireAuditCapability } from './audit.js';
 import { actorId } from './internals.js';
 import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
+import { normalizeDocumentVersionParentError } from './stale-document.js';
+import { appendTreeRoot } from './tree.js';
 /**
  * Persist the first version of a logical document with lifecycle-owned
  * registration and actor metadata. Authentication, hooks, normalization,
  * counters, path derivation, ordering, and rich-text work stay in the caller
  * so their sequencing remains explicit.
  */
-export function persistInitialDocumentVersion(ctx, write) {
-    return ctx.db.commands.documents.createDocumentVersion({
-        ...write,
-        collectionId: ctx.collectionId,
-        collectionVersion: ctx.collectionVersion,
-        collectionConfig: ctx.definition,
-        createdBy: actorId(ctx),
+export async function persistInitialDocumentVersion(ctx, write) {
+    return requireAuditCapability(ctx.db).withTransaction(async () => {
+        await ctx.db.commands.collections.lockCollectionRegistration(ctx.collectionId, ctx.definition.tree === true || ctx.definition.singleton === true ? 'exclusive' : 'shared');
+        const result = await ctx.db.commands.documents.createDocumentVersion({
+            ...write,
+            collectionId: ctx.collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: ctx.definition,
+            createdBy: actorId(ctx),
+        });
+        if (ctx.definition.tree === true)
+            await appendTreeRoot(ctx, result.document.document_id);
+        return result;
     });
 }
 /**
@@ -38,5 +47,7 @@ export function persistExistingDocumentVersion(ctx, write) {
             collectionConfig: ctx.definition,
             createdBy: actorId(ctx),
         }),
+    }).catch((error) => {
+        throw normalizeDocumentVersionParentError(error);
     });
 }

package/dist/services/document-lifecycle/publish-schedule-consistency.d.ts

@@ -34,3 +34,5 @@ export declare function commitContentVersionWithScheduleSuspension<T>(params: {
     documentId: string;
     write: () => Promise<T>;
 }): Promise<T>;
+/** Called after the primary writes, under their document lock and transaction. */
+export declare function suspendPublishScheduleForEdit(ctx: DocumentLifecycleContext, audit: AuditCapability, documentId: string, reason: 'content_edited' | 'document_metadata_changed'): Promise<boolean>;