@byline/db-mysql 4.19.0 → 5.1.0

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

@@ -60,6 +60,23 @@ export declare const adminUsers: import("drizzle-orm/mysql-core").MySqlTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        session_version: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "session_version";
+            tableName: "byline_admin_users";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         vid: import("drizzle-orm/mysql-core").MySqlColumn<{
             name: "vid";
             tableName: "byline_admin_users";
@@ -720,6 +737,98 @@ export declare const adminPermissions: import("drizzle-orm/mysql-core").MySqlTab
  * at the replacement row; presenting a rotated token is treated as replay
  * and revokes the whole chain.
  */
+export declare const adminLoginSessions: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "byline_admin_login_sessions";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "id";
+            tableName: "byline_admin_login_sessions";
+            dataType: "custom";
+            columnType: "MySqlCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        admin_user_id: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "admin_user_id";
+            tableName: "byline_admin_login_sessions";
+            dataType: "custom";
+            columnType: "MySqlCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        session_version: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "session_version";
+            tableName: "byline_admin_login_sessions";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expires_at: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "expires_at";
+            tableName: "byline_admin_login_sessions";
+            dataType: "date";
+            columnType: "MySqlDateTime";
+            data: Date;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        revoked_at: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "revoked_at";
+            tableName: "byline_admin_login_sessions";
+            dataType: "date";
+            columnType: "MySqlDateTime";
+            data: Date;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'mysql';
+}>;
 export declare const adminRefreshTokens: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
     name: "byline_admin_refresh_tokens";
     schema: undefined;
@@ -792,6 +901,23 @@ export declare const adminRefreshTokens: import("drizzle-orm/mysql-core").MySqlT
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        sid: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "sid";
+            tableName: "byline_admin_refresh_tokens";
+            dataType: "custom";
+            columnType: "MySqlCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         token_hash: import("drizzle-orm/mysql-core").MySqlColumn<{
             name: "token_hash";
             tableName: "byline_admin_refresh_tokens";
