@byline/core 4.14.1 → 4.16.0

package/dist/scheduler/types.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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 { BylineLogger } from '../logger/index.js';
+/** Lifecycle state of a registered task, as persisted by the store. */
+export type RecurringTaskStatus = 'never_run' | 'running' | 'succeeded' | 'failed';
+/**
+ * What a handler may tell the runner when it returns.
+ *
+ * `workRemaining` means the handler stopped on a batch budget rather than an
+ * empty queue. The runner then sets the next run to database-now instead of
+ * database-now plus the interval. This only accelerates a task whose interval
+ * exceeds the tick cadence; a task already at the 60s minimum becomes due on
+ * the next tick either way.
+ */
+export interface RecurringTaskResult {
+    workRemaining?: boolean;
+}
+/** Everything a handler is given for one execution. */
+export interface RecurringTaskContext {
+    taskName: string;
+    /** The `next_run_at` that made this task due. Diagnostic, not a business cursor. */
+    scheduledFor: Date;
+    /** Aborted on shutdown or on lease loss. Handlers check it between batches. */
+    signal: AbortSignal;
+    logger: BylineLogger;
+    /** Renew the lease. Rejects when the lease has been lost, which aborts the run. */
+    heartbeat(): Promise<void>;
+}
+export interface RecurringTaskDefinition {
+    /** Stable, code-owned, globally unique key, e.g. `analytics.rollup`. */
+    name: string;
+    /** Delay after a successful run. Minimum 60_000. */
+    intervalMs: number;
+    /** Initial lease window. Minimum 60_000. A long run renews before it expires. */
+    leaseMs: number;
+    run(context: RecurringTaskContext): Promise<RecurringTaskResult | void>;
+}
+/** A task successfully claimed by this instance. */
+export interface ClaimedRecurringTask {
+    name: string;
+    /** Unique to this claim. Every later write is conditional on it. */
+    leaseToken: string;
+    scheduledFor: Date;
+    /** Database time at the moment of the claim. */
+    databaseNow: Date;
+    /**
+     * True when this claim took over a lease that had expired — i.e. a previous
+     * runner died mid-execution without recording an outcome. The runner logs a
+     * distinct `recovered-expired-lease` event for these. False for an ordinary
+     * claim of an unleased row.
+     */
+    recoveredExpiredLease: boolean;
+}
+/** Read-only health row for diagnostics and admin surfaces. */
+export interface RecurringTaskHealth {
+    name: string;
+    intervalMs: number;
+    nextRunAt: Date;
+    lastStatus: RecurringTaskStatus;
+    lastStartedAt: Date | null;
+    lastSucceededAt: Date | null;
+    lastFailedAt: Date | null;
+    lastDurationMs: number | null;
+    consecutiveFailures: number;
+    lastError: string | null;
+    /** True when a lease exists and has passed its expiry — a crashed runner. */
+    leaseExpired: boolean;
+    /** Database time when this row was read, so callers can judge staleness. */
+    databaseNow: Date;
+}
+/** What a definition contributes to reconciliation. */
+export interface ReconcileTaskInput {
+    name: string;
+    intervalMs: number;
+}
+/**
+ * The optional scheduler capability a database adapter implements. Every method
+ * derives due-ness and expiry from database time, never from the process clock.
+ *
+ * A MySQL (or any third) adapter implementing this interface should be able to
+ * do so from the doc comments below without reading the design spec — every
+ * method states exactly which columns it reads and writes.
+ *
+ * One rule holds across every method and is not repeated below: every
+ * successful mutation — `reconcile`, `claim`, `renew`, `complete`, `fail` —
+ * also sets `updated_at` from database time, in addition to the per-method
+ * column lists that follow.
+ */
+export interface ISchedulerStore {
+    /**
+     * Insert rows for unknown names and update `interval_ms` for known ones,
+     * preserving health history. Must be safe to run concurrently from several
+     * instances — a deploy restarts them together.
+     *
+     * A brand-new row's `next_run_at` is database-now **plus** the task's
+     * `intervalMs` — a task never fires at module evaluation or immediately on
+     * deploy; the first execution is one interval after the row is created.
+     *
+     * For an existing, unleased row:
+     *
+     * - When the interval **decreases**, `next_run_at` is clamped to no later
+     *   than database-now plus the new interval, so a task moving from a daily
+     *   to a minute-grained cadence does not wait out the rest of the old day.
+     * - When the interval **increases**, an already-due or earlier-scheduled
+     *   `next_run_at` is left alone — it is NOT postponed to reflect the new,
+     *   longer interval. The new cadence takes effect starting from the next
+     *   time the row completes successfully (see `complete` below).
+     *
+     * `interval_ms` is always updated, including on a row carrying a live
+     * lease (`lease_expires_at` in the future) — the lease protects
+     * `next_run_at` and the lease columns themselves (`lease_token`,
+     * `lease_owner`, `lease_expires_at`), which are left untouched while a
+     * lease is live, but not `interval_ms`. This matters because `complete`
+     * derives `next_run_at` from the row's persisted `interval_ms` rather than
+     * from a caller-supplied value (see `complete` below); if reconcile
+     * skipped leased rows entirely, a newly deployed cadence would not take
+     * effect until the in-flight lease released, which would partially defeat
+     * the reason `complete` stopped accepting an interval from the runner. A
+     * rolling deploy is exactly the moment both a reconcile and a live lease
+     * are likely to coincide.
+     *
+     * Rows for names no longer present in the registered task set are retained
+     * as dormant history: reconcile neither executes them nor deletes them.
+     * Pruning dormant rows is a future explicit maintenance operation, not a
+     * side effect of reconcile.
+     */
+    reconcile(tasks: readonly ReconcileTaskInput[]): Promise<void>;
+    /**
+     * Atomically claim `name` if it is due (`next_run_at <= database now`) and
+     * either unleased or its lease has expired. Returns null when another
+     * instance won the race or the task is not yet due.
+     *
+     * On a successful claim, exactly these columns are mutated:
+     *
+     * - `lease_token` — set to a fresh, claim-unique token.
+     * - `lease_owner` — set to the caller-supplied `owner` label.
+     * - `lease_expires_at` — set to database-now plus `leaseMs`.
+     * - `last_started_at` — set to database-now.
+     * - `last_status` — set to `'running'`.
+     *
+     * `next_run_at` is deliberately left untouched by claim. The returned
+     * `scheduledFor` is that pre-claim `next_run_at` value — the due time that
+     * made the row eligible, not a new value computed at claim time. Because
+     * claim never advances `next_run_at`, a row whose runner died without
+     * calling `complete` or `fail` stays due, so another instance can reclaim
+     * it the moment `lease_expires_at` passes (`recoveredExpiredLease: true`
+     * on that claim — see `ClaimedRecurringTask`).
+     */
+    claim(params: {
+        name: string;
+        leaseMs: number;
+        owner: string;
+    }): Promise<ClaimedRecurringTask | null>;
+    /**
+     * Extend a token-matched lease: sets `lease_expires_at` to database-now
+     * plus `leaseMs`. Every write here and below is conditioned on
+     * `lease_token = params.leaseToken` — a stale runner whose lease has since
+     * been reclaimed by another instance cannot successfully renew, complete,
+     * or fail the row. Expiry alone does not invalidate a still-matching token:
+     * a runner may renew after the deadline provided no other claimant has
+     * replaced its token. Returns `false` (never throws) only when the token does
+     * not match — i.e. the lease has actually been lost.
+     */
+    renew(params: {
+        name: string;
+        leaseToken: string;
+        leaseMs: number;
+    }): Promise<boolean>;
+    /**
+     * Record success on a token-matched row.
+     *
+     * Fields cleared: `lease_token`, `lease_owner`, `lease_expires_at` (all set
+     * to null — the row is unleased again).
+     *
+     * Fields reset: `consecutive_failures` back to 0, `last_error` to null —
+     * a success always clears prior failure state regardless of how many
+     * failures preceded it.
+     *
+     * Fields recorded: `last_succeeded_at` and `last_duration_ms` from
+     * `durationMs`; `last_status` set to `'succeeded'`.
+     *
+     * `next_run_at` becomes database-now plus the row's **persisted**
+     * `interval_ms` — never an interval supplied by the caller. A runner that
+     * has been holding a lease across a rolling deploy may be carrying a stale
+     * cadence; reading the column instead means a newly reconciled interval
+     * always wins. When `workRemaining` is true, `next_run_at` becomes
+     * database-now instead, ignoring the interval entirely.
+     *
+     * Returns `false` (never throws) when the token does not match — the
+     * lease had already been lost.
+     */
+    complete(params: {
+        name: string;
+        leaseToken: string;
+        durationMs: number;
+        workRemaining: boolean;
+    }): Promise<boolean>;
+    /**
+     * Record failure on a token-matched row.
+     *
+     * Fields cleared: `lease_token`, `lease_owner`, `lease_expires_at` (all set
+     * to null — the row is unleased again, so another instance may claim it
+     * once `next_run_at` is reached).
+     *
+     * Fields incremented / stored: `consecutive_failures` is incremented by
+     * one; `last_error` is stored, truncated to 2048 characters and never
+     * containing a stack trace (full stacks belong in the configured logger,
+     * not this column). `last_failed_at` and `last_duration_ms` are recorded
+     * from `durationMs`; `last_status` is set to `'failed'`.
+     *
+     * `next_run_at` becomes database-now plus a bounded backoff derived from
+     * the just-incremented `consecutive_failures`: 1, 2, 4, 8 minutes for the
+     * first four consecutive failures, then capped at 15 minutes for the fifth
+     * and every subsequent consecutive failure. A later success (`complete`)
+     * restores the configured `interval_ms` and resets this sequence — the
+     * backoff never compounds across a success.
+     *
+     * Returns `false` (never throws) when the token does not match — the
+     * lease had already been lost.
+     */
+    fail(params: {
+        name: string;
+        leaseToken: string;
+        durationMs: number;
+        error: string;
+    }): Promise<boolean>;
+    /**
+     * Health rows for the named tasks, or all rows when `names` is omitted.
+     *
+     * `lease_owner` is a bounded, non-secret diagnostic label (typically a
+     * machine id plus process id), capped at 255 characters. Correctness never
+     * depends on it being unique — fencing is entirely a function of
+     * `lease_token`, never of `lease_owner`.
+     */
+    health(names?: readonly string[]): Promise<RecurringTaskHealth[]>;
+}

