@byline/core 4.19.0 → 5.0.0

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

@@ -0,0 +1,83 @@
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
+import { generateKeyBetween, generateNKeysBetween } from '../../lib/fractional-index.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
+/** Flat ordering and any sibling-key repairs share one guarded transaction. */
+export async function reorderDocument(ctx, params) {
+    assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+    await readDocumentForMutation(ctx, params);
+    if (ctx.definition.orderable !== true || ctx.definition.tree === true)
+        throw ERR_VALIDATION({ message: 'Flat reorder requires an orderable, non-tree collection' });
+    const audit = requireAuditCapability(ctx.db);
+    const committed = await commitGuardedDocumentMutation(ctx, params, async () => {
+        const rows = await ctx.db.withReadSnapshot((queries) => queries.documents.getCanonicalDocumentOrder({ collection_id: ctx.collectionId }));
+        const keys = new Map(rows.map((row) => [row.id, row.order_key]));
+        const keyed = rows.filter((row) => row.order_key !== null);
+        const corrupt = keyed.some((row, index) => {
+            if (index === 0)
+                return false;
+            const previous = keyed[index - 1];
+            return previous !== undefined && row.order_key <= previous.order_key;
+        });
+        if (corrupt) {
+            const replacements = generateNKeysBetween(null, null, rows.length);
+            rows.forEach((row, index) => {
+                keys.set(row.id, replacements[index]);
+            });
+        }
+        else {
+            const missing = rows.filter((row) => row.order_key === null);
+            const replacements = generateNKeysBetween(keyed.at(-1)?.order_key ?? null, null, missing.length);
+            missing.forEach((row, index) => {
+                keys.set(row.id, replacements[index]);
+            });
+        }
+        const siblings = rows.filter((row) => row.id !== params.documentId);
+        let leftId = params.beforeDocumentId ?? null;
+        const rightId = params.afterDocumentId ?? null;
+        if (leftId === null && rightId === null)
+            leftId = siblings.at(-1)?.id ?? null;
+        const leftIndex = leftId === null ? -1 : siblings.findIndex((row) => row.id === leftId);
+        const rightIndex = rightId === null ? siblings.length : siblings.findIndex((row) => row.id === rightId);
+        if ((leftId !== null && leftIndex < 0) ||
+            (rightId !== null && rightIndex < 0) ||
+            rightIndex !== leftIndex + 1)
+            throw ERR_CONFLICT({
+                message: 'The supplied ordering neighbors have changed. Reload before reordering.',
+            });
+        const left = leftId === null ? null : (keys.get(leftId) ?? null);
+        const right = rightId === null ? null : (keys.get(rightId) ?? null);
+        const current = keys.get(params.documentId);
+        const orderKey = current && (left === null || left < current) && (right === null || current < right)
+            ? current
+            : generateKeyBetween(left, right);
+        keys.set(params.documentId, orderKey);
+        let changed = false;
+        for (const row of rows) {
+            const next = keys.get(row.id);
+            if (next === undefined || next === null || next === row.order_key)
+                continue;
+            await ctx.db.commands.documents.setOrderKey({ document_id: row.id, order_key: next });
+            await audit.append({
+                documentId: row.id,
+                collectionId: ctx.collectionId,
+                ...auditActor(ctx),
+                action: AUDIT_ACTIONS.orderChanged,
+                field: 'order_key',
+                before: row.order_key,
+                after: next,
+            });
+            if (row.id === params.documentId)
+                changed = true;
+        }
+        return { value: orderKey, changed };
+    }, { structuralScope: 'collection' });
+    return {
+        documentId: params.documentId,
+        orderKey: committed.value,
+        revision: committed.revision,
+        affectedDocuments: committed.affectedDocuments,
+        scheduledPublicationsNeedReconfirmation: committed.scheduledPublicationsNeedReconfirmation,
+    };
+}

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