@@ -809,6 +935,23 @@ export declare const adminRefreshTokens: import("drizzle-orm/mysql-core").MySqlT
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        session_version: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "session_version";
+            tableName: "byline_admin_refresh_tokens";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         issued_at: import("drizzle-orm/mysql-core").MySqlColumn<{
             name: "issued_at";
             tableName: "byline_admin_refresh_tokens";
@@ -949,3 +1092,62 @@ export declare const adminPermissionsRelations: import("drizzle-orm").Relations<
 export declare const adminRefreshTokensRelations: import("drizzle-orm").Relations<"byline_admin_refresh_tokens", {
     user: import("drizzle-orm").One<"byline_admin_users", true>;
 }>;
+/** Shared, expiring fixed-window counters for password sign-in admission. */
+export declare const adminSignInRateLimits: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "byline_admin_sign_in_rate_limits";
+    schema: undefined;
+    columns: {
+        key: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "key";
+            tableName: "byline_admin_sign_in_rate_limits";
+            dataType: "string";
+            columnType: "MySqlVarChar";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "attempts";
+            tableName: "byline_admin_sign_in_rate_limits";
+            dataType: "number";
+            columnType: "MySqlInt";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expires_at: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "expires_at";
+            tableName: "byline_admin_sign_in_rate_limits";
+            dataType: "date";
+            columnType: "MySqlDateTime";
+            data: Date;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'mysql';
+}>;

package/dist/database/schema/auth.js

@@ -36,6 +36,7 @@ import { createdAt, timestamps, uuidChar } from './common.js';
 // ---------------------------------------------------------------------------
 export const adminUsers = mysqlTable('byline_admin_users', {
     id: uuidChar('id').primaryKey(),
+    session_version: int('session_version').notNull().default(0),
     vid: int('vid').notNull().default(1),
     given_name: varchar('given_name', { length: 100 }),
     family_name: varchar('family_name', { length: 100 }),
@@ -162,11 +163,27 @@ export const adminPermissions = mysqlTable('byline_admin_permissions', {
  * at the replacement row; presenting a rotated token is treated as replay
  * and revokes the whole chain.
  */
+export const adminLoginSessions = mysqlTable('byline_admin_login_sessions', {
+    id: uuidChar('id').primaryKey(),
+    admin_user_id: uuidChar('admin_user_id').notNull(),
+    session_version: int('session_version').notNull(),
+    expires_at: datetime('expires_at', { fsp: 6 }).notNull(),
+    revoked_at: datetime('revoked_at', { fsp: 6 }),
+}, (table) => [
+    foreignKey({
+        name: 'fk_admin_login_sessions_user',
+        columns: [table.admin_user_id],
+        foreignColumns: [adminUsers.id],
+    }).onDelete('cascade'),
+    index('idx_admin_login_sessions_user').on(table.admin_user_id),
+]);
 export const adminRefreshTokens = mysqlTable('byline_admin_refresh_tokens', {
     id: uuidChar('id').primaryKey(),
     admin_user_id: uuidChar('admin_user_id').notNull(),
     /** SHA-256 hex digest of the raw refresh-token string. 64 chars. */
+    sid: uuidChar('sid'),
     token_hash: varchar('token_hash', { length: 64 }).notNull().unique(),
+    session_version: int('session_version').notNull().default(-1),
     // fsp 6 throughout this table, matching pg — see `common.ts`'s
     // `auditTimestamp` docblock for why every temporal column in this
     // schema moved from fsp 3 to fsp 6.
@@ -183,11 +200,17 @@ export const adminRefreshTokens = mysqlTable('byline_admin_refresh_tokens', {
     ip: varchar('ip', { length: 45 }),
     ...timestamps,
 }, (table) => [
+    foreignKey({
+        name: 'fk_admin_refresh_tokens_sid',
+        columns: [table.sid],
+        foreignColumns: [adminLoginSessions.id],
+    }).onDelete('cascade'),
     foreignKey({
         name: 'fk_admin_refresh_tokens_admin_user_id',
         columns: [table.admin_user_id],
         foreignColumns: [adminUsers.id],
     }).onDelete('cascade'),
+    index('idx_admin_refresh_tokens_sid').on(table.sid),
     index('idx_byline_admin_refresh_tokens_user').on(table.admin_user_id),
     index('idx_byline_admin_refresh_tokens_token_hash').on(table.token_hash),
 ]);
@@ -224,3 +247,9 @@ export const adminRefreshTokensRelations = relations(adminRefreshTokens, ({ one
         references: [adminUsers.id],
     }),
 }));
+/** Shared, expiring fixed-window counters for password sign-in admission. */
+export const adminSignInRateLimits = mysqlTable('byline_admin_sign_in_rate_limits', {
+    key: varchar('key', { length: 64 }).primaryKey(),
+    attempts: int('attempts').notNull(),
+    expires_at: datetime('expires_at', { fsp: 3 }).notNull(),
+}, (table) => [index('idx_admin_sign_in_rate_limits_expiry').on(table.expires_at)]);

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";
@@ -4068,4 +4102,4 @@ export declare const recurringTasks: import("drizzle-orm/mysql-core").MySqlTable
     };
     dialect: 'mysql';
 }>;
-export { adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminUserPreferences, adminUsers, adminUsersRelations, } from './auth.js';
+export { adminLoginSessions, adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminSignInRateLimits, adminUserPreferences, adminUsers, adminUsersRelations, } from './auth.js';

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),
@@ -991,4 +996,4 @@ export const recurringTasks = mysqlTable('byline_recurring_tasks', {
 // Auth schema — byline_admin_users, byline_admin_roles, etc.
 // See ./auth.ts for definitions and rationale.
 // ---------------------------------------------------------------------------
-export { adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminUserPreferences, adminUsers, adminUsersRelations, } from './auth.js';
+export { adminLoginSessions, adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminSignInRateLimits, adminUserPreferences, adminUsers, adminUsersRelations, } from './auth.js';

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

@@ -348,8 +348,10 @@ describe('schema pins — timestamp precision (spec §F.3)', () => {
     it('finds datetime columns to check (schema is not empty)', () => {
         expect(instantColumns.length).toBeGreaterThan(0);
     });
-    it.each(instantColumns.map((c) => [`${c.tableName}.${c.column.name}`, c.column]))('%s is datetime(6) — microsecond precision (pg parity)', (_label, column) => {
-        expect(column.getSQLType()).toBe('datetime(6)');
+    it.each(instantColumns.map((c) => [`${c.tableName}.${c.column.name}`, c.column]))('%s uses the PostgreSQL companion precision', (label, column) => {
+        // Admission windows intentionally share JavaScript millisecond precision on both adapters.
+        const precision = label === 'byline_admin_sign_in_rate_limits.expires_at' ? 3 : 6;
+        expect(column.getSQLType()).toBe(`datetime(${precision})`);
     });
     // `MySqlDate` (the `date()` builder, used by `datetimeStore.value_date`)
     // is the one temporal type genuinely outside this pin's scope — a
@@ -448,6 +450,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 +488,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 {};