package/dist/scheduler/types.js

@@ -0,0 +1,8 @@
+/**
+ * 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/validate-scheduler-config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { ISchedulerStore, RecurringTaskDefinition } from './types.js';
+/**
+ * Boot-time gate. Recurring tasks registered against an adapter that does not
+ * implement the optional scheduler capability would silently never run, so this
+ * fails loudly at `initBylineCore()` instead.
+ */
+export declare function validateSchedulerConfig(params: {
+    tasks?: readonly RecurringTaskDefinition[];
+    adapter: {
+        scheduler?: ISchedulerStore;
+    };
+}): void;

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

@@ -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 { validateRecurringTasks } from './validate-tasks.js';
+/**
+ * Boot-time gate. Recurring tasks registered against an adapter that does not
+ * implement the optional scheduler capability would silently never run, so this
+ * fails loudly at `initBylineCore()` instead.
+ */
+export function validateSchedulerConfig(params) {
+    const tasks = params.tasks ?? [];
+    if (tasks.length === 0)
+        return;
+    validateRecurringTasks(tasks);
+    if (params.adapter.scheduler == null) {
+        const names = tasks.map((t) => t.name).join(', ');
+        throw new Error(`recurring tasks are registered (${names}) but the configured database adapter does not ` +
+            'implement the scheduler capability. Use a canonical adapter (@byline/db-postgres or ' +
+            '@byline/db-mysql), or remove the tasks.');
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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/validate-scheduler-config.test.node.js

@@ -0,0 +1,38 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { defineRecurringTask } from './define-recurring-task.js';
+import { validateSchedulerConfig } from './validate-scheduler-config.js';
+const task = defineRecurringTask({
+    name: 'analytics.rollup',
+    intervalMs: 3_600_000,
+    leaseMs: 300_000,
+    run: async () => { },
+});
+const store = {};
+describe('validateSchedulerConfig', () => {
+    it('passes when tasks are registered against a scheduler-capable adapter', () => {
+        expect(() => validateSchedulerConfig({ tasks: [task], adapter: { scheduler: store } })).not.toThrow();
+    });
+    it('passes when no tasks are registered and the adapter lacks the capability', () => {
+        expect(() => validateSchedulerConfig({ tasks: [], adapter: {} })).not.toThrow();
+        expect(() => validateSchedulerConfig({ adapter: {} })).not.toThrow();
+    });
+    it('fails when tasks are registered against an adapter without the capability', () => {
+        expect(() => validateSchedulerConfig({ tasks: [task], adapter: {} })).toThrow(/scheduler/i);
+    });
+    it('names the offending tasks in the failure message', () => {
+        expect(() => validateSchedulerConfig({ tasks: [task], adapter: {} })).toThrow(/analytics\.rollup/);
+    });
+    it('applies task validation as part of config validation', () => {
+        expect(() => validateSchedulerConfig({
+            tasks: [{ ...task, intervalMs: 1_000 }],
+            adapter: { scheduler: store },
+        })).toThrow(/interval/i);
+    });
+});

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

@@ -0,0 +1,14 @@
+/**
+ * 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 { RecurringTaskDefinition } from './types.js';
+/**
+ * Boot-time validation of the registered task set. Throws on the first problem
+ * so a misconfigured deployment fails loudly at startup rather than silently
+ * never running work.
+ */
+export declare function validateRecurringTasks(definitions: readonly RecurringTaskDefinition[]): void;

package/dist/scheduler/validate-tasks.js

@@ -0,0 +1,40 @@
+/**
+ * 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 { MIN_INTERVAL_MS, MIN_LEASE_MS } from './define-recurring-task.js';
+function assertDuration(value, label, minimum, taskName) {
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`recurring task '${taskName}': ${label} must be a whole number of milliseconds ` +
+            `(received ${value})`);
+    }
+    if (value < minimum) {
+        throw new Error(`recurring task '${taskName}': ${label} must be at least ${minimum}ms (received ${value})`);
+    }
+}
+/**
+ * Boot-time validation of the registered task set. Throws on the first problem
+ * so a misconfigured deployment fails loudly at startup rather than silently
+ * never running work.
+ */
+export function validateRecurringTasks(definitions) {
+    const seen = new Set();
+    for (const definition of definitions) {
+        const name = definition?.name;
+        if (typeof name !== 'string' || name.trim().length === 0) {
+            throw new Error('recurring task: name must be a non-empty string');
+        }
+        if (seen.has(name)) {
+            throw new Error(`recurring task '${name}': duplicate task name`);
+        }
+        seen.add(name);
+        assertDuration(definition.intervalMs, 'intervalMs', MIN_INTERVAL_MS, name);
+        assertDuration(definition.leaseMs, 'leaseMs', MIN_LEASE_MS, name);
+        if (typeof definition.run !== 'function') {
+            throw new Error(`recurring task '${name}': run must be a function`);
+        }
+    }
+}

package/dist/scheduler/validate-tasks.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/validate-tasks.test.node.js

@@ -0,0 +1,49 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { defineRecurringTask } from './define-recurring-task.js';
+import { validateRecurringTasks } from './validate-tasks.js';
+const ok = defineRecurringTask({
+    name: 'analytics.rollup',
+    intervalMs: 3_600_000,
+    leaseMs: 300_000,
+    run: async () => { },
+});
+describe('validateRecurringTasks', () => {
+    it('accepts a valid set', () => {
+        expect(() => validateRecurringTasks([ok])).not.toThrow();
+    });
+    it('accepts an empty set', () => {
+        expect(() => validateRecurringTasks([])).not.toThrow();
+    });
+    it('rejects duplicate names', () => {
+        expect(() => validateRecurringTasks([ok, { ...ok }])).toThrow(/duplicate/i);
+    });
+    it('rejects a blank name', () => {
+        expect(() => validateRecurringTasks([{ ...ok, name: '   ' }])).toThrow(/name/i);
+    });
+    it('rejects an interval below the 60s minimum', () => {
+        expect(() => validateRecurringTasks([{ ...ok, intervalMs: 59_999 }])).toThrow(/interval/i);
+    });
+    it('rejects a lease below the 60s minimum', () => {
+        expect(() => validateRecurringTasks([{ ...ok, leaseMs: 59_999 }])).toThrow(/lease/i);
+    });
+    it('rejects non-finite durations', () => {
+        expect(() => validateRecurringTasks([{ ...ok, intervalMs: Number.NaN }])).toThrow(/interval/i);
+        expect(() => validateRecurringTasks([{ ...ok, leaseMs: Number.POSITIVE_INFINITY }])).toThrow(/lease/i);
+    });
+    it('rejects a fractional interval', () => {
+        expect(() => validateRecurringTasks([{ ...ok, intervalMs: 60_000.5 }])).toThrow(/whole number/i);
+    });
+    it('accepts a large, valid interval (30 days)', () => {
+        expect(() => validateRecurringTasks([{ ...ok, intervalMs: 30 * 86_400_000 }])).not.toThrow();
+    });
+    it('rejects a missing run function', () => {
+        expect(() => validateRecurringTasks([{ ...ok, run: undefined }])).toThrow(/run/i);
+    });
+});

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

@@ -36,6 +36,7 @@ function createMockDb(options) {
         commands: {
             collections: { create, update, delete: vi.fn(fail) },
             documents: {
+                publishSchedules: {},
                 createDocumentVersion: vi.fn(fail),
                 updateDocumentPath: vi.fn(fail),
                 setDocumentAvailableLocales: vi.fn(fail),
@@ -72,6 +73,7 @@ function createMockDb(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
+                publishSchedules: {},
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),

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

@@ -23,6 +23,7 @@ function makeAdapter(options) {
         commands: {
             collections: { create: vi.fn(fail), update: vi.fn(fail), delete: vi.fn(fail) },
             documents: {
+                publishSchedules: {},
                 createDocumentVersion: vi.fn(fail),
                 updateDocumentPath: vi.fn(fail),
                 setDocumentAvailableLocales: vi.fn(fail),
@@ -59,6 +60,7 @@ function makeAdapter(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
+                publishSchedules: {},
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),

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

@@ -12,6 +12,12 @@ export declare const AUDIT_ACTIONS: {
     readonly pathChanged: 'document.path.changed';
     readonly localesChanged: 'document.locales.changed';
     readonly statusChanged: 'document.status.changed';
+    readonly publishScheduled: 'document.publish.scheduled';
+    readonly publishRescheduled: 'document.publish.rescheduled';
+    readonly publishReconfirmed: 'document.publish.reconfirmed';
+    readonly publishScheduleCancelled: 'document.publish.schedule.cancelled';
+    readonly publishScheduleSuspended: 'document.publish.schedule.suspended';
+    readonly publishScheduleDiscarded: 'document.publish.schedule.discarded';
     readonly deleted: 'document.deleted';
     readonly treePlaced: 'document.tree.placed';
     readonly treeReparented: 'document.tree.reparented';

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

@@ -21,6 +21,12 @@ export const AUDIT_ACTIONS = {
     pathChanged: 'document.path.changed',
     localesChanged: 'document.locales.changed',
     statusChanged: 'document.status.changed',
+    publishScheduled: 'document.publish.scheduled',
+    publishRescheduled: 'document.publish.rescheduled',
+    publishReconfirmed: 'document.publish.reconfirmed',
+    publishScheduleCancelled: 'document.publish.schedule.cancelled',
+    publishScheduleSuspended: 'document.publish.schedule.suspended',
+    publishScheduleDiscarded: 'document.publish.schedule.discarded',
     deleted: 'document.deleted',
     treePlaced: 'document.tree.placed',
     treeReparented: 'document.tree.reparented',

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

@@ -12,6 +12,7 @@ import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { actorId, applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
+import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
 /**
  * Copy a document's content from one locale into another, in place on
  * the same document.
@@ -123,17 +124,21 @@ 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 db.commands.documents.createDocumentVersion({
+        const writeResult = await commitContentVersionWithScheduleSuspension({
+            ctx,
             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),
+            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),
+            }),
         });
         const documentVersionId = extractVersionId(writeResult.document);
         await invokeHook(hooks?.afterUpdate, {

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

@@ -11,6 +11,7 @@ import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { actorId, invokeHook } from './internals.js';
+import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.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
@@ -86,18 +87,25 @@ export async function deleteLocale(ctx, params) {
             collectionPath,
             deleteLocale: deleteLocaleMarker,
         });
-        const result = await db.commands.documents.deleteDocumentLocale({
+        const result = await commitContentVersionWithScheduleSuspension({
+            ctx,
             documentId: params.documentId,
-            locale: params.locale,
-            status: getDefaultStatus(definition),
-            createdBy: actorId(ctx),
+            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;
+            },
         });
-        if (result == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId, collectionPath },
-            }).log(ctx.logger);
-        }
         await invokeHook(hooks?.afterUpdate, {
             data: originalData,
             originalData,

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

@@ -11,6 +11,7 @@ import { ERR_NOT_FOUND, 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 { firePromoteTreeChange, reconcileTreeOnDeleteInTransaction } from './tree.js';
 function readErrorCode(error) {
     try {
@@ -87,6 +88,7 @@ export async function deleteDocument(ctx, params) {
         let deletedVersionCount = 0;
         let treeResult;
         await audit.withTransaction(async () => {
+            const cancelledSchedule = await cancelPublishScheduleInTransaction(ctx, params.documentId);
             deletedVersionCount = await db.commands.documents.softDeleteDocument({
                 document_id: params.documentId,
             });
@@ -100,6 +102,12 @@ export async function deleteDocument(ctx, params) {
             if (treeAudit != null) {
                 treeResult = await reconcileTreeOnDeleteInTransaction(ctx, params.documentId, treeAudit);
             }
+            await appendPublishScheduleCancellationAudit({
+                ctx,
+                audit,
+                schedule: cancelledSchedule,
+                reason: 'soft_deleted',
+            });
         });
         // Everything below is post-commit. Each operation and the logger get an
         // independent attempt; none can turn the committed delete into a rejection.

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

@@ -28,6 +28,7 @@ export { deleteDocument } from './delete.js';
 export { deleteLocale } from './delete-locale.js';
 export { duplicateDocument } from './duplicate.js';
 export { restoreDocumentVersion } from './restore.js';
+export { cancelDocumentScheduledPublish, confirmDocumentScheduledPublish, getDocumentScheduledPublish, listDocumentPublishSchedules, scheduleDocumentPublish, } from './scheduled-publish.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
 export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';

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

@@ -28,6 +28,7 @@ export { deleteDocument } from './delete.js';
 export { deleteLocale } from './delete-locale.js';
 export { duplicateDocument } from './duplicate.js';
 export { restoreDocumentVersion } from './restore.js';
+export { cancelDocumentScheduledPublish, confirmDocumentScheduledPublish, getDocumentScheduledPublish, listDocumentPublishSchedules, scheduleDocumentPublish, } from './scheduled-publish.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
 export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';