@byline/db-mysql 4.18.0 → 5.0.0

package/dist/database/schema/index.d.ts

@@ -271,6 +271,23 @@ export declare const documents: import("drizzle-orm/mysql-core").MySqlTableWithC
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        revision: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "revision";
+            tableName: "byline_documents";
+            dataType: "number";
+            columnType: "MySqlBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: 'mysql';
 }>;
@@ -581,6 +598,23 @@ export declare const documentPublishSchedules: import("drizzle-orm/mysql-core").
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        authorized_revision: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "authorized_revision";
+            tableName: "byline_document_publish_schedules";
+            dataType: "number";
+            columnType: "MySqlBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         publish_at: import("drizzle-orm/mysql-core").MySqlColumn<{
             name: "publish_at";
             tableName: "byline_document_publish_schedules";

package/dist/database/schema/index.js

@@ -65,6 +65,8 @@ export const documents = mysqlTable('byline_documents', {
     // `backfillSourceLocales()` (boot-auto via initBylineCore).
     //
     source_locale: varchar('source_locale', { length: 10 }).notNull(),
+    // Editorial concurrency counter; content versions remain independently immutable.
+    revision: bigint('revision', { mode: 'number' }).notNull(),
     ...timestamps,
 }, (table) => [
     foreignKey({
@@ -72,6 +74,7 @@ export const documents = mysqlTable('byline_documents', {
         columns: [table.collection_id],
         foreignColumns: [collections.id],
     }).onDelete('cascade'),
+    check('check_documents_revision', sql `${table.revision} BETWEEN 1 AND 9007199254740991`),
     index('idx_documents_collection').on(table.collection_id),
     index('idx_documents_collection_order').on(table.collection_id, table.order_key),
     unique('uq_documents_collection_id_id').on(table.collection_id, table.id),
@@ -137,6 +140,7 @@ export const documentPublishSchedules = mysqlTable('byline_document_publish_sche
     document_id: uuidChar('document_id').primaryKey(),
     collection_id: uuidChar('collection_id').notNull(),
     target_version_id: uuidChar('target_version_id').notNull(),
+    authorized_revision: bigint('authorized_revision', { mode: 'number' }),
     publish_at: datetime('publish_at', { fsp: 6 }).notNull(),
     state: varchar('state', { length: 32 }).notNull().default('armed'),
     suspended_at: datetime('suspended_at', { fsp: 6 }),
@@ -157,6 +161,7 @@ export const documentPublishSchedules = mysqlTable('byline_document_publish_sche
     // stack or document content.
     last_error: text('last_error'),
 }, (table) => [
+    check('check_publish_schedules_authorized_revision', sql `${table.authorized_revision} IS NULL OR ${table.authorized_revision} BETWEEN 1 AND 9007199254740991`),
     foreignKey({
         name: 'fk_publish_schedules_document',
         columns: [table.document_id],
@@ -173,7 +178,7 @@ export const documentPublishSchedules = mysqlTable('byline_document_publish_sche
         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'`),
+    check('check_publish_schedules_suspended_reason', sql `${table.suspended_reason} IS NULL OR ${table.suspended_reason} IN ('content_edited', 'document_metadata_changed', 'upgrade_invalidated')`),
     // 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),

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

@@ -448,6 +448,7 @@ describe('schema pins — scheduled publication', () => {
     });
     it('pins the bounded state and suspension-reason constraints', () => {
         expect(cfg.checks.map((constraint) => constraint.name).sort()).toEqual([
+            'check_publish_schedules_authorized_revision',
             'check_publish_schedules_state',
             'check_publish_schedules_suspended_reason',
         ]);
@@ -485,3 +486,16 @@ describe('schema pins — singleton documents', () => {
         expect(ownershipForeignKey?.onDelete).toBe('cascade');
     });
 });
+describe('schema pins — document revisions', () => {
+    it('requires an explicit safe-range revision on every new document', () => {
+        expect(coreSchema.documents.revision.getSQLType()).toBe('bigint');
+        expect(coreSchema.documents.revision.notNull).toBe(true);
+        expect(coreSchema.documents.revision.hasDefault).toBe(false);
+        expect(getTableConfig(coreSchema.documents).checks.map((constraint) => constraint.name)).toContain('check_documents_revision');
+    });
+    it('allows legacy schedules to have no prior document authorization', () => {
+        expect(coreSchema.documentPublishSchedules.authorized_revision.getSQLType()).toBe('bigint');
+        expect(coreSchema.documentPublishSchedules.authorized_revision.notNull).toBe(false);
+        expect(coreSchema.documentPublishSchedules.authorized_revision.hasDefault).toBe(false);
+    });
+});

package/dist/index.js

@@ -15,6 +15,8 @@ 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 { DocumentRevisions } from './modules/storage/document-revisions.js';
+import { createReadSnapshot } from './modules/storage/read-snapshot.js';
 import { SingletonCommands, SingletonQueries } from './modules/storage/singletons.js';
 import { createCommandBuilders } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -151,6 +153,8 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
             singletons: singletonQueries,
         },
         withTransaction: (fn) => txManager.withTransaction(fn),
+        withReadSnapshot: createReadSnapshot(db, collections, defaultContentLocale),
+        revisions: new DocumentRevisions(dbManager),
         scheduler: schedulerStore,
         classifyError,
         drizzle: db,

package/dist/lib/db-manager.d.ts

@@ -27,14 +27,24 @@ export interface DBManager {
     get(): DBExecutor;
     /** Whether the current async context owns an ambient transaction. */
     isInTransaction(): boolean;
+    getTransactionScope(): object | undefined;
+    getTransactionToken(): object | undefined;
+    isTransactionTokenActive(token: object): boolean;
+    runInTransaction<T>(executor: DBExecutor, fn: () => Promise<T>): Promise<T>;
 }
 export declare class DBManagerImpl implements DBManager {
+    private readonly transactionALS;
+    private readonly activeTransactions;
     private readonly dbPool;
     constructor(deps: {
         dbPool: DBExecutor;
     });
     get(): DBExecutor;
     isInTransaction(): boolean;
+    getTransactionScope(): object | undefined;
+    getTransactionToken(): object | undefined;
+    isTransactionTokenActive(token: object): boolean;
+    runInTransaction<T>(executor: DBExecutor, fn: () => Promise<T>): Promise<T>;
 }
 export interface TXManager {
     /**

package/dist/lib/db-manager.js

@@ -17,17 +17,42 @@
  * `withTransaction` capability on `IDbAdapter`, never the implementation.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-const transactionALS = new AsyncLocalStorage();
+import { DbErrorCodes, ERR_LOCK_CONFLICT } from '@byline/core';
+import { classifyError } from '../modules/storage/classify-error.js';
 export class DBManagerImpl {
+    transactionALS = new AsyncLocalStorage();
+    activeTransactions = new WeakSet();
     dbPool;
     constructor(deps) {
         this.dbPool = deps.dbPool;
     }
     get() {
-        return transactionALS.getStore() ?? this.dbPool;
+        return this.transactionALS.getStore()?.executor ?? this.dbPool;
     }
     isInTransaction() {
-        return transactionALS.getStore() != null;
+        return this.getTransactionToken() != null;
+    }
+    getTransactionScope() {
+        return this.getTransactionToken() != null ? this.transactionALS.getStore()?.scope : undefined;
+    }
+    getTransactionToken() {
+        const frame = this.transactionALS.getStore();
+        return frame != null && this.activeTransactions.has(frame) ? frame : undefined;
+    }
+    isTransactionTokenActive(token) {
+        return this.activeTransactions.has(token);
+    }
+    async runInTransaction(executor, fn) {
+        // Share lock ordering with savepoints. Observations issued inside a savepoint
+        // expire when it ends: rollback can release the row locks it acquired.
+        const frame = { executor, scope: this.getTransactionScope() ?? {} };
+        this.activeTransactions.add(frame);
+        try {
+            return await this.transactionALS.run(frame, fn);
+        }
+        finally {
+            this.activeTransactions.delete(frame);
+        }
     }
 }
 export class TXManagerImpl {
@@ -35,18 +60,50 @@ export class TXManagerImpl {
     constructor(deps) {
         this.db = deps.db;
     }
-    withTransaction(fn) {
-        return this.db.get().transaction((tx) => 
-        // `tx` is Drizzle's MySqlTransaction; it carries the full
-        // query-builder surface every command uses. The cast bridges the
-        // structural gap to MySql2Database the same way the pg adapter
-        // bridges to NodePgDatabase. See docs/03-architecture/03-transactions.md.
-        transactionALS.run(tx, fn), {
-            // Spec decision: pin the isolation level to match the pg adapter's
-            // assumptions (Postgres's default is READ COMMITTED; MySQL/InnoDB
-            // defaults to REPEATABLE READ). Canonical adapters must behave
-            // identically for the shared db-conformance suite.
-            isolationLevel: 'read committed',
-        });
+    async withTransaction(fn) {
+        const ownsTransaction = !this.db.isInTransaction();
+        let callbackError;
+        let callbackFailed = false;
+        const guarded = async () => {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                callbackFailed = true;
+                callbackError = error;
+                throw error;
+            }
+        };
+        try {
+            return await this.db.get().transaction((tx) => 
+            // `tx` is Drizzle's MySqlTransaction; it carries the full
+            // query-builder surface every command uses. The cast bridges the
+            // structural gap to MySql2Database the same way the pg adapter
+            // bridges to NodePgDatabase. See docs/03-architecture/03-transactions.md.
+            this.db.runInTransaction(tx, guarded), {
+                // Spec decision: pin the isolation level to match the pg adapter's
+                // assumptions (Postgres's default is READ COMMITTED; MySQL/InnoDB
+                // defaults to REPEATABLE READ). Canonical adapters must behave
+                // identically for the shared db-conformance suite.
+                isolationLevel: 'read committed',
+            });
+        }
+        catch (error) {
+            // Drizzle rethrows the callback error only after ROLLBACK succeeds. A
+            // rollback failure replaces it; a COMMIT failure has no callback error.
+            // Never infer safe retry from either of those uncertain outcomes, nor
+            // from a savepoint rollback inside an externally owned transaction.
+            if (ownsTransaction &&
+                callbackFailed &&
+                error === callbackError &&
+                classifyError(error).code === DbErrorCodes.LOCK_CONFLICT) {
+                throw ERR_LOCK_CONFLICT({
+                    message: 'This change could not be saved because another operation was using the document. Reload before trying again.',
+                    cause: error,
+                    details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+                });
+            }
+            throw error;
+        }
     }
 }

package/dist/lib/db-manager.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/db-manager.test.node.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
+describe('adapter transaction ownership', () => {
+    it('does not leak one adapter transaction into another adapter pool', async () => {
+        const poolA = {};
+        const poolB = {};
+        const tx = {};
+        const a = new DBManagerImpl({ dbPool: poolA });
+        const b = new DBManagerImpl({ dbPool: poolB });
+        await a.runInTransaction(tx, async () => {
+            expect(a.get()).toBe(tx);
+            expect(a.isInTransaction()).toBe(true);
+            expect(b.get()).toBe(poolB);
+            expect(b.isInTransaction()).toBe(false);
+            expect(b.getTransactionScope()).toBeUndefined();
+        });
+        expect(a.get()).toBe(poolA);
+        expect(a.getTransactionScope()).toBeUndefined();
+    });
+    it('preserves root scope through savepoints and restores the parent executor', async () => {
+        const pool = {};
+        const outer = {};
+        const inner = {};
+        const manager = new DBManagerImpl({ dbPool: pool });
+        await manager.runInTransaction(outer, async () => {
+            const scope = manager.getTransactionScope();
+            await expect(manager.runInTransaction(inner, async () => {
+                expect(manager.get()).toBe(inner);
+                expect(manager.getTransactionScope()).toBe(scope);
+                throw new Error('rollback');
+            })).rejects.toThrow('rollback');
+            expect(manager.get()).toBe(outer);
+            expect(manager.getTransactionScope()).toBe(scope);
+        });
+    });
+});
+describe('owned transaction lock failures', () => {
+    const conflict = () => Object.assign(new Error('driver SQL detail'), { errno: 1213 });
+    for (const outcome of ['rollback', 'rollback failure', 'commit failure', 'nested']) {
+        it(`only marks confirmed whole rollback retryable: ${outcome}`, async () => {
+            const original = conflict();
+            const replacement = new Error('connection lost');
+            let rollbackCompleted = false;
+            const executor = {
+                transaction: async (fn) => {
+                    let result;
+                    try {
+                        result = await fn(executor);
+                    }
+                    catch (error) {
+                        if (outcome === 'rollback failure')
+                            throw replacement;
+                        rollbackCompleted = true;
+                        throw error;
+                    }
+                    if (outcome === 'commit failure')
+                        throw original;
+                    return result;
+                },
+            };
+            const db = new DBManagerImpl({ dbPool: executor });
+            const manager = new TXManagerImpl({ db });
+            const operation = () => manager.withTransaction(async () => {
+                if (outcome !== 'commit failure')
+                    throw original;
+                return 'ok';
+            });
+            const pending = outcome === 'nested' ? db.runInTransaction(executor, operation) : operation();
+            if (outcome === 'rollback') {
+                await expect(pending).rejects.toMatchObject({
+                    code: 'ERR_LOCK_CONFLICT',
+                    details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+                    cause: original,
+                });
+                expect(rollbackCompleted).toBe(true);
+            }
+            else {
+                await expect(pending).rejects.toBe(outcome === 'rollback failure' ? replacement : original);
+            }
+        });
+    }
+});

package/dist/lib/revision-schema.d.ts

@@ -0,0 +1,2 @@
+import type { DBExecutor } from './db-manager.js';
+export declare function assertRevisionSchema(db: DBExecutor): Promise<void>;

package/dist/lib/revision-schema.js

@@ -0,0 +1,63 @@
+import { ERR_DATABASE } from '@byline/core';
+import { sql } from 'drizzle-orm';
+// Catalogue renderers add parentheses, casts, charset introducers, and escaped quotes.
+// Compare complete normalized expressions, not just constraint names or bound substrings.
+function normalize(clause) {
+    return clause
+        .toLowerCase()
+        .replace(/::(?:character varying|bigint|integer|text)(?:\[\])?/g, '')
+        .replace(/_utf8mb[34]/g, '')
+        .replace(/^check/, '')
+        .replace(/[\s()[\]`'"\\]/g, '');
+}
+export async function assertRevisionSchema(db) {
+    const upgrade = 'Byline document revision schema is incompatible. Fence all writers/workers, upgrade both packages and schema using 0005_document-revisions.sql, and rerun startup validation before reopening traffic.';
+    try {
+        const columnResult = await db.execute(sql `SELECT TABLE_NAME AS table_name, COLUMN_NAME AS column_name,
+      CASE WHEN DATA_TYPE = 'bigint' AND COLUMN_TYPE NOT LIKE '%unsigned%' AND COLUMN_DEFAULT IS NULL
+        AND IS_NULLABLE = CASE WHEN COLUMN_NAME = 'revision' THEN 'NO' ELSE 'YES' END
+        AND EXTRA = '' THEN 1 ELSE 0 END AS valid
+      FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND ((table_name = 'byline_documents' AND column_name = 'revision') OR (table_name = 'byline_document_publish_schedules' AND column_name = 'authorized_revision'))`);
+        const checkResult = await db.execute(sql `SELECT t.CONSTRAINT_NAME AS name, c.CHECK_CLAUSE AS clause, (t.ENFORCED = 'YES') AS valid
+      FROM information_schema.TABLE_CONSTRAINTS t JOIN information_schema.CHECK_CONSTRAINTS c
+        ON c.CONSTRAINT_SCHEMA = t.CONSTRAINT_SCHEMA AND c.CONSTRAINT_NAME = t.CONSTRAINT_NAME
+      WHERE t.CONSTRAINT_SCHEMA = DATABASE() AND t.TABLE_NAME IN ('byline_documents', 'byline_document_publish_schedules') AND t.CONSTRAINT_TYPE = 'CHECK'`);
+        const columns = columnResult[0];
+        const checks = checkResult[0];
+        if (columns.length !== 2 || columns.some((column) => Number(column.valid) !== 1))
+            throw new Error('Required BIGINT columns must have the correct nullability and no default.');
+        const required = [
+            [
+                'check_documents_revision',
+                [
+                    'revision BETWEEN 1 AND 9007199254740991',
+                    'revision >= 1 AND revision <= 9007199254740991',
+                ],
+            ],
+            [
+                'check_publish_schedules_authorized_revision',
+                [
+                    'authorized_revision IS NULL OR authorized_revision BETWEEN 1 AND 9007199254740991',
+                    'authorized_revision IS NULL OR authorized_revision >= 1 AND authorized_revision <= 9007199254740991',
+                ],
+            ],
+            [
+                'check_publish_schedules_suspended_reason',
+                [
+                    "suspended_reason IS NULL OR suspended_reason IN ('content_edited', 'document_metadata_changed', 'upgrade_invalidated')",
+                    "suspended_reason IS NULL OR suspended_reason = ANY (ARRAY['content_edited', 'document_metadata_changed', 'upgrade_invalidated'])",
+                ],
+            ],
+        ];
+        for (const [name, expressions] of required) {
+            const check = checks.find((row) => row.name === name);
+            if (check == null ||
+                Number(check.valid) !== 1 ||
+                !expressions.some((expression) => normalize(expression) === normalize(check.clause)))
+                throw new Error(`Missing or incompatible enforced check: ${name}`);
+        }
+    }
+    catch (cause) {
+        throw ERR_DATABASE({ message: upgrade, cause });
+    }
+}

package/dist/modules/storage/classify-error.js

@@ -50,6 +50,9 @@ export function classifyError(err) {
             const match = typeof e.message === 'string' ? e.message.match(/CONSTRAINT [`']([^`']+)[`']/) : null;
             return { code: DbErrorCodes.FOREIGN_KEY_VIOLATION, constraint: match?.[1] };
         }
+        if (e.errno === 1213 || e.errno === 1205) {
+            return { code: DbErrorCodes.LOCK_CONFLICT };
+        }
         e = e.cause;
     }
     return { code: DbErrorCodes.UNKNOWN };

package/dist/modules/storage/classify-error.test.node.js

@@ -99,3 +99,11 @@ runClassifyErrorContract([
         unrelatedError: { code: 'ER_DATA_TOO_LONG', errno: 1406, sqlState: '22001' },
     },
 ]);
+describe('lock conflict classification', () => {
+    it.each([1213, 1205])('classifies driver lock failure %s through a cause', (value) => {
+        expect(classifyError({ cause: { errno: value } })).toEqual({ code: 'DB_LOCK_CONFLICT' });
+    });
+    it('does not classify connection loss as safe contention', () => {
+        expect(classifyError({ code: 'ECONNRESET', errno: 2013 })).toEqual({ code: 'DB_UNKNOWN' });
+    });
+});

package/dist/modules/storage/collection-registration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { DBManager } from '../../lib/db-manager.js';
+export declare function lockCollectionRegistration(dbManager: DBManager, collectionId: string, mode: 'shared' | 'exclusive'): Promise<void>;

package/dist/modules/storage/collection-registration.js

@@ -0,0 +1,32 @@
+/**
+ * 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 { ERR_DATABASE, ERR_NOT_FOUND, ERR_VALIDATION } from '@byline/core';
+import { sql } from 'drizzle-orm';
+export async function lockCollectionRegistration(dbManager, collectionId, mode) {
+    if (mode !== 'shared' && mode !== 'exclusive') {
+        throw ERR_VALIDATION({ message: 'Invalid collection registration lock mode' });
+    }
+    if (!dbManager.isInTransaction()) {
+        throw ERR_DATABASE({
+            message: 'collection registration locks require an active transaction',
+            details: { collectionId },
+        });
+    }
+    const locked = await dbManager.get().execute(sql `
+      SELECT id FROM byline_collections
+      WHERE id = ${collectionId}
+      ${mode === 'exclusive' ? sql `FOR UPDATE` : sql `FOR SHARE`}
+    `);
+    const rows = locked[0];
+    if (rows.length === 0) {
+        throw ERR_NOT_FOUND({
+            message: 'collection registration not found',
+            details: { collectionId },
+        });
+    }
+}

package/dist/modules/storage/document-revisions.d.ts

@@ -0,0 +1,20 @@
+import { type DocumentRevisionReceipt, type DocumentRevisionStore, type DocumentRevisionTarget, type DocumentStructuralState, type LockedDocumentRevision } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+export declare class DocumentRevisions implements DocumentRevisionStore {
+    private readonly manager;
+    private readonly issued;
+    private readonly lockOrder;
+    private readonly acquiring;
+    constructor(manager: DBManager);
+    readStructure(params: {
+        collectionId: string;
+        documentIds?: readonly string[];
+        parentDocumentId?: string;
+    }): Promise<DocumentStructuralState[]>;
+    isInTransaction(): boolean;
+    assertCompatibleSchema(): Promise<void>;
+    private scope;
+    lock(targets: readonly DocumentRevisionTarget[]): Promise<readonly LockedDocumentRevision[]>;
+    private lockSequentially;
+    advance(locked: LockedDocumentRevision): Promise<DocumentRevisionReceipt>;
+}

package/dist/modules/storage/document-revisions.js

@@ -0,0 +1,197 @@
+import { assertDocumentVersionParent, documentRevisionFromDatabase, ERR_DATABASE, ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ERR_VALIDATION, parseDocumentRevision, } from '@byline/core';
+import { and, desc, eq, sql } from 'drizzle-orm';
+import { documentAvailableLocales, documentPaths, documents, documentVersions, } from '../../database/schema/index.js';
+import { assertRevisionSchema } from '../../lib/revision-schema.js';
+export class DocumentRevisions {
+    manager;
+    issued = new WeakMap();
+    lockOrder = new WeakMap();
+    acquiring = new WeakSet();
+    constructor(manager) {
+        this.manager = manager;
+    }
+    async readStructure(params) {
+        this.scope();
+        const ids = params.documentIds ?? [];
+        const filtered = params.documentIds !== undefined || params.parentDocumentId !== undefined;
+        const selection = ids.length
+            ? sql `d.id IN (${sql.join(ids.map((id) => sql `${id}`), sql `, `)})`
+            : sql `FALSE`;
+        const result = await this.manager.get().execute(sql `
+      SELECT d.id, d.revision, d.order_key,
+        r.child_document_id, r.parent_document_id, r.order_key AS tree_order_key,
+        EXISTS (SELECT 1 FROM byline_document_versions v WHERE v.document_id = d.id AND v.is_deleted = false) AS live
+      FROM byline_documents d
+      LEFT JOIN byline_document_relationships r ON r.child_document_id = d.id
+      WHERE d.collection_id = ${params.collectionId}
+        AND (${!filtered} OR ${selection} OR r.parent_document_id = ${params.parentDocumentId ?? null})
+      ORDER BY d.id
+    `);
+        const rows = result[0];
+        return rows.map((row) => ({
+            documentId: row.id,
+            revision: documentRevisionFromDatabase(row.revision),
+            orderKey: row.order_key,
+            placed: row.child_document_id !== null,
+            parentDocumentId: row.parent_document_id,
+            treeOrderKey: row.tree_order_key,
+            live: Boolean(row.live),
+        }));
+    }
+    isInTransaction() {
+        return this.manager.isInTransaction();
+    }
+    assertCompatibleSchema() {
+        return assertRevisionSchema(this.manager.get());
+    }
+    scope() {
+        const scope = this.manager.getTransactionScope();
+        if (scope == null)
+            throw ERR_DATABASE({
+                message: 'Document revision primitives require an active adapter transaction.',
+            });
+        return scope;
+    }
+    async lock(targets) {
+        const scope = this.scope();
+        if (this.acquiring.has(scope))
+            throw ERR_DATABASE({
+                message: 'Concurrent document lock requests inside one transaction are not allowed.',
+            });
+        this.acquiring.add(scope);
+        try {
+            return await this.lockSequentially(targets, scope);
+        }
+        finally {
+            this.acquiring.delete(scope);
+        }
+    }
+    async lockSequentially(targets, scope) {
+        const token = this.manager.getTransactionToken();
+        // Validate all caller values before acquiring even the first lock.
+        const ordered = targets
+            .map((target) => {
+            if (![target.documentId, target.collectionId].every((id) => typeof id === 'string' &&
+                /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))) {
+                throw ERR_VALIDATION({
+                    message: 'Revision targets require valid document and collection UUIDs.',
+                });
+            }
+            return {
+                ...target,
+                documentId: target.documentId.toLowerCase(),
+                collectionId: target.collectionId.toLowerCase(),
+                expectedRevision: parseDocumentRevision(target.expectedRevision),
+            };
+        })
+            .sort((a, b) => (a.documentId < b.documentId ? -1 : a.documentId > b.documentId ? 1 : 0));
+        if (new Set(ordered.map((target) => target.documentId)).size !== ordered.length) {
+            throw ERR_VALIDATION({ message: 'Duplicate document revision lock targets are not allowed.' });
+        }
+        const last = this.lockOrder.get(scope);
+        if (last != null && ordered.some((target) => target.documentId <= last)) {
+            throw ERR_DATABASE({
+                message: 'Document revision locks must be acquired once in increasing document identity order, including across savepoints.',
+            });
+        }
+        const executor = this.manager.get();
+        const locked = [];
+        for (const target of ordered) {
+            const [document] = await executor
+                .select({
+                revision: sql `${documents.revision}`,
+                sourceLocale: documents.source_locale,
+            })
+                .from(documents)
+                .where(and(eq(documents.id, target.documentId), eq(documents.collection_id, target.collectionId)))
+                .for('update');
+            this.lockOrder.set(scope, target.documentId);
+            if (document == null)
+                throw ERR_NOT_FOUND({ message: 'Document is unavailable.' });
+            const [current] = await executor
+                .select({ id: documentVersions.id, status: documentVersions.status })
+                .from(documentVersions)
+                .where(and(eq(documentVersions.document_id, target.documentId), eq(documentVersions.is_deleted, false)))
+                .orderBy(desc(documentVersions.id))
+                .limit(1);
+            if (current == null) {
+                const [anyVersion] = await executor
+                    .select({ id: documentVersions.id })
+                    .from(documentVersions)
+                    .where(eq(documentVersions.document_id, target.documentId))
+                    .limit(1);
+                if (anyVersion != null)
+                    throw ERR_NOT_FOUND({ message: 'Document is unavailable.' });
+            }
+            const revision = documentRevisionFromDatabase(document.revision);
+            if (revision !== target.expectedRevision)
+                throw ERR_DOCUMENT_STALE({
+                    message: 'This document has changed. Reload it before making further changes.',
+                    details: {
+                        reason: 'revision_mismatch',
+                        documentId: target.documentId,
+                        expectedRevision: target.expectedRevision,
+                        currentRevision: revision,
+                    },
+                });
+            assertDocumentVersionParent({
+                documentId: target.documentId,
+                locale: target.locale,
+                previousVersionId: target.previousVersionId,
+                currentVersionId: current?.id ?? null,
+            });
+            const [path] = await executor
+                .select({ path: documentPaths.path })
+                .from(documentPaths)
+                .where(and(eq(documentPaths.document_id, target.documentId), eq(documentPaths.locale, document.sourceLocale)))
+                .limit(1);
+            const locales = await executor
+                .select({ locale: documentAvailableLocales.locale })
+                .from(documentAvailableLocales)
+                .where(eq(documentAvailableLocales.document_id, target.documentId));
+            const observation = Object.freeze({
+                documentId: target.documentId,
+                collectionId: target.collectionId,
+                revision,
+                currentVersionId: current?.id ?? null,
+                status: current?.status ?? null,
+                sourceLocale: document.sourceLocale,
+                path: path?.path ?? null,
+                availableLocales: Object.freeze(locales.map((row) => row.locale).sort()),
+            });
+            this.issued.set(observation, {
+                scope,
+                token,
+                documentId: target.documentId,
+                collectionId: target.collectionId,
+                revision,
+            });
+            locked.push(observation);
+        }
+        return Object.freeze(locked);
+    }
+    async advance(locked) {
+        const scope = this.scope();
+        const original = this.issued.get(locked);
+        if (original == null ||
+            original.scope !== scope ||
+            !this.manager.isTransactionTokenActive(original.token))
+            throw ERR_DATABASE({
+                message: 'Document revision observation does not belong to this active transaction.',
+            });
+        if (original.revision === Number.MAX_SAFE_INTEGER)
+            throw ERR_DATABASE({
+                message: 'Document revision exhausted its safe integer range; the mutation was not committed.',
+            });
+        const next = original.revision + 1;
+        const executor = this.manager.get();
+        const predicate = and(eq(documents.id, original.documentId), eq(documents.collection_id, original.collectionId), eq(documents.revision, original.revision));
+        const [changed] = await executor.update(documents).set({ revision: next }).where(predicate);
+        const count = changed.affectedRows;
+        if (count !== 1)
+            throw ERR_DATABASE({
+                message: 'Locked document revision was already advanced or changed; roll back the mutation.',
+            });
+        return { documentId: original.documentId, revision: next };
+    }
+}

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

@@ -15,6 +15,7 @@ export declare class DocumentPublishScheduleCommands implements IDocumentPublish
     private dbManager;
     constructor(dbManager: DBManager);
     private get db();
+    lockDocuments(documentIds: readonly string[]): Promise<void>;
     private lockCurrentVersion;
     private lockSchedule;
     private readSchedule;
@@ -22,6 +23,7 @@ export declare class DocumentPublishScheduleCommands implements IDocumentPublish
         documentId: string;
         collectionId: string;
         expectedVersionId: string;
+        authorizedRevision: number;
         publishAt: Date;
         actorId: string | null;
     }): Promise<ScheduleDocumentPublishResult>;
@@ -29,6 +31,7 @@ export declare class DocumentPublishScheduleCommands implements IDocumentPublish
         documentId: string;
         collectionId: string;
         expectedVersionId: string;
+        authorizedRevision: number;
         actorId: string | null;
     }): Promise<ConfirmDocumentPublishScheduleResult>;
     cancel(params: {
@@ -38,6 +41,7 @@ export declare class DocumentPublishScheduleCommands implements IDocumentPublish
     suspendForContentEdit(params: {
         documentId: string;
         collectionId: string;
+        reason?: 'content_edited' | 'document_metadata_changed';
     }): Promise<SuspendDocumentPublishScheduleResult>;
     claimDue(params: {
         batchSize: number;
@@ -52,6 +56,7 @@ export declare class DocumentPublishScheduleCommands implements IDocumentPublish
         executionToken: string;
     }): Promise<boolean>;
     suspendClaimForContentEdit(params: {
+        reason?: 'content_edited' | 'document_metadata_changed';
         documentId: string;
         executionToken: string;
     }): Promise<boolean>;

package/dist/modules/storage/publish-schedules.js

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { randomUUID } from 'node:crypto';
+import { documentRevisionFromDatabase, parseDocumentRevision } from '@byline/core';
 import { sql } from 'drizzle-orm';
 import { affectedRowCount, toDate } from './storage-utils.js';
 const LAST_ERROR_MAX_LENGTH = 2_048;
@@ -17,6 +18,9 @@ function requiredDate(value, column) {
 }
 function toSchedule(row) {
     return {
+        authorizedRevision: row.authorized_revision == null
+            ? null
+            : documentRevisionFromDatabase(row.authorized_revision),
         documentId: row.document_id,
         collectionId: row.collection_id,
         targetVersionId: row.target_version_id,
@@ -58,6 +62,13 @@ export class DocumentPublishScheduleCommands {
     get db() {
         return this.dbManager.get();
     }
+    async lockDocuments(documentIds) {
+        if (!this.dbManager.isInTransaction())
+            throw new Error('Schedule locks require an active transaction');
+        for (const documentId of [...new Set(documentIds)].sort()) {
+            await this.db.execute(sql `SELECT document_id FROM byline_document_publish_schedules WHERE document_id = ${documentId} FOR UPDATE`);
+        }
+    }
     async lockCurrentVersion(params) {
         const document = await this.db.execute(sql `
       SELECT id
@@ -99,6 +110,7 @@ export class DocumentPublishScheduleCommands {
         return toSchedule(row);
     }
     async schedule(params) {
+        params = { ...params, authorizedRevision: parseDocumentRevision(params.authorizedRevision) };
         const currentVersionId = await this.lockCurrentVersion(params);
         if (currentVersionId === null)
             return { status: 'document_not_found' };
@@ -119,7 +131,7 @@ export class DocumentPublishScheduleCommands {
         if (previous === null) {
             await this.db.execute(sql `
         INSERT INTO byline_document_publish_schedules (
-          document_id, collection_id, target_version_id, publish_at,
+          document_id, collection_id, target_version_id, authorized_revision, publish_at,
           state, suspended_at, suspended_reason,
           scheduled_by, last_authorized_by, last_authorized_at,
           execution_token, execution_expires_at, last_attempt_at,
@@ -128,6 +140,7 @@ export class DocumentPublishScheduleCommands {
           ${params.documentId},
           ${params.collectionId},
           ${params.expectedVersionId},
+          ${params.authorizedRevision},
           ${params.publishAt},
           'armed', NULL, NULL,
           ${params.actorId}, ${params.actorId}, CURRENT_TIMESTAMP(6),
@@ -140,6 +153,7 @@ export class DocumentPublishScheduleCommands {
             await this.db.execute(sql `
         UPDATE byline_document_publish_schedules SET
           target_version_id = ${params.expectedVersionId},
+          authorized_revision = ${params.authorizedRevision},
           publish_at = ${params.publishAt},
           state = 'armed',
           suspended_at = NULL,
@@ -159,6 +173,7 @@ export class DocumentPublishScheduleCommands {
         return { status: 'scheduled', schedule: await this.readSchedule(params.documentId), previous };
     }
     async confirm(params) {
+        params = { ...params, authorizedRevision: parseDocumentRevision(params.authorizedRevision) };
         const currentVersionId = await this.lockCurrentVersion(params);
         if (currentVersionId === null || currentVersionId !== params.expectedVersionId) {
             return { status: 'version_mismatch' };
@@ -172,6 +187,7 @@ export class DocumentPublishScheduleCommands {
         await this.db.execute(sql `
       UPDATE byline_document_publish_schedules SET
         target_version_id = ${params.expectedVersionId},
+          authorized_revision = ${params.authorizedRevision},
         state = 'armed',
         suspended_at = NULL,
         suspended_reason = NULL,
@@ -214,7 +230,7 @@ export class DocumentPublishScheduleCommands {
       UPDATE byline_document_publish_schedules SET
         state = 'needs_reconfirm',
         suspended_at = CURRENT_TIMESTAMP(6),
-        suspended_reason = 'content_edited',
+        suspended_reason = ${params.reason ?? 'content_edited'},
         execution_token = NULL,
         execution_expires_at = NULL,
         updated_at = CURRENT_TIMESTAMP(6)
@@ -291,6 +307,8 @@ export class DocumentPublishScheduleCommands {
       FROM byline_document_publish_schedules
       WHERE document_id = ${params.documentId}
         AND execution_token = ${params.executionToken}
+        AND state = 'armed'
+        AND execution_expires_at > CURRENT_TIMESTAMP(6)
       FOR UPDATE
     `);
         const row = firstRow(result);
@@ -301,6 +319,7 @@ export class DocumentPublishScheduleCommands {
       DELETE FROM byline_document_publish_schedules
       WHERE document_id = ${params.documentId}
         AND execution_token = ${params.executionToken}
+        AND state = 'armed' AND execution_expires_at > CURRENT_TIMESTAMP(6)
     `);
         return affectedRowCount(result) === 1;
     }
@@ -309,7 +328,7 @@ export class DocumentPublishScheduleCommands {
       UPDATE byline_document_publish_schedules SET
         state = 'needs_reconfirm',
         suspended_at = CURRENT_TIMESTAMP(6),
-        suspended_reason = 'content_edited',
+        suspended_reason = ${params.reason ?? 'content_edited'},
         execution_token = NULL,
         execution_expires_at = NULL,
         last_attempt_at = NULL,
@@ -319,6 +338,7 @@ export class DocumentPublishScheduleCommands {
         updated_at = CURRENT_TIMESTAMP(6)
       WHERE document_id = ${params.documentId}
         AND execution_token = ${params.executionToken}
+        AND state = 'armed' AND execution_expires_at > CURRENT_TIMESTAMP(6)
     `);
         return affectedRowCount(result) === 1;
     }

package/dist/modules/storage/read-snapshot.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionDefinition, IDbAdapter } from '@byline/core';
+import type { DBExecutor } from '../../lib/db-manager.js';
+export declare function createReadSnapshot(db: DBExecutor, collections: readonly CollectionDefinition[], defaultLocale: string): IDbAdapter['withReadSnapshot'];

package/dist/modules/storage/read-snapshot.js

@@ -0,0 +1,12 @@
+import { runReadSnapshot } from '@byline/core';
+import { DBManagerImpl } from '../../lib/db-manager.js';
+import { createAuditQueries } from '../audit/audit-queries.js';
+import { SingletonQueries } from './singletons.js';
+import { createQueryBuilders } from './storage-queries.js';
+export function createReadSnapshot(db, collections, defaultLocale) {
+    return (fn) => db.transaction(async (tx) => {
+        const manager = new DBManagerImpl({ dbPool: tx });
+        const queries = createQueryBuilders(tx, collections, defaultLocale, manager);
+        return runReadSnapshot({ ...queries, audit: createAuditQueries(tx), singletons: new SingletonQueries(manager) }, fn);
+    }, { isolationLevel: 'repeatable read', accessMode: 'read only' });
+}

package/dist/modules/storage/singletons.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { type ISingletonCommands, type ISingletonQueries } from '@byline/core';
+import type { ISingletonCommands, ISingletonQueries } from '@byline/core';
 import type { DBManager } from '../../lib/db-manager.js';
 export declare class SingletonCommands implements ISingletonCommands {
     private dbManager;

package/dist/modules/storage/singletons.js

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { ERR_DATABASE, ERR_NOT_FOUND, } from '@byline/core';
-import { eq, sql } from 'drizzle-orm';
+import { eq } from 'drizzle-orm';
 import { singletonDocuments } from '../../database/schema/index.js';
+import { lockCollectionRegistration } from './collection-registration.js';
 export class SingletonCommands {
     dbManager;
     constructor(dbManager) {
@@ -21,24 +21,7 @@ export class SingletonCommands {
         return this.dbManager.get();
     }
     async lockSlot(collectionId) {
-        if (!this.dbManager.isInTransaction()) {
-            throw ERR_DATABASE({
-                message: 'singleton slot locks require an active transaction',
-                details: { collectionId },
-            });
-        }
-        const locked = await this.db.execute(sql `
-      SELECT id FROM byline_collections
-      WHERE id = ${collectionId}
-      FOR UPDATE
-    `);
-        const rows = locked[0];
-        if (rows.length === 0) {
-            throw ERR_NOT_FOUND({
-                message: 'singleton slot registration not found',
-                details: { collectionId },
-            });
-        }
+        await lockCollectionRegistration(this.dbManager, collectionId, 'exclusive');
     }
     async setMapping(collectionId, documentId) {
         await this.db

package/dist/modules/storage/storage-commands.d.ts

@@ -20,6 +20,7 @@ import type { DBManager } from '../../lib/db-manager.js';
  */
 export declare class CollectionCommands implements ICollectionCommands {
     private dbManager;
+    lockCollectionRegistration(collectionId: string, mode: 'shared' | 'exclusive'): Promise<void>;
     constructor(dbManager: DBManager);
     /**
      * The executor for this call — the ambient transaction when a
@@ -384,6 +385,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      */
     restoreSoftDeletedDocument(params: {
         document_id: string;
+        expectedRevision: number;
     }): Promise<number>;
     private readDocumentVersionLiveness;
     /**

package/dist/modules/storage/storage-commands.js

@@ -5,11 +5,12 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { DbErrorCodes, ERR_CONFLICT, ERR_NOT_FOUND, ERR_VALIDATION, flattenFieldSetData, generateKeyBetween, isSingleton, TREE_PLACEMENT_STALE_MARKER, } from '@byline/core';
+import { assertDocumentVersionParent, DbErrorCodes, documentRevisionFromDatabase, ERR_CONFLICT, ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ERR_VALIDATION, flattenFieldSetData, generateKeyBetween, isSingleton, parseDocumentRevision, TREE_PLACEMENT_STALE_MARKER, } from '@byline/core';
 import { and, desc, eq, inArray, ne, notInArray, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
-import { booleanStore, collections, currentDocumentsView, datetimeStore, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
+import { booleanStore, collections, currentDocumentsView, datetimeStore, documentAvailableLocales, documentPaths, documentPublishSchedules, documentRelationships, documents, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
 import { classifyError } from './classify-error.js';
+import { lockCollectionRegistration } from './collection-registration.js';
 import { DocumentPublishScheduleCommands } from './publish-schedules.js';
 import { prepareFieldInsertBuckets } from './storage-insert.js';
 import { affectedRowCount, getFirstOrThrow } from './storage-utils.js';
@@ -34,6 +35,9 @@ const staleTreePlacementMessage = (message) => `${TREE_PLACEMENT_STALE_MARKER} t
  */
 export class CollectionCommands {
     dbManager;
+    async lockCollectionRegistration(collectionId, mode) {
+        await lockCollectionRegistration(this.dbManager, collectionId, mode);
+    }
     constructor(dbManager) {
         this.dbManager = dbManager;
     }
@@ -202,6 +206,7 @@ export class DocumentCommands {
                 sourceLocale = this.defaultContentLocale;
                 await tx.insert(documents).values({
                     id: documentId,
+                    revision: 1,
                     collection_id: params.collectionId,
                     order_key: params.orderKey ?? null,
                     source_locale: sourceLocale,
@@ -221,6 +226,12 @@ export class DocumentCommands {
                         details: { documentId },
                     });
                 }
+                assertDocumentVersionParent({
+                    documentId,
+                    locale: params.locale,
+                    previousVersionId: params.previousVersionId,
+                    currentVersionId: versionLiveness.currentVersionId,
+                });
                 sourceLocale = existing.source_locale ?? this.defaultContentLocale;
             }
             // 2. Create the document version. The id is minted here (app-side
@@ -799,18 +810,30 @@ export class DocumentCommands {
      * reconstructed by this storage primitive.
      */
     async restoreSoftDeletedDocument(params) {
+        params = { ...params, expectedRevision: parseDocumentRevision(params.expectedRevision) };
         const restoredAt = new Date();
         return this.db.transaction(async (tx) => {
             const collectionId = await this.lockDocumentCollection(tx, params.document_id);
             if (collectionId == null)
                 return 0;
             const [document] = await tx
-                .select({ id: documents.id })
+                .select({ id: documents.id, revision: documents.revision })
                 .from(documents)
                 .where(eq(documents.id, params.document_id))
                 .for('update');
             if (document == null)
                 return 0;
+            const currentRevision = documentRevisionFromDatabase(document.revision);
+            if (currentRevision !== params.expectedRevision)
+                throw ERR_DOCUMENT_STALE({
+                    message: 'This document has changed. Reload before restoring.',
+                    details: {
+                        reason: 'revision_mismatch',
+                        documentId: params.document_id,
+                        expectedRevision: params.expectedRevision,
+                        currentRevision,
+                    },
+                });
             const versionLiveness = await this.readDocumentVersionLiveness(tx, params.document_id);
             if (versionLiveness.total === 0 || versionLiveness.live > 0)
                 return 0;
@@ -821,6 +844,17 @@ export class DocumentCommands {
                 updated_at: restoredAt,
             })
                 .where(eq(documentPaths.document_id, params.document_id));
+            // Internal restores cannot revive a schedule left by legacy or raw maintenance.
+            // Keep this on the same transaction executor, after the collection/document locks.
+            await tx
+                .delete(documentPublishSchedules)
+                .where(eq(documentPublishSchedules.document_id, params.document_id));
+            if (currentRevision === Number.MAX_SAFE_INTEGER)
+                throw ERR_VALIDATION({ message: 'Document revision exhausted' });
+            await tx
+                .update(documents)
+                .set({ revision: currentRevision + 1, updated_at: restoredAt })
+                .where(and(eq(documents.id, params.document_id), eq(documents.revision, currentRevision)));
             const result = await tx
                 .update(documentVersions)
                 .set({
@@ -833,10 +867,12 @@ export class DocumentCommands {
     }
     async readDocumentVersionLiveness(tx, documentId) {
         // Match the live views: only explicit `false` is live; legacy `NULL` is not.
+        // Their current version is likewise the greatest live UUIDv7 id.
         return tx
             .select({
             total: sql `CAST(COUNT(*) AS SIGNED)`,
             live: sql `CAST(COUNT(CASE WHEN ${documentVersions.is_deleted} = false THEN 1 END) AS SIGNED)`,
+            currentVersionId: sql `MAX(CASE WHEN ${documentVersions.is_deleted} = false THEN ${documentVersions.id} ELSE NULL END)`,
         })
             .from(documentVersions)
             .where(eq(documentVersions.document_id, documentId))

package/dist/modules/storage/storage-queries.d.ts

@@ -75,6 +75,10 @@ export declare class CollectionQueries implements ICollectionQueries {
  * DocumentQueries
  */
 export declare class DocumentQueries implements IDocumentQueries {
+    getDocumentRevision(params: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<number | null>;
     readonly publishSchedules: DocumentPublishScheduleQueries;
     private db;
     private transactionDb;

package/dist/modules/storage/storage-queries.js

@@ -62,6 +62,14 @@ export class CollectionQueries {
  * DocumentQueries
  */
 export class DocumentQueries {
+    async getDocumentRevision(params) {
+        const rows = await this.db
+            .select({ revision: documents.revision })
+            .from(documents)
+            .where(and(eq(documents.id, params.document_id), eq(documents.collection_id, params.collection_id)))
+            .limit(1);
+        return rows[0]?.revision ?? null;
+    }
     publishSchedules;
     db;
     transactionDb;
@@ -1722,6 +1730,7 @@ export class DocumentQueries {
                 : sql `(d.order_key IS NULL) ASC, d.order_key ASC, d.created_at DESC`;
         }
         const columnMap = {
+            document_id: 'd.document_id',
             created_at: 'd.created_at',
             updated_at: 'd.updated_at',
         };

package/dist/modules/storage/tests/storage-live-path-queries.test.js

@@ -144,7 +144,10 @@ describe('live-path query resolution (MySQL)', () => {
             previousVersionId: first.document.id,
         });
         await testDb.commandBuilders.documents.softDeleteDocument({ document_id: documentId });
-        await expect(testDb.commandBuilders.documents.restoreSoftDeletedDocument({ document_id: documentId })).resolves.toBe(2);
+        await expect(testDb.commandBuilders.documents.restoreSoftDeletedDocument({
+            expectedRevision: 1,
+            document_id: documentId,
+        })).resolves.toBe(2);
         const restoredPaths = await testDb.db
             .select({
             path: documentPaths.path,
@@ -180,7 +183,10 @@ describe('live-path query resolution (MySQL)', () => {
             .update(documentPaths)
             .set({ deleted_at: null })
             .where(eq(documentPaths.document_id, documentId));
-        await expect(testDb.commandBuilders.documents.restoreSoftDeletedDocument({ document_id: documentId })).resolves.toBe(0);
+        await expect(testDb.commandBuilders.documents.restoreSoftDeletedDocument({
+            expectedRevision: 2,
+            document_id: documentId,
+        })).resolves.toBe(0);
         const legacyPaths = await testDb.db
             .select({ deletedAt: documentPaths.deleted_at })
             .from(documentPaths)
@@ -196,6 +202,7 @@ describe('live-path query resolution (MySQL)', () => {
         const documentId = crypto.randomUUID();
         const path = `versionless-${timestamp}`;
         await testDb.db.insert(documents).values({
+            revision: 1,
             id: documentId,
             collection_id: collectionId,
             source_locale: 'en',

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-mysql",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.18.0",
+  "version": "5.0.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -50,8 +50,8 @@
     "drizzle-orm": "^0.45.2",
     "mysql2": "^3.24.2",
     "uuid": "^14.0.2",
-    "@byline/admin": "4.18.0",
-    "@byline/core": "4.18.0"
+    "@byline/admin": "5.0.0",
+    "@byline/core": "5.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",
@@ -64,9 +64,9 @@
     "tsc-alias": "^1.9.2",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/client": "4.18.0",
-    "@byline/db-conformance": "0.0.10",
-    "@byline/auth": "4.18.0"
+    "@byline/client": "5.0.0",
+    "@byline/auth": "5.0.0",
+    "@byline/db-conformance": "0.0.10"
   },
   "publishConfig": {
     "access": "public",