@byline/db-mysql 4.19.0 → 5.1.0

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/admin/admin-store.js

@@ -5,11 +5,15 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { eq } from 'drizzle-orm';
+import { adminUsers } from '../../database/schema/auth.js';
 import { createAdminPermissionsRepository } from './admin-permissions-repository.js';
 import { createAdminPreferencesRepository } from './admin-preferences-repository.js';
 import { createAdminRolesRepository } from './admin-roles-repository.js';
 import { createAdminUsersRepository } from './admin-users-repository.js';
+import { createLoginSessionsRepository } from './login-sessions-repository.js';
 import { createRefreshTokensRepository } from './refresh-tokens-repository.js';
+import { createSignInRateLimitStore } from './sign-in-rate-limit-store.js';
 /**
  * Wire the five admin repositories against a Drizzle handle and return the
  * `AdminStore` bundle expected by `@byline/admin` — specifically by the
@@ -21,6 +25,32 @@ import { createRefreshTokensRepository } from './refresh-tokens-repository.js';
  */
 export function createAdminStore(db) {
     return {
+        async withSessionLock(adminUserId, work) {
+            return db.transaction(async (tx) => {
+                await tx
+                    .select({ id: adminUsers.id })
+                    .from(adminUsers)
+                    .where(eq(adminUsers.id, adminUserId))
+                    .for('update');
+                const scoped = createAdminStore(tx);
+                const user = await scoped.adminUsers.getByIdForSignIn(adminUserId);
+                return work(scoped, user);
+            });
+        },
+        async withSessionLocks(adminUserIds, work) {
+            return db.transaction(async (tx) => {
+                for (const id of [...new Set(adminUserIds)].sort()) {
+                    await tx
+                        .select({ id: adminUsers.id })
+                        .from(adminUsers)
+                        .where(eq(adminUsers.id, id))
+                        .for('update');
+                }
+                return work(createAdminStore(tx));
+            });
+        },
+        loginSessions: createLoginSessionsRepository(db),
+        signInRateLimits: createSignInRateLimitStore(db),
         adminUsers: createAdminUsersRepository(db),
         adminRoles: createAdminRolesRepository(db),
         adminPermissions: createAdminPermissionsRepository(db),

package/dist/modules/admin/admin-users-repository.js

@@ -10,6 +10,8 @@ import { and, asc, desc, eq, inArray, like, or, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
 import { adminUsers } from '../../database/schema/auth.js';
 import { affectedRowCount } from '../storage/storage-utils.js';
+import { createLoginSessionsRepository } from './login-sessions-repository.js';
+import { createRefreshTokensRepository } from './refresh-tokens-repository.js';
 /**
  * MySQL implementation of `AdminUsersRepository`. Ported from
  * `packages/db-postgres/src/modules/admin/admin-users-repository.ts`.
@@ -160,14 +162,22 @@ export function createAdminUsersRepository(db) {
         },
         async getByEmailForSignIn(email) {
             const [row] = await db
-                .select({ ...PUBLIC_COLUMNS, password_hash: adminUsers.password })
+                .select({
+                ...PUBLIC_COLUMNS,
+                password_hash: adminUsers.password,
+                session_version: adminUsers.session_version,
+            })
                 .from(adminUsers)
                 .where(eq(adminUsers.email, email.toLowerCase()));
             return row ?? null;
         },
         async getByIdForSignIn(id) {
             const [row] = await db
-                .select({ ...PUBLIC_COLUMNS, password_hash: adminUsers.password })
+                .select({
+                ...PUBLIC_COLUMNS,
+                password_hash: adminUsers.password,
+                session_version: adminUsers.session_version,
+            })
                 .from(adminUsers)
                 .where(eq(adminUsers.id, id));
             return row ?? null;
@@ -211,6 +221,9 @@ export function createAdminUsersRepository(db) {
                 updateSet.is_super_admin = patch.is_super_admin;
             if (patch.is_enabled !== undefined)
                 updateSet.is_enabled = patch.is_enabled;
+            if (patch.is_enabled === false) {
+                updateSet.session_version = sql `${adminUsers.session_version} + 1`;
+            }
             if (patch.is_email_verified !== undefined)
                 updateSet.is_email_verified = patch.is_email_verified;
             if (patch.remember_me !== undefined)
@@ -233,6 +246,10 @@ export function createAdminUsersRepository(db) {
                     .where(eq(adminUsers.id, id));
                 if (!fresh)
                     throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                if (patch.is_enabled === false) {
+                    await createRefreshTokensRepository(tx).revokeAllForUser(id);
+                    await createLoginSessionsRepository(tx).revokeAllForUser(id);
+                }
                 return fresh;
             });
         },
@@ -245,6 +262,7 @@ export function createAdminUsersRepository(db) {
                     .update(adminUsers)
                     .set({
                     password: passwordHash,
+                    session_version: sql `${adminUsers.session_version} + 1`,
                     updated_at: now,
                     vid: sql `${adminUsers.vid} + 1`,
                 })
@@ -257,14 +275,27 @@ export function createAdminUsersRepository(db) {
                     .where(eq(adminUsers.id, id));
                 if (!fresh)
                     throw ERR_ADMIN_USER_VERSION_CONFLICT();
+                await createRefreshTokensRepository(tx).revokeAllForUser(id);
+                await createLoginSessionsRepository(tx).revokeAllForUser(id);
                 return fresh;
             });
         },
         async setEnabled(id, enabled) {
-            await db
-                .update(adminUsers)
-                .set({ is_enabled: enabled, updated_at: new Date(), vid: sql `${adminUsers.vid} + 1` })
-                .where(eq(adminUsers.id, id));
+            await db.transaction(async (tx) => {
+                await tx
+                    .update(adminUsers)
+                    .set({
+                    is_enabled: enabled,
+                    updated_at: new Date(),
+                    vid: sql `${adminUsers.vid} + 1`,
+                    ...(!enabled ? { session_version: sql `${adminUsers.session_version} + 1` } : {}),
+                })
+                    .where(eq(adminUsers.id, id));
+                if (!enabled) {
+                    await createRefreshTokensRepository(tx).revokeAllForUser(id);
+                    await createLoginSessionsRepository(tx).revokeAllForUser(id);
+                }
+            });
         },
         async setPreferredLocale(id, locale) {
             await db

package/dist/modules/admin/login-sessions-repository.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { LoginSessionsRepository } from '@byline/admin/auth';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+export declare function createLoginSessionsRepository(db: MySql2Database<typeof schema>): LoginSessionsRepository;

package/dist/modules/admin/login-sessions-repository.js

@@ -0,0 +1,38 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { and, eq, isNull } from 'drizzle-orm';
+import { adminLoginSessions } from '../../database/schema/auth.js';
+export function createLoginSessionsRepository(db) {
+    return {
+        async create(input) {
+            await db.insert(adminLoginSessions).values(input);
+        },
+        async findById(id) {
+            const [row] = await db.select().from(adminLoginSessions).where(eq(adminLoginSessions.id, id));
+            return row ?? null;
+        },
+        async extend(id, expiresAt) {
+            await db
+                .update(adminLoginSessions)
+                .set({ expires_at: expiresAt })
+                .where(and(eq(adminLoginSessions.id, id), isNull(adminLoginSessions.revoked_at)));
+        },
+        async revoke(id, at = new Date()) {
+            await db
+                .update(adminLoginSessions)
+                .set({ revoked_at: at })
+                .where(and(eq(adminLoginSessions.id, id), isNull(adminLoginSessions.revoked_at)));
+        },
+        async revokeAllForUser(adminUserId, at = new Date()) {
+            await db
+                .update(adminLoginSessions)
+                .set({ revoked_at: at })
+                .where(and(eq(adminLoginSessions.admin_user_id, adminUserId), isNull(adminLoginSessions.revoked_at)));
+        },
+    };
+}

package/dist/modules/admin/refresh-tokens-repository.js

@@ -34,11 +34,16 @@ import { affectedRowCount } from '../storage/storage-utils.js';
 export function createRefreshTokensRepository(db) {
     return {
         async issue(input) {
+            if (!Number.isSafeInteger(input.session_version) || input.session_version < -1) {
+                throw new Error('issueRefreshToken: session_version must be an integer >= -1');
+            }
             const now = new Date();
             const row = {
                 id: input.id,
                 admin_user_id: input.admin_user_id,
                 token_hash: input.token_hash,
+                session_version: input.session_version,
+                sid: input.sid ?? null,
                 issued_at: now,
                 expires_at: input.expires_at,
                 revoked_at: null,
@@ -51,6 +56,8 @@ export function createRefreshTokensRepository(db) {
                 id: row.id,
                 admin_user_id: row.admin_user_id,
                 token_hash: row.token_hash,
+                session_version: row.session_version,
+                sid: row.sid,
                 issued_at: now,
                 expires_at: row.expires_at,
                 user_agent: row.user_agent,
@@ -90,30 +97,17 @@ export function createRefreshTokensRepository(db) {
                 .where(and(eq(adminRefreshTokens.id, id), isNull(adminRefreshTokens.revoked_at)));
         },
         async revokeChain(startId, at = new Date()) {
-            let cursor = startId;
-            let touched = 0;
-            // Bounded walk — chains in practice are short; 1000 is a safety ceiling.
-            for (let step = 0; cursor != null && step < 1000; step++) {
-                const [row] = await db
-                    .select({
-                    id: adminRefreshTokens.id,
-                    rotated_to_id: adminRefreshTokens.rotated_to_id,
-                    revoked_at: adminRefreshTokens.revoked_at,
-                })
-                    .from(adminRefreshTokens)
-                    .where(eq(adminRefreshTokens.id, cursor));
-                if (!row)
-                    break;
-                if (row.revoked_at == null) {
-                    await db
-                        .update(adminRefreshTokens)
-                        .set({ revoked_at: at, updated_at: new Date() })
-                        .where(eq(adminRefreshTokens.id, row.id));
-                    touched++;
-                }
-                cursor = row.rotated_to_id;
-            }
-            return touched;
+            const [member] = await db
+                .select()
+                .from(adminRefreshTokens)
+                .where(eq(adminRefreshTokens.id, startId));
+            if (!member?.sid)
+                return 0; // Legacy credentials fail closed in the provider.
+            const result = await db
+                .update(adminRefreshTokens)
+                .set({ revoked_at: at, updated_at: at })
+                .where(and(eq(adminRefreshTokens.sid, member.sid), isNull(adminRefreshTokens.revoked_at)));
+            return affectedRowCount(result);
         },
         async revokeAllForUser(adminUserId, at = new Date()) {
             const result = await db

package/dist/modules/admin/retry-deadlock.d.ts

@@ -0,0 +1,2 @@
+/** Retry only InnoDB deadlock victims: error 1213 guarantees transaction rollback. */
+export declare function retryDeadlock<T>(operation: () => Promise<T>): Promise<T>;

package/dist/modules/admin/retry-deadlock.js

@@ -0,0 +1,22 @@
+/** Retry only InnoDB deadlock victims: error 1213 guarantees transaction rollback. */
+export async function retryDeadlock(operation) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            let cause = error;
+            let deadlock = false;
+            for (let depth = 0; depth < 8 && cause && typeof cause === 'object'; depth++) {
+                if ('errno' in cause && cause.errno === 1213) {
+                    deadlock = true;
+                    break;
+                }
+                cause = 'cause' in cause ? cause.cause : undefined;
+            }
+            if (!deadlock || attempt >= 2)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 10 * 2 ** attempt + Math.random() * 10));
+        }
+    }
+}

