@byline/db-mysql 4.19.0 → 5.1.0

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 { assertDocumentVersionParent, 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,
@@ -805,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;
@@ -827,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({

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.19.0",
+  "version": "5.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -48,24 +48,24 @@
   ],
   "dependencies": {
     "drizzle-orm": "^0.45.2",
-    "mysql2": "^3.24.2",
+    "mysql2": "^3.24.4",
     "uuid": "^14.0.2",
-    "@byline/admin": "4.19.0",
-    "@byline/core": "4.19.0"
+    "@byline/admin": "5.1.0",
+    "@byline/core": "5.1.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.10",
-    "@types/node": "^26.4.0",
+    "@biomejs/biome": "2.5.12",
+    "@types/node": "^26.5.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.4.2",
     "drizzle-kit": "^0.31.10",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.9.2",
+    "tsc-alias": "^1.9.4",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "@byline/auth": "4.19.0",
-    "@byline/client": "4.19.0",
+    "vitest": "^5.0.0",
+    "@byline/auth": "5.1.0",
+    "@byline/client": "5.1.0",
     "@byline/db-conformance": "0.0.10"
   },
   "publishConfig": {