@@ -7,6 +7,7 @@
  */
 import type { DocumentLifecycleContext } from './context.js';
 export interface RestoreVersionResult {
+    revision: number;
     documentId: string;
     documentVersionId: string;
     sourceVersionId: string;
@@ -53,5 +54,6 @@ export interface RestoreVersionResult {
  */
 export declare function restoreDocumentVersion(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     sourceVersionId: string;
 }): Promise<RestoreVersionResult>;

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

@@ -13,6 +13,7 @@ import { getDefaultStatus } from '../../workflow/workflow.js';
 import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
 import { persistExistingDocumentVersion } from './persistence.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
 /**
  * Restore a historical document version as the new current version.
  *
@@ -54,9 +55,12 @@ import { persistExistingDocumentVersion } from './persistence.js';
  *   8. `hooks.afterUpdate({ ..., restore })`
  */
 export async function restoreDocumentVersion(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'restoreDocumentVersion' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'update');
+        const latest = await readDocumentForMutation(ctx, { ...params, locale: 'all' });
+        const previousVersionId = latest.document_version_id;
         const hooks = await resolveHooks(definition);
         // 1. Read source version (full multi-locale tree).
         const source = await db.queries.documents.getDocumentByVersion({
@@ -82,17 +86,7 @@ export async function restoreDocumentVersion(ctx, params) {
         }
         // 3. Current version metadata — used both for the already-current
         //    guard and for the sticky path resolution.
-        const currentMeta = await db.queries.documents.getCurrentVersionMetadata({
-            collection_id: collectionId,
-            document_id: params.documentId,
-        });
-        if (currentMeta == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        if (currentMeta.document_version_id === params.sourceVersionId) {
+        if (previousVersionId === params.sourceVersionId) {
             throw ERR_INVALID_TRANSITION({
                 message: 'source version is already the current version of this document',
                 details: {
@@ -103,12 +97,6 @@ export async function restoreDocumentVersion(ctx, params) {
         }
         // 4. originalData for hooks: full reconstruction of the current
         //    version (locale-scoped, matching updateDocument's semantics).
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: defaultLocale,
-            reconstruct: true,
-        });
         const originalData = latest ?? {};
         const sourceFields = source.fields ?? {};
         const restoreContext = { sourceVersionId: params.sourceVersionId };
@@ -131,19 +119,24 @@ 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 persistExistingDocumentVersion(ctx, {
-            documentId: params.documentId,
-            action: 'restore',
-            documentData: sourceFields,
-            status: getDefaultStatus(definition),
-            locale: 'all',
-            previousVersionId: currentMeta.document_version_id,
+        const committed = await commitGuardedDocumentMutation(ctx, { ...params, previousVersionId, locale: 'all' }, async () => {
+            const result = await persistExistingDocumentVersion(ctx, {
+                documentId: params.documentId,
+                action: 'restore',
+                documentData: sourceFields,
+                status: getDefaultStatus(definition),
+                locale: 'all',
+                previousVersionId: previousVersionId,
+            });
+            return { value: result, changed: true };
         });
+        const result = committed.value;
+        const revision = committed.revision;
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // 7. afterUpdate. Restore is path-sticky: the canonical path comes
         //    from the current version's envelope (originalData), not the source.
-        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId, revision }, () => invokeHook(hooks?.afterUpdate, {
             data: sourceFields,
             originalData,
             collectionPath,
@@ -156,6 +149,7 @@ export async function restoreDocumentVersion(ctx, params) {
             documentId,
             documentVersionId,
             sourceVersionId: params.sourceVersionId,
+            revision,
         };
     });
 }

package/dist/services/document-lifecycle/rethrow-path-conflict.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/document-lifecycle/rethrow-path-conflict.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
@@ -8,7 +9,7 @@
 import { describe, expect, it } from 'vitest';
 import { ErrorCodes } from '../../lib/errors.js';
 import { rethrowPathConflict } from './internals.js';
-const adapterWith = (c) => ({ classifyError: c === undefined ? undefined : () => c });
+const adapterWith = (c) => testAdapter({ classifyError: c === undefined ? undefined : () => c });
 describe('rethrowPathConflict', () => {
     it.each([
         [

package/dist/services/document-lifecycle/revision-guard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { DocumentRevisionTarget, LockedDocumentRevision } from '../../@types/index.js';
+import type { DocumentLifecycleContext } from './context.js';
+/** Public lifecycle services own their commit boundary, including post-commit hooks. */
+export declare function assertLifecycleTransactionOwnership(ctx: DocumentLifecycleContext): void;
+/** Authorized preflight: reject known staleness before hooks or external preparation. */
+export declare function readDocumentForMutation(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    expectedRevision: number;
+    locale?: string;
+    lenient?: boolean;
+}): Promise<Record<string, any>>;
+/** Internal final boundary. The callback contains storage work only, never user hooks. */
+export declare function commitGuardedDocumentMutation<T>(ctx: DocumentLifecycleContext, target: Omit<DocumentRevisionTarget, 'collectionId'>, write: (locked: LockedDocumentRevision) => Promise<{
+    value: T;
+    changed: boolean;
+}>, options?: {
+    collectionLock?: 'exclusive';
+    structuralScope?: 'collection';
+}): Promise<{
+    value: T;
+    revision: number;
+    affectedDocuments: {
+        documentId: string;
+        revision: number;
+    }[];
+    scheduledPublicationsNeedReconfirmation: boolean;
+}>;

package/dist/services/document-lifecycle/revision-guard.js

@@ -0,0 +1,154 @@
+/**
+ * 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 { documentAbilityKey } from '../../auth/register-collection-abilities.js';
+import { ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { documentRevisionFromDatabase, parseDocumentRevision, } from '../../storage/document-revision.js';
+import { requireAuditCapability } from './audit.js';
+import { suspendPublishScheduleForEdit } from './publish-schedule-consistency.js';
+/** Public lifecycle services own their commit boundary, including post-commit hooks. */
+export function assertLifecycleTransactionOwnership(ctx) {
+    if (ctx.db.revisions.isInTransaction()) {
+        throw ERR_VALIDATION({
+            message: 'Public document lifecycle operations cannot run inside an externally owned transaction',
+            details: { reason: 'external_lifecycle_transaction' },
+        });
+    }
+}
+/** Authorized preflight: reject known staleness before hooks or external preparation. */
+export async function readDocumentForMutation(ctx, params) {
+    assertLifecycleTransactionOwnership(ctx);
+    const expectedRevision = parseDocumentRevision(params.expectedRevision);
+    return ctx.db.withReadSnapshot(async (queries) => {
+        const source = await queries.documents.getDocumentById({
+            collection_id: ctx.collectionId,
+            document_id: params.documentId,
+            locale: params.locale ?? ctx.defaultLocale,
+            reconstruct: true,
+            readMode: 'any',
+            lenient: params.lenient,
+            requestContext: ctx.requestContext,
+        });
+        if (source == null)
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId },
+            });
+        const currentRevision = documentRevisionFromDatabase(await queries.documents.getDocumentRevision({
+            collection_id: ctx.collectionId,
+            document_id: params.documentId,
+        }));
+        if (currentRevision !== expectedRevision)
+            throw ERR_DOCUMENT_STALE({
+                message: 'This document has changed. Reload it before making changes.',
+                details: {
+                    reason: 'revision_mismatch',
+                    documentId: params.documentId,
+                    expectedRevision,
+                    currentRevision,
+                },
+            });
+        return source;
+    });
+}
+/** Internal final boundary. The callback contains storage work only, never user hooks. */
+export async function commitGuardedDocumentMutation(ctx, target, write, options = {}) {
+    assertLifecycleTransactionOwnership(ctx);
+    target = { ...target, expectedRevision: parseDocumentRevision(target.expectedRevision) };
+    const audit = requireAuditCapability(ctx.db);
+    return audit.withTransaction(async () => {
+        // Acquire the collection lock before any document lock, including FK locks
+        // from version/path/audit inserts. Ordinary writers share it; exclusive
+        // operations select their mode up front, never upgrading after locking a document.
+        const mode = options.structuralScope === 'collection' ||
+            options.collectionLock === 'exclusive' ||
+            ctx.definition.singleton === true ||
+            ctx.definition.tree === true
+            ? 'exclusive'
+            : 'shared';
+        await ctx.db.commands.collections.lockCollectionRegistration(ctx.collectionId, mode);
+        if (ctx.definition.singleton === true) {
+            const mapped = await ctx.db.queries.singletons.getMappedDocumentId(ctx.collectionId);
+            if (mapped !== target.documentId)
+                throw ERR_NOT_FOUND({ message: 'Singleton target is unavailable; reload before saving' });
+        }
+        const structural = ctx.definition.tree === true || options.structuralScope === 'collection';
+        const before = structural
+            ? await ctx.db.revisions.readStructure({
+                collectionId: ctx.collectionId,
+                ...(options.structuralScope === 'collection'
+                    ? {}
+                    : { documentIds: [target.documentId], parentDocumentId: target.documentId }),
+            })
+            : [];
+        const targets = before
+            .filter((row) => row.live && row.documentId !== target.documentId)
+            .map((row) => ({
+            documentId: row.documentId,
+            collectionId: ctx.collectionId,
+            expectedRevision: row.revision,
+        }));
+        const lockedDocuments = await ctx.db.revisions.lock([
+            ...targets,
+            { ...target, collectionId: ctx.collectionId },
+        ]);
+        const locked = lockedDocuments.find((row) => row.documentId === target.documentId);
+        if (!locked)
+            throw new Error('Revision guard returned no locked observation');
+        if (structural)
+            await ctx.db.commands.documents.publishSchedules.lockDocuments(lockedDocuments.map((row) => row.documentId));
+        const outcome = await write(locked);
+        const after = structural
+            ? await ctx.db.revisions.readStructure({
+                collectionId: ctx.collectionId,
+                documentIds: before.map((row) => row.documentId),
+            })
+            : [];
+        const structuralChanges = new Set();
+        for (const previous of before) {
+            const current = after.find((row) => row.documentId === previous.documentId);
+            if (current &&
+                (current.orderKey !== previous.orderKey ||
+                    current.placed !== previous.placed ||
+                    current.parentDocumentId !== previous.parentDocumentId ||
+                    current.treeOrderKey !== previous.treeOrderKey))
+                structuralChanges.add(previous.documentId);
+        }
+        // Legacy/internal writes can leave edges attached to unavailable documents.
+        // Never commit a derived structural write that was not revision-locked.
+        if ([...structuralChanges].some((id) => !lockedDocuments.some((row) => row.documentId === id)))
+            throw ERR_NOT_FOUND({
+                message: 'A structural target is unavailable; reload before changing this tree.',
+            });
+        let suspended = false;
+        const affectedDocuments = [];
+        let revision = locked.revision;
+        for (const document of lockedDocuments) {
+            const changedStructure = structuralChanges.has(document.documentId);
+            if (changedStructure)
+                suspended =
+                    (await suspendPublishScheduleForEdit(ctx, audit, document.documentId, 'document_metadata_changed')) || suspended;
+            if ((document.documentId === target.documentId && outcome.changed) || changedStructure) {
+                const receipt = await ctx.db.revisions.advance(document);
+                affectedDocuments.push(receipt);
+                if (document.documentId === target.documentId)
+                    revision = receipt.revision;
+            }
+        }
+        const actor = ctx.requestContext?.actor;
+        const canSeeSchedules = actor?.hasAbility(documentAbilityKey(ctx.definition, 'publish')) === true &&
+            actor.hasAbility(documentAbilityKey(ctx.definition, 'changeStatus'));
+        return {
+            value: outcome.value,
+            revision,
+            affectedDocuments: actor?.hasAbility(documentAbilityKey(ctx.definition, 'read'))
+                ? affectedDocuments
+                : affectedDocuments.filter((row) => row.documentId === target.documentId),
+            scheduledPublicationsNeedReconfirmation: canSeeSchedules && suspended,
+        };
+    });
+}

package/dist/services/document-lifecycle/same-document-data.d.ts

@@ -0,0 +1,2 @@
+/** Compare reconstructed field data without treating omitted optional keys as edits. */
+export declare function sameDocumentData(left: unknown, right: unknown): boolean;

package/dist/services/document-lifecycle/same-document-data.js

@@ -0,0 +1,17 @@
+/** Compare reconstructed field data without treating omitted optional keys as edits. */
+export function sameDocumentData(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left instanceof Date && right instanceof Date)
+        return left.getTime() === right.getTime();
+    if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    if (Array.isArray(left) || Array.isArray(right))
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => sameDocumentData(value, right[index])));
+    const a = left, b = right;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((key) => sameDocumentData(a[key], b[key]));
+}

package/dist/services/document-lifecycle/scheduled-publish.d.ts

@@ -15,6 +15,7 @@ export type ClaimedScheduledPublicationResult = {
     status: 'claim_lost';
 } | {
     status: 'target_changed';
+    reason: 'content_edited' | 'document_metadata_changed';
 } | {
     status: 'terminal';
     reason: 'document_not_found' | 'already_published' | 'invalid_transition';
@@ -23,14 +24,24 @@ export declare function scheduleDocumentPublish(ctx: DocumentLifecycleContext, p
     documentId: string;
     publishAt: string;
     expectedVersionId: string;
-}): Promise<DocumentPublishSchedule>;
+    expectedRevision: number;
+}): Promise<DocumentPublishSchedule & {
+    revision: number;
+}>;
 export declare function confirmDocumentScheduledPublish(ctx: DocumentLifecycleContext, params: {
     documentId: string;
     expectedVersionId: string;
-}): Promise<DocumentPublishSchedule>;
+    expectedRevision: number;
+}): Promise<DocumentPublishSchedule & {
+    revision: number;
+}>;
 export declare function cancelDocumentScheduledPublish(ctx: DocumentLifecycleContext, params: {
     documentId: string;
-}): Promise<DocumentPublishSchedule | null>;
+    expectedRevision: number;
+}): Promise<{
+    schedule: DocumentPublishSchedule | null;
+    revision: number;
+}>;
 export declare function getDocumentScheduledPublish(ctx: DocumentLifecycleContext, params: {
     documentId: string;
 }): Promise<DocumentPublishSchedule | null>;
@@ -39,7 +50,12 @@ export declare function listDocumentPublishSchedules(core: BylineCore, requestCo
     lastAuthorizedBy?: string;
     page: number;
     pageSize: number;
-}): Promise<DocumentPublishSchedulePage>;
+}): Promise<Omit<DocumentPublishSchedulePage, 'schedules'> & {
+    schedules: (DocumentPublishSchedule & {
+        revision: number;
+        documentPath: string | null;
+    })[];
+}>;
 /**
  * Execute one token-fenced publication through the normal status lifecycle.
  * Internal to the server-only sweep: authorization was captured when the row