@byline/core 4.16.0 → 4.18.0

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

@@ -575,3 +575,78 @@ describe('validateCollections — search config fields', () => {
         expect(() => validateCollections([searchable({ filters: ['nope'] })])).toThrow(/no top-level field with that name exists/);
     });
 });
+describe('validateCollections — singletons', () => {
+    const singleton = (extra) => ({
+        path: 'site-settings',
+        label: 'Site settings',
+        singleton: true,
+        fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+        ...extra,
+    });
+    it('rejects orderable on a singleton', () => {
+        expect(() => validateCollections([singleton({ orderable: true })])).toThrow(/orderable/);
+    });
+    it('rejects tree on a singleton', () => {
+        expect(() => validateCollections([singleton({ tree: true })])).toThrow(/tree/);
+    });
+    it('rejects useAsPath on a singleton', () => {
+        expect(() => validateCollections([singleton({ useAsPath: 'name' })])).toThrow(/useAsPath/);
+    });
+    it('rejects search configuration on a singleton', () => {
+        expect(() => validateCollections([singleton({ search: { body: ['name'] } })])).toThrow(/search/);
+    });
+    it('rejects advertiseLocales on a singleton', () => {
+        expect(() => validateCollections([singleton({ advertiseLocales: true })])).toThrow(/advertiseLocales/);
+    });
+    it('accepts a well-formed singleton', () => {
+        expect(() => validateCollections([singleton({})])).not.toThrow();
+    });
+    it('rejects a relation whose target is a singleton', () => {
+        const singletonTarget = singleton({});
+        const referrer = {
+            path: 'news',
+            labels: { singular: 'Article', plural: 'News' },
+            fields: [
+                {
+                    name: 'settings',
+                    label: 'Settings',
+                    type: 'relation',
+                    targetCollection: 'site-settings',
+                },
+            ],
+        };
+        expect(() => validateCollections([singletonTarget, referrer])).toThrow(/singleton/i);
+    });
+    it('rejects labels on a singleton at runtime', () => {
+        expect(() => validateCollections([singleton({ labels: { singular: 'S', plural: 'P' } })])).toThrow(/labels|label/i);
+    });
+    it('accepts the singleton hook family', () => {
+        expect(() => validateCollections([
+            singleton({
+                hooks: { beforeRead: () => false },
+            }),
+        ])).not.toThrow();
+    });
+    it('still applies field-level validation to a singleton', () => {
+        expect(() => validateCollections([
+            singleton({
+                fields: [
+                    {
+                        name: 'heroImage',
+                        label: 'Hero image',
+                        type: 'image',
+                        upload: { location: '/leading-slash-is-invalid' },
+                    },
+                ],
+            }),
+        ])).toThrow(/location/);
+    });
+    it('rejects a singleton whose path collides with a collection', () => {
+        const collection = {
+            path: 'site-settings',
+            labels: { singular: 'Setting', plural: 'Settings' },
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+        };
+        expect(() => validateCollections([collection, singleton({})])).toThrow(/site-settings/);
+    });
+});

package/dist/core.d.ts