package/dist/modules/admin/sign-in-rate-limit-store.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { SignInRateLimitStore } from '@byline/admin/auth';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+export declare function createSignInRateLimitStore(db: MySql2Database<typeof schema>): SignInRateLimitStore;

package/dist/modules/admin/sign-in-rate-limit-store.js

@@ -0,0 +1,37 @@
+/**
+ * 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 { eq, sql } from 'drizzle-orm';
+import { adminSignInRateLimits as counters } from '../../database/schema/auth.js';
+import { retryDeadlock } from './retry-deadlock.js';
+export function createSignInRateLimitStore(db) {
+    return {
+        async consume(key, limit, expiresAt) {
+            // The upsert holds the row lock until our read commits, including concurrent first inserts.
+            return retryDeadlock(() => db.transaction(async (tx) => {
+                await tx
+                    .insert(counters)
+                    .values({ key, attempts: 1, expires_at: expiresAt })
+                    .onDuplicateKeyUpdate({
+                    set: { attempts: sql `least(${counters.attempts} + 1, ${limit + 1})` },
+                });
+                const [row] = await tx
+                    .select({ attempts: counters.attempts })
+                    .from(counters)
+                    .where(eq(counters.key, key))
+                    .for('update');
+                if (!row)
+                    throw new Error('Sign-in counter update returned no row');
+                return row.attempts <= limit;
+            }));
+        },
+        async purgeExpired(before) {
+            const [result] = await db.execute(sql `delete from ${counters} where ${counters.expires_at} < ${before.toISOString().slice(0, 23).replace('T', ' ')} limit 100`);
+            return result.affectedRows;
+        },
+    };
+}

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>;
+}