@byline/db-mysql 4.14.1 → 4.16.0

package/dist/database/schema/index.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { eq, relations, sql } from 'drizzle-orm';
-import { bigint, boolean, date, datetime, decimal, float, foreignKey, index, int, json, mysqlTable, mysqlView, primaryKey, text, time, unique, varchar, } from 'drizzle-orm/mysql-core';
+import { bigint, boolean, check, date, datetime, decimal, float, foreignKey, index, int, json, mysqlTable, mysqlView, primaryKey, text, time, unique, varchar, } from 'drizzle-orm/mysql-core';
 import { createdAt, timestamps, uuidChar, varcharByteSorted, varcharCaseSensitive, } from './common.js';
 // Every foreign key below is declared with the table-level `foreignKey()`
 // builder and an explicit, short `fk_<table>_<column>` name, rather than
@@ -115,6 +115,55 @@ export const documentVersions = mysqlTable('byline_document_versions', {
     // Ensure logical document belongs to only one collection
     index('idx_documents_document_collection').on(table.document_id, table.collection_id),
 ]);
+// Scheduled publication — one active intent row per logical document.
+// This is document lifecycle metadata, not authored/versioned content. The
+// target version is pinned until a later content write suspends the row for
+// explicit re-confirmation. See specs/2026-08-22-scheduled-publish.md.
+export const documentPublishSchedules = mysqlTable('byline_document_publish_schedules', {
+    document_id: uuidChar('document_id').primaryKey(),
+    collection_id: uuidChar('collection_id').notNull(),
+    target_version_id: uuidChar('target_version_id').notNull(),
+    publish_at: datetime('publish_at', { fsp: 6 }).notNull(),
+    state: varchar('state', { length: 32 }).notNull().default('armed'),
+    suspended_at: datetime('suspended_at', { fsp: 6 }),
+    suspended_reason: varchar('suspended_reason', { length: 32 }),
+    // Historical and current authorizers are deliberately not foreign keys:
+    // deleting an admin account must not revoke an already-authorized schedule.
+    scheduled_by: uuidChar('scheduled_by'),
+    last_authorized_by: uuidChar('last_authorized_by'),
+    last_authorized_at: datetime('last_authorized_at', { fsp: 6 }).notNull(),
+    scheduled_at: datetime('scheduled_at', { fsp: 6 }).notNull().default(sql `CURRENT_TIMESTAMP(6)`),
+    updated_at: datetime('updated_at', { fsp: 6 }).notNull().default(sql `CURRENT_TIMESTAMP(6)`),
+    execution_token: uuidChar('execution_token'),
+    execution_expires_at: datetime('execution_expires_at', { fsp: 6 }),
+    last_attempt_at: datetime('last_attempt_at', { fsp: 6 }),
+    next_attempt_at: datetime('next_attempt_at', { fsp: 6 }).notNull(),
+    attempt_count: int('attempt_count').notNull().default(0),
+    // Sanitized by the storage command and capped at 2 KiB; never stores a
+    // stack or document content.
+    last_error: text('last_error'),
+}, (table) => [
+    foreignKey({
+        name: 'fk_publish_schedules_document',
+        columns: [table.document_id],
+        foreignColumns: [documents.id],
+    }).onDelete('cascade'),
+    foreignKey({
+        name: 'fk_publish_schedules_collection',
+        columns: [table.collection_id],
+        foreignColumns: [collections.id],
+    }).onDelete('cascade'),
+    foreignKey({
+        name: 'fk_publish_schedules_target_version',
+        columns: [table.target_version_id],
+        foreignColumns: [documentVersions.id],
+    }).onDelete('cascade'),
+    check('check_publish_schedules_state', sql `${table.state} IN ('armed', 'needs_reconfirm')`),
+    check('check_publish_schedules_suspended_reason', sql `${table.suspended_reason} IS NULL OR ${table.suspended_reason} = 'content_edited'`),
+    // MySQL has no partial indexes, so state is the leading discriminator.
+    index('idx_document_publish_schedules_due').on(table.state, table.next_attempt_at, table.publish_at),
+    index('idx_document_publish_schedules_execution_expiry').on(table.execution_expires_at),
+]);
 // Document paths — one row per (logical document, content locale).
 // Promotes `path` out of the version row so per-collection uniqueness can
 // be enforced at the DB layer without colliding with the sticky
@@ -894,6 +943,37 @@ export const auditLog = mysqlTable('byline_audit_log', {
     index('idx_audit_log_action').on(table.action, table.id),
 ]);
 // ---------------------------------------------------------------------------