@@ -30,9 +30,8 @@ export interface BylineCore<TAdminStore = unknown> {
      */
     getCollectionRecord: (path: string) => CollectionRecord;
     /**
-     * Ability registry. Populated at init time with the CRUD + workflow
-     * abilities contributed by each declared collection
-     * (`collections.<path>.{read,create,update,delete,publish,changeStatus}`).
+     * Ability registry. Populated at init time with the kind-aware ability
+     * family contributed by every declared document resource.
      *
      * Plugins and future subsystems contribute their own abilities via
      * `registerAbility()` — or directly against `core.abilities` — typically

package/dist/core.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { AbilityRegistry } from '@byline/auth';
-import { registerCollectionAbilities } from './auth/register-collection-abilities.js';
+import { registerDocumentAbilities } from './auth/register-collection-abilities.js';
 import { defineBylineCore, getBylineCoreUnsafe, registerServerConfig, resolveServerConfig, } from './config/config.js';
 import { createBylineLogger, defineLogger } from './lib/logger.js';
 import { Registry } from './lib/registry.js';
@@ -157,12 +157,12 @@ export const initBylineCore = async (config, pinoLogger) => {
         }
         return record;
     };
-    // Ability registry — populated with each collection's CRUD + workflow
+    // Ability registry — populated with each document resource's kind-aware
     // abilities. Plugins and subsystems add their own via
     // `core.registerAbility()` or `core.abilities.register()`.
     const abilities = new AbilityRegistry();
     for (const definition of composed.collections) {
-        registerCollectionAbilities(abilities, definition);
+        registerDocumentAbilities(abilities, definition);
     }
     const core = {
         config: composed.config,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './@types/index.js';
-export { type ActorAbilitySnapshot, applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, filterReadableCollections, registerCollectionAbilities, } from './auth/index.js';
-export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { type ActorAbilitySnapshot, applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityResource, type CollectionAbilityResourceDescriptor, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, type DocumentAbilityResource, type DocumentAbilityVerbFor, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, type SingletonAbilityResource, type SingletonAbilityResourceDescriptor, type SingletonAbilityVerb, } from './auth/index.js';
+export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, getSingletonAdminConfig, orderByContentLocale, } from './config/config.js';
 export { type CollectionGroupBucket, groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';

package/dist/index.js

@@ -11,8 +11,8 @@
 // breaking package-surface change.
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, filterReadableCollections, registerCollectionAbilities, } from './auth/index.js';
-export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './auth/index.js';
+export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, getSingletonAdminConfig, orderByContentLocale, } from './config/config.js';
 export { groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';

package/dist/lib/errors.d.ts

@@ -141,15 +141,17 @@ export declare const ERR_TREE_HOOK_COMMITTED: (opts: BylineErrorOptions, errorCo
  */
 export declare const DbErrorCodes: {
     readonly UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION';
+    readonly FOREIGN_KEY_VIOLATION: 'DB_FOREIGN_KEY_VIOLATION';
     readonly UNKNOWN: 'DB_UNKNOWN';
 };
 export type DbErrorCode = (typeof DbErrorCodes)[keyof typeof DbErrorCodes];
 export interface DbErrorClassification {
     code: DbErrorCode;
     /**
-     * For `DB_UNIQUE_VIOLATION`: the violated constraint / index name when the
-     * driver exposes it (Postgres carries it structurally; MySQL parses it from
-     * the error message). Absent when the driver surfaces no name.
+     * For `DB_UNIQUE_VIOLATION` and `DB_FOREIGN_KEY_VIOLATION`: the violated
+     * constraint / index name when the driver exposes it (Postgres carries it
+     * structurally; MySQL parses it from the error message). Absent when the
+     * driver surfaces no name.
      */
     constraint?: string;
 }

package/dist/lib/errors.js

@@ -181,5 +181,6 @@ export const ERR_TREE_HOOK_COMMITTED = createErrorType(ErrorCodes.TREE_HOOK_COMM
  */
 export const DbErrorCodes = {
     UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION',
+    FOREIGN_KEY_VIOLATION: 'DB_FOREIGN_KEY_VIOLATION',
     UNKNOWN: 'DB_UNKNOWN',
 };

package/dist/services/collection-bootstrap.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { isSingleton } from '../@types/collection-types.js';
 import { fingerprintCollection } from '../storage/collection-fingerprint.js';
 /**
  * Reconcile every registered `CollectionDefinition` with its row in the
@@ -57,6 +58,17 @@ async function reconcileCollection(definition, db, logger) {
             record: { collectionId, version: initialVersion, schemaHash: fingerprint },
         };
     }
+    const storedConfig = (existing.config ?? {});
+    const storedIsSingleton = storedConfig.singleton === true;
+    const incomingIsSingleton = isSingleton(definition);
+    if (storedIsSingleton !== incomingIsSingleton) {
+        throw new Error(`Registered schema "${definition.path}" changed kind from ` +
+            `${storedIsSingleton ? 'singleton' : 'collection'} to ` +
+            `${incomingIsSingleton ? 'singleton' : 'collection'}. Cardinality and supported ` +
+            'operations differ between the two, so this needs an explicit data migration — ' +
+            'not a schema-version bump. Register the new kind under a different path, migrate ' +
+            'the documents, then retire the old one.');
+    }
     const collectionId = existing.id;
     const storedVersion = (existing.version ?? 1) | 0;
     const storedHash = existing.schema_hash ?? null;

package/dist/services/collection-bootstrap.test.node.js

@@ -23,15 +23,19 @@ function baseCollection() {
 }
 function createMockDb(options) {
     const getCollectionByPath = vi.fn(options.getCollectionByPath ?? (async () => options.existingRow ?? null));
-    const create = vi
-        .fn()
-        .mockImplementation(async (_path, _config, _opts) => [
-        { id: 'col-new' },
-    ]);
-    const update = vi.fn().mockResolvedValue([{ id: options.existingRow?.id ?? 'col-new' }]);
     const fail = () => {
         throw new Error('not expected to be called');
     };
+    const create = options.failWrites
+        ? vi.fn(fail)
+        : vi
+            .fn()
+            .mockImplementation(async (_path, _config, _opts) => [
+            { id: 'col-new' },
+        ]);
+    const update = options.failWrites
+        ? vi.fn(fail)
+        : vi.fn().mockResolvedValue([{ id: options.existingRow?.id ?? 'col-new' }]);
     const db = {
         commands: {
             collections: { create, update, delete: vi.fn(fail) },
@@ -65,6 +69,11 @@ function createMockDb(options) {
                 nextScopedCounterValue: vi.fn(fail),
             },
             audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
+            singletons: {
+                lockSlot: vi.fn(fail),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
         },
         queries: {
             collections: {
@@ -105,6 +114,7 @@ function createMockDb(options) {
                     meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
                 })),
             },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
         },
         withTransaction: async (fn) => fn(),
     };
@@ -216,4 +226,51 @@ describe('ensureCollections', () => {
         expect(create).toHaveBeenCalledTimes(1);
         expect(update).not.toHaveBeenCalled();
     });
+    it('rejects changing a registered path from collection to singleton before writing', async () => {
+        const { db, create, update } = createMockDb({
+            existingRow: {
+                id: 'col-1',
+                version: 1,
+                schema_hash: 'stale',
+                config: { path: 'site-settings', fields: [] },
+            },
+            failWrites: true,
+        });
+        await expect(ensureCollections({
+            definitions: [
+                {
+                    path: 'site-settings',
+                    label: 'Site settings',
+                    singleton: true,
+                    fields: [{ name: 'name', label: 'Site name', type: 'text' }],
+                },
+            ],
+            db,
+        })).rejects.toThrow(/kind/i);
+        expect(create).not.toHaveBeenCalled();
+        expect(update).not.toHaveBeenCalled();
+    });
+    it('rejects changing a registered path from singleton to collection before writing', async () => {
+        const { db, create, update } = createMockDb({
+            existingRow: {
+                id: 'col-1',
+                version: 1,
+                schema_hash: 'stale',
+                config: { path: 'site-settings', singleton: true, fields: [] },
+            },
+            failWrites: true,
+        });
+        await expect(ensureCollections({
+            definitions: [
+                {
+                    path: 'site-settings',
+                    labels: { singular: 'Setting', plural: 'Settings' },
+                    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+                },
+            ],
+            db,
+        })).rejects.toThrow(/kind/i);
+        expect(create).not.toHaveBeenCalled();
+        expect(update).not.toHaveBeenCalled();
+    });
 });

package/dist/services/discover-counter-groups.test.node.js

@@ -52,6 +52,11 @@ function makeAdapter(options) {
                 nextScopedCounterValue: vi.fn(fail),
             },
             audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
+            singletons: {
+                lockSlot: vi.fn(fail),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
         },
         queries: {
             collections: {
@@ -92,6 +97,7 @@ function makeAdapter(options) {
                     meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
                 })),
             },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
         },
         withTransaction: async (fn) => fn(),
     };

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

@@ -10,9 +10,9 @@ 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 { actorId, applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
+import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
-import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
+import { persistExistingDocumentVersion } from './persistence.js';
 /**
  * Copy a document's content from one locale into another, in place on
  * the same document.
@@ -48,7 +48,7 @@ import { commitContentVersionWithScheduleSuspension } from './publish-schedule-c
 export async function copyToLocale(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'copyToLocale' }, async () => {
         const { db, definition, collectionId, collectionPath } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        assertActorCanPerform(ctx.requestContext, definition, 'update');
         if (params.sourceLocale === params.targetLocale) {
             throw ERR_VALIDATION({
                 message: 'sourceLocale and targetLocale must differ',
@@ -124,21 +124,13 @@ export async function copyToLocale(ctx, params) {
         //    rewritten by this call).
         const previousVersionId = targetRecord.document_version_id ?? undefined;
         await applyRichTextEmbed(ctx, merged.data);
-        const writeResult = await commitContentVersionWithScheduleSuspension({
-            ctx,
+        const writeResult = await persistExistingDocumentVersion(ctx, {
             documentId: params.documentId,
-            write: () => db.commands.documents.createDocumentVersion({
-                documentId: params.documentId,
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
-                action: 'copy_to_locale',
-                documentData: merged.data,
-                status: getDefaultStatus(definition),
-                locale: params.targetLocale,
-                previousVersionId,
-                createdBy: actorId(ctx),
-            }),
+            action: 'copy_to_locale',
+            documentData: merged.data,
+            status: getDefaultStatus(definition),
+            locale: params.targetLocale,
+            previousVersionId,
         });
         const documentVersionId = extractVersionId(writeResult.document);
         await invokeHook(hooks?.afterUpdate, {

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

@@ -15,7 +15,8 @@ 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 { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { persistInitialDocumentVersion } from './persistence.js';
 import { appendTreeRoot } from './tree.js';
 /**
  * Create a new document.
@@ -33,8 +34,8 @@ import { appendTreeRoot } from './tree.js';
  */
 export async function createDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'createDocument' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        const { db, definition, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, definition, 'create');
         // Reject unsupported tree adapters before hooks, counters, or persistence
         // can create a document that cannot be placed and audited safely.
         if (definition.tree === true)
@@ -72,11 +73,7 @@ export async function createDocument(ctx, params) {
         // Refresh embedded relation envelopes inside rich-text fields
         // (internal-link / inline-image nodes) before flatten-and-persist.
         await applyRichTextEmbed(ctx, data);
-        const result = await db.commands.documents
-            .createDocumentVersion({
-            collectionId,
-            collectionVersion: ctx.collectionVersion,
-            collectionConfig: definition,
+        const result = await persistInitialDocumentVersion(ctx, {
             action: 'create',
             documentData: data,
             path: resolvedPath,
@@ -84,9 +81,7 @@ export async function createDocument(ctx, params) {
             status: params.status ?? data.status ?? getDefaultStatus(definition),
             locale: params.locale ?? defaultLocale,
             orderKey,
-            createdBy: actorId(ctx),
-        })
-            .catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale, 'create'));
+        }).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:

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

@@ -40,7 +40,7 @@ import { commitContentVersionWithScheduleSuspension } from './publish-schedule-c
 export async function deleteLocale(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        assertActorCanPerform(ctx.requestContext, definition, 'update');
         // The default locale anchors the document's path and source_locale —
         // it cannot be deleted (the other locales fall back to it).
         if (params.locale === defaultLocale) {

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

@@ -49,7 +49,7 @@ function serializeSideEffectFailure(phase, error) {
 export async function deleteDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteDocument' }, async () => {
         const { db, collectionPath, definition, logger } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'delete');
+        assertActorCanPerform(ctx.requestContext, definition, 'delete');
         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

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

@@ -12,7 +12,8 @@ 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 { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
+import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
+import { persistInitialDocumentVersion } from './persistence.js';
 /**
  * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
  * duplicate's data tree. Handles both shapes:
@@ -100,7 +101,7 @@ function deriveDuplicateCandidatePath(definition, fields, defaultLocale, slugifi
 export async function duplicateDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'duplicateDocument' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        assertActorCanPerform(ctx.requestContext, definition, 'create');
         const slugifier = ctx.slugifier ?? slugify;
         const hooks = await resolveHooks(definition);
         // 1. Read source with locale='all' — single read, full multi-locale tree.
@@ -159,20 +160,14 @@ export async function duplicateDocument(ctx, params) {
         // restoreDocumentVersion for the same caveat).
         await applyRichTextEmbed(ctx, clonedFields);
         try {
-            result = await db.commands.documents
-                .createDocumentVersion({
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
+            result = await persistInitialDocumentVersion(ctx, {
                 action: 'create',
                 documentData: clonedFields,
                 path: finalPath,
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
-                createdBy: actorId(ctx),
-            })
-                .catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale, 'duplicate'));
+            }).catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale, 'duplicate'));
         }
         catch (err) {
             if (!isPathConflictError(err)) {
@@ -184,20 +179,14 @@ export async function duplicateDocument(ctx, params) {
             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 db.commands.documents
-                .createDocumentVersion({
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
+            result = await persistInitialDocumentVersion(ctx, {
                 action: 'create',
                 documentData: clonedFields,
                 path: finalPath,
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
-                createdBy: actorId(ctx),
-            })
-                .catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale, 'duplicate'));
+            }).catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale, 'duplicate'));
         }
         const newDocumentId = extractDocumentId(result.document);
         const newDocumentVersionId = extractVersionId(result.document);

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

@@ -0,0 +1,29 @@
+/**
+ * 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 type { IDocumentCommands } from '../../@types/index.js';
+import type { DocumentLifecycleContext } from './context.js';
+type AdapterVersionWrite = Parameters<IDocumentCommands['createDocumentVersion']>[0];
+type LifecycleOwnedWriteKeys = 'collectionId' | 'collectionVersion' | 'collectionConfig' | 'createdBy';
+type InitialDocumentVersionWrite = Omit<AdapterVersionWrite, LifecycleOwnedWriteKeys | 'documentId' | 'previousVersionId'>;
+type ExistingDocumentVersionWrite = Omit<AdapterVersionWrite, LifecycleOwnedWriteKeys | 'documentId'> & {
+    documentId: string;
+};
+/**
+ * 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 declare function persistInitialDocumentVersion(ctx: DocumentLifecycleContext, write: InitialDocumentVersionWrite): ReturnType<IDocumentCommands['createDocumentVersion']>;
+/**
+ * Persist a new version of an existing logical document and suspend any armed
+ * publication schedule atomically. All operation-specific preparation and
+ * hook sequencing remains in the caller.
+ */
+export declare function persistExistingDocumentVersion(ctx: DocumentLifecycleContext, write: ExistingDocumentVersionWrite): ReturnType<IDocumentCommands['createDocumentVersion']>;
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * 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 { actorId } from './internals.js';
+import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.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),
+    });
+}
+/**
+ * Persist a new version of an existing logical document and suspend any armed
+ * publication schedule atomically. All operation-specific preparation and
+ * hook sequencing remains in the caller.
+ */
+export function persistExistingDocumentVersion(ctx, write) {
+    return commitContentVersionWithScheduleSuspension({
+        ctx,
+        documentId: write.documentId,
+        write: () => ctx.db.commands.documents.createDocumentVersion({
+            ...write,
+            collectionId: ctx.collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: ctx.definition,
+            createdBy: actorId(ctx),
+        }),
+    });
+}

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

@@ -10,8 +10,8 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, } from './internals.js';
-import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
+import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
+import { persistExistingDocumentVersion } from './persistence.js';
 /**
  * Restore a historical document version as the new current version.
  *
@@ -55,7 +55,7 @@ import { commitContentVersionWithScheduleSuspension } from './publish-schedule-c
 export async function restoreDocumentVersion(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'restoreDocumentVersion' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        assertActorCanPerform(ctx.requestContext, definition, 'update');
         const hooks = await resolveHooks(definition);
         // 1. Read source version (full multi-locale tree).
         const source = await db.queries.documents.getDocumentByVersion({
@@ -130,21 +130,13 @@ export async function restoreDocumentVersion(ctx, params) {
         //
         // No `path` is passed: restore does not change the document's path
         // (the existing byline_document_paths row stays as-is — sticky).
-        const result = await commitContentVersionWithScheduleSuspension({
-            ctx,
+        const result = await persistExistingDocumentVersion(ctx, {
             documentId: params.documentId,
-            write: () => db.commands.documents.createDocumentVersion({
-                documentId: params.documentId,
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
-                action: 'restore',
-                documentData: sourceFields,
-                status: getDefaultStatus(definition),
-                locale: 'all',
-                previousVersionId: currentMeta.document_version_id,
-                createdBy: actorId(ctx),
-            }),
+            action: 'restore',
+            documentData: sourceFields,
+            status: getDefaultStatus(definition),
+            locale: 'all',
+            previousVersionId: currentMeta.document_version_id,
         });
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);