+// Recurring-task scheduler — byline_recurring_tasks
+// ---------------------------------------------------------------------------
+// Recurring-task scheduler (specs/2026-08-22-scheduler.md).
+// Code-registered definitions are authoritative; rows for definitions removed
+// from code are retained as dormant history and never executed.
+export const recurringTasks = mysqlTable('byline_recurring_tasks', {
+    name: varchar('name', { length: 255 }).primaryKey(),
+    // bigint: MySQL INT tops out at ~24.9 days in milliseconds, and a 30-day
+    // interval is a legitimate configuration. `mode: 'number'` is safe because
+    // boot-time validation guarantees every millisecond value is a JS safe integer.
+    interval_ms: bigint('interval_ms', { mode: 'number' }).notNull(),
+    next_run_at: datetime('next_run_at', { fsp: 6 }).notNull(),
+    // A token unique to one claim — not a stable machine id. Every health and
+    // schedule write is conditional on it, so a slow runner whose lease expired
+    // cannot overwrite a newer run.
+    lease_token: uuidChar('lease_token'),
+    // Bounded, non-secret diagnostic label (machine id + pid). Correctness never
+    // depends on owner uniqueness.
+    lease_owner: varchar('lease_owner', { length: 255 }),
+    lease_expires_at: datetime('lease_expires_at', { fsp: 6 }),
+    last_started_at: datetime('last_started_at', { fsp: 6 }),
+    last_succeeded_at: datetime('last_succeeded_at', { fsp: 6 }),
+    last_failed_at: datetime('last_failed_at', { fsp: 6 }),
+    last_duration_ms: bigint('last_duration_ms', { mode: 'number' }),
+    consecutive_failures: int('consecutive_failures').notNull().default(0),
+    last_status: varchar('last_status', { length: 32 }).notNull().default('never_run'),
+    // Sanitized message, capped at 2 KiB by the store. Full stacks go to the logger.
+    last_error: text('last_error'),
+    ...timestamps,
+});
+// ---------------------------------------------------------------------------
 // Auth schema — byline_admin_users, byline_admin_roles, etc.
 // See ./auth.ts for definitions and rationale.
 // ---------------------------------------------------------------------------

package/dist/database/schema/schema-pins.test.node.js

@@ -418,3 +418,48 @@ describe('schema pins — document-paths case-sensitive collation (project-owner
         expect(pathColumn?.getSQLType()).toBe('varchar(255) COLLATE utf8mb4_bin');
     });
 });
+describe('schema pins — scheduled publication', () => {
+    const cfg = getTableConfig(coreSchema.documentPublishSchedules);
+    it('pins one row per document and exactly the three lifecycle ownership foreign keys', () => {
+        const documentId = cfg.columns.find((column) => column.name === 'document_id');
+        expect(documentId?.primary).toBe(true);
+        const references = cfg.foreignKeys.map((foreignKey) => ({
+            name: foreignKey.getName(),
+            local: foreignKey.reference().columns.map((column) => column.name),
+            onDelete: foreignKey.onDelete,
+        }));
+        expect(references).toEqual([
+            {
+                name: 'fk_publish_schedules_document',
+                local: ['document_id'],
+                onDelete: 'cascade',
+            },
+            {
+                name: 'fk_publish_schedules_collection',
+                local: ['collection_id'],
+                onDelete: 'cascade',
+            },
+            {
+                name: 'fk_publish_schedules_target_version',
+                local: ['target_version_id'],
+                onDelete: 'cascade',
+            },
+        ]);
+    });
+    it('pins the bounded state and suspension-reason constraints', () => {
+        expect(cfg.checks.map((constraint) => constraint.name).sort()).toEqual([
+            'check_publish_schedules_state',
+            'check_publish_schedules_suspended_reason',
+        ]);
+    });
+    it('pins state as the MySQL due-index discriminator and execution-expiry recovery', () => {
+        const due = cfg.indexes.find((candidate) => candidate.config.name === 'idx_document_publish_schedules_due');
+        expect(due?.config.columns.map((column) => ('name' in column ? column.name : null))).toEqual([
+            'state',
+            'next_attempt_at',
+            'publish_at',
+        ]);
+        const expiry = cfg.indexes.find((candidate) => candidate.config.name === 'idx_document_publish_schedules_execution_expiry');
+        expect(expiry?.config.columns.map((column) => ('name' in column ? column.name : null))).toEqual(['execution_expires_at']);
+    });
+});

package/dist/index.js

@@ -13,6 +13,7 @@ import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
 import { createAuditCommands } from './modules/audit/audit-commands.js';
 import { createAuditQueries } from './modules/audit/audit-queries.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
+import { createSchedulerStore } from './modules/scheduler/scheduler-store.js';
 import { classifyError } from './modules/storage/classify-error.js';
 import { createCommandBuilders } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -85,6 +86,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
     const counterCommands = createCounterCommands(pool);
     const auditCommands = createAuditCommands(dbManager);
     const auditQueries = createAuditQueries(db);
+    const schedulerStore = createSchedulerStore(db);
     // Boot check: run lazily on the pool's first physical connection rather
     // than eagerly here, because `mysqlAdapter` is synchronous (mirroring
     // `pgAdapter`) and cannot await a round trip before returning. mysql2
@@ -144,6 +146,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
             audit: auditQueries,
         },
         withTransaction: (fn) => txManager.withTransaction(fn),
+        scheduler: schedulerStore,
         classifyError,
         drizzle: db,
         pool,

package/dist/modules/scheduler/scheduler-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+export declare function createSchedulerStore(db: DatabaseConnection): ISchedulerStore;
+export {};

package/dist/modules/scheduler/scheduler-store.js

@@ -0,0 +1,237 @@
+/**
+ * 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
+ */
+/**
+ * MySQL implementation of `ISchedulerStore` (specs/2026-08-22-scheduler.md).
+ * Every due and lease comparison uses database UTC time, and every write after
+ * a claim is fenced by the claim's token.
+ *
+ * MySQL has no `UPDATE ... RETURNING`, so `claim()` locks the eligible row,
+ * updates it, and returns the pre-claim schedule from one READ COMMITTED
+ * transaction. The transaction is deliberately store-owned rather than ambient:
+ * scheduler claims must not inherit a caller's longer transaction boundary.
+ */
+import { randomUUID } from 'node:crypto';
+import { MAX_BACKOFF_MS } from '@byline/core/scheduler';
+import { sql } from 'drizzle-orm';
+import { affectedRowCount, toDate } from '../storage/storage-utils.js';
+/** Doc comment on `ISchedulerStore.fail`: 2048 characters, never a stack trace. */
+const LAST_ERROR_MAX_LENGTH = 2048;
+/** Doc comment on `ISchedulerStore.health`: `lease_owner` capped at 255 characters. */
+const LEASE_OWNER_MAX_LENGTH = 255;
+const MAX_BACKOFF_SECONDS = MAX_BACKOFF_MS / 1000;
+function requiredDate(value, context) {
+    const date = toDate(value, context);
+    if (date === null) {
+        throw new Error(`scheduler store: ${context} unexpectedly returned null`);
+    }
+    return date;
+}
+class SchedulerStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * One conflict-tolerant upsert per definition. `interval_ms` always follows
+     * code, while an unleased `next_run_at` is only pulled earlier when the new
+     * interval would otherwise leave the task waiting too long.
+     */
+    async reconcile(tasks) {
+        for (const task of tasks) {
+            await this.db.execute(sql `
+        INSERT INTO byline_recurring_tasks (name, interval_ms, next_run_at, last_status)
+        VALUES (
+          ${task.name},
+          ${task.intervalMs},
+          TIMESTAMPADD(MICROSECOND, ${task.intervalMs} * 1000, CURRENT_TIMESTAMP(6)),
+          'never_run'
+        )
+        ON DUPLICATE KEY UPDATE
+          next_run_at = CASE
+            WHEN lease_token IS NULL
+             AND next_run_at > TIMESTAMPADD(
+               MICROSECOND,
+               ${task.intervalMs} * 1000,
+               CURRENT_TIMESTAMP(6)
+             )
+            THEN TIMESTAMPADD(MICROSECOND, ${task.intervalMs} * 1000, CURRENT_TIMESTAMP(6))
+            ELSE next_run_at
+          END,
+          interval_ms = ${task.intervalMs},
+          updated_at = CURRENT_TIMESTAMP(6)
+      `);
+        }
+    }
+    /**
+     * Atomic claim through a locking read and fenced update on one physical
+     * connection. Under READ COMMITTED, contenders blocked on `FOR UPDATE`
+     * re-check the eligibility predicate after the winner commits and return
+     * null instead of observing the stale due row.
+     */
+    async claim(params) {
+        return this.db.transaction(async (tx) => {
+            const selected = (await tx.execute(sql `
+          SELECT
+            name,
+            next_run_at AS scheduled_for,
+            CURRENT_TIMESTAMP(6) AS database_now,
+            (lease_expires_at IS NOT NULL) AS recovered_expired_lease
+          FROM byline_recurring_tasks
+          WHERE name = ${params.name}
+            AND next_run_at <= CURRENT_TIMESTAMP(6)
+            AND (lease_expires_at IS NULL OR lease_expires_at <= CURRENT_TIMESTAMP(6))
+          FOR UPDATE
+        `));
+            const row = selected[0][0];
+            if (row === undefined)
+                return null;
+            const leaseToken = randomUUID();
+            const result = await tx.execute(sql `
+          UPDATE byline_recurring_tasks SET
+            lease_token = ${leaseToken},
+            lease_owner = ${params.owner.slice(0, LEASE_OWNER_MAX_LENGTH)},
+            lease_expires_at = TIMESTAMPADD(
+              MICROSECOND,
+              ${params.leaseMs} * 1000,
+              CURRENT_TIMESTAMP(6)
+            ),
+            last_started_at = CURRENT_TIMESTAMP(6),
+            last_status = 'running',
+            updated_at = CURRENT_TIMESTAMP(6)
+          WHERE name = ${params.name}
+        `);
+            if (affectedRowCount(result) !== 1) {
+                throw new Error(`scheduler store: locked claim row '${params.name}' disappeared`);
+            }
+            return {
+                name: row.name,
+                leaseToken,
+                scheduledFor: requiredDate(row.scheduled_for, 'scheduled_for'),
+                databaseNow: requiredDate(row.database_now, 'database_now'),
+                recoveredExpiredLease: Boolean(row.recovered_expired_lease),
+            };
+        }, { isolationLevel: 'read committed' });
+    }
+    /**
+     * Do not add an expiry predicate: expiry makes a row claimable but does not
+     * invalidate the current token until another claimant replaces it.
+     */
+    async renew(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        lease_expires_at = TIMESTAMPADD(
+          MICROSECOND,
+          ${params.leaseMs} * 1000,
+          CURRENT_TIMESTAMP(6)
+        ),
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /**
+     * Complete a token-matched run and schedule from the persisted cadence.
+     * `interval_ms` is read but not assigned here, so assignment order is
+     * currently irrelevant. If a future change adds it to this SET list, keep
+     * that assignment after `next_run_at` so the persisted pre-update cadence is
+     * retained; see `fail()` for MySQL's left-to-right assignment rule.
+     */
+    async complete(params) {
+        const nextRunAt = params.workRemaining
+            ? sql `CURRENT_TIMESTAMP(6)`
+            : sql `TIMESTAMPADD(MICROSECOND, interval_ms * 1000, CURRENT_TIMESTAMP(6))`;
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        last_succeeded_at = CURRENT_TIMESTAMP(6),
+        last_status = 'succeeded',
+        last_duration_ms = ${params.durationMs},
+        consecutive_failures = 0,
+        last_error = NULL,
+        lease_token = NULL,
+        lease_owner = NULL,
+        lease_expires_at = NULL,
+        next_run_at = ${nextRunAt},
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /**
+     * Record a token-matched failure with 1, 2, 4, 8, then 15 minute backoff.
+     * MySQL evaluates single-table UPDATE assignments from left to right, so
+     * `next_run_at` intentionally reads the old `consecutive_failures` before
+     * the following assignment increments it.
+     */
+    async fail(params) {
+        const result = await this.db.execute(sql `
+      UPDATE byline_recurring_tasks SET
+        last_failed_at = CURRENT_TIMESTAMP(6),
+        last_status = 'failed',
+        last_duration_ms = ${params.durationMs},
+        last_error = ${params.error.slice(0, LAST_ERROR_MAX_LENGTH)},
+        lease_token = NULL,
+        lease_owner = NULL,
+        lease_expires_at = NULL,
+        next_run_at = TIMESTAMPADD(
+          SECOND,
+          LEAST(
+            60 * CAST(POWER(2, LEAST(consecutive_failures, 4)) AS UNSIGNED),
+            ${MAX_BACKOFF_SECONDS}
+          ),
+          CURRENT_TIMESTAMP(6)
+        ),
+        consecutive_failures = consecutive_failures + 1,
+        updated_at = CURRENT_TIMESTAMP(6)
+      WHERE name = ${params.name} AND lease_token = ${params.leaseToken}
+    `);
+        return affectedRowCount(result) === 1;
+    }
+    /** Return selected health rows, or every row when names is omitted. */
+    async health(names) {
+        if (names?.length === 0)
+            return [];
+        const whereClause = names === undefined
+            ? sql ``
+            : sql `WHERE name IN (${sql.join(names.map((name) => sql `${name}`), sql `, `)})`;
+        const result = (await this.db.execute(sql `
+      SELECT
+        name,
+        interval_ms,
+        next_run_at,
+        last_status,
+        last_started_at,
+        last_succeeded_at,
+        last_failed_at,
+        last_duration_ms,
+        consecutive_failures,
+        last_error,
+        (lease_expires_at IS NOT NULL AND lease_expires_at <= CURRENT_TIMESTAMP(6)) AS lease_expired,
+        CURRENT_TIMESTAMP(6) AS database_now
+      FROM byline_recurring_tasks
+      ${whereClause}
+      ORDER BY name
+    `));
+        return result[0].map((row) => ({
+            name: row.name,
+            intervalMs: Number(row.interval_ms),
+            nextRunAt: requiredDate(row.next_run_at, 'next_run_at'),
+            lastStatus: row.last_status,
+            lastStartedAt: toDate(row.last_started_at, 'last_started_at'),
+            lastSucceededAt: toDate(row.last_succeeded_at, 'last_succeeded_at'),
+            lastFailedAt: toDate(row.last_failed_at, 'last_failed_at'),
+            lastDurationMs: row.last_duration_ms === null ? null : Number(row.last_duration_ms),
+            consecutiveFailures: Number(row.consecutive_failures),
+            lastError: row.last_error,
+            leaseExpired: Boolean(row.lease_expired),
+            databaseNow: requiredDate(row.database_now, 'database_now'),
+        }));
+    }
+}
+export function createSchedulerStore(db) {
+    return new SchedulerStore(db);
+}

package/dist/modules/storage/publish-schedules.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 { ClaimedDocumentPublishSchedule, ConfirmDocumentPublishScheduleResult, DocumentPublishSchedule, DocumentPublishSchedulePage, DocumentPublishScheduleState, IDocumentPublishScheduleCommands, IDocumentPublishScheduleQueries, ScheduleDocumentPublishResult, SuspendDocumentPublishScheduleResult } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+import type { DBManager } from '../../lib/db-manager.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+/** MySQL scheduled-publication writes on the ambient document transaction. */
+export declare class DocumentPublishScheduleCommands implements IDocumentPublishScheduleCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    private get db();
+    private lockCurrentVersion;
+    private lockSchedule;
+    private readSchedule;
+    schedule(params: {
+        documentId: string;
+        collectionId: string;
+        expectedVersionId: string;
+        publishAt: Date;
+        actorId: string | null;
+    }): Promise<ScheduleDocumentPublishResult>;
+    confirm(params: {
+        documentId: string;
+        collectionId: string;
+        expectedVersionId: string;
+        actorId: string | null;
+    }): Promise<ConfirmDocumentPublishScheduleResult>;
+    cancel(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    suspendForContentEdit(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<SuspendDocumentPublishScheduleResult>;
+    claimDue(params: {
+        batchSize: number;
+        leaseMs: number;
+    }): Promise<ClaimedDocumentPublishSchedule[]>;
+    lockClaim(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    deleteClaim(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<boolean>;
+    suspendClaimForContentEdit(params: {
+        documentId: string;
+        executionToken: string;
+    }): Promise<boolean>;
+    /**
+     * `attempt_count` is read but not assigned, so MySQL's left-to-right SET
+     * evaluation cannot shift the backoff sequence. If it is ever assigned in
+     * this statement, keep `next_attempt_at` before that assignment.
+     */
+    releaseClaim(params: {
+        documentId: string;
+        executionToken: string;
+        error: string;
+    }): Promise<boolean>;
+}
+/** MySQL scheduled-publication reads. */
+export declare class DocumentPublishScheduleQueries implements IDocumentPublishScheduleQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    get(params: {
+        documentId: string;
+        collectionId: string;
+    }): Promise<DocumentPublishSchedule | null>;
+    list(params: {
+        collectionIds: readonly string[];
+        states?: readonly DocumentPublishScheduleState[];
+        lastAuthorizedBy?: string;
+        page: number;
+        pageSize: number;
+    }): Promise<DocumentPublishSchedulePage>;
+}
+export {};