Keep database upgrades within edge request limits

TODO.md

@@ -20,6 +20,30 @@ everything still outstanding is captured below.
 
 ---
 
+## Split the database migration runtime
+
+*Origin: CodeRabbit review on PR #1845 (`src/shared/db/migrations.ts`).*
+
+`src/shared/db/migrations.ts` already exceeded 700 lines before PR #1845 and now
+also owns request-sized batches and lease-scoped completion. Split it without
+changing behavior. A useful starting boundary is:
+
+- Move lease acquisition, ownership checks, and release into a focused lock
+  module.
+- Move migration marker and schema marker statement builders into a recording
+  module.
+- Move retry and pending-migration execution into a runner module.
+- Leave `initDb` and database-state routing in `migrations.ts` as thin
+  orchestration.
+
+Keep the existing request round-trip count, lazy migration loading, partial
+progress behavior, and lock failure tests unchanged. This is intentionally
+separate from PR #1845 because moving the whole migration subsystem while
+changing its locking and batching would make the safety fix much harder to
+review and roll back.
+
+---
+
 ## Booking unification — phases 3 & 4
 
 *Origin: `booking-unification.md`, `booking-unification-phase2.md`.*

src/shared/db/client.ts

@@ -527,8 +527,10 @@ export const executeBatch = async (
 };
 
 /** The slice of an open write transaction handed to a {@link withTransaction}
- *  callback: run statements with `execute`; commit/rollback are managed for you. */
+ *  callback: run statements singly or as one batch; commit/rollback are managed
+ *  for you. */
 export type TxScope = {
+  batch: (statements: InStatement[]) => Promise<ResultSet[]>;
   execute: (stmt: InStatement) => Promise<ResultSet>;
 };
 
@@ -550,6 +552,15 @@ const runWriteTransactionOnce = async <T>(
   const writtenSql: string[] = [];
   let statementCount = 0;
   const scope: TxScope = {
+    batch: (statements) => {
+      const sqls = statements.map((statement) =>
+        typeof statement === "string" ? statement : statement.sql,
+      );
+      writtenSql.push(...sqls);
+      statementCount += 1;
+      enforceTransactionRoundTripGuard(statementCount, sqls.join("; "));
+      return tx.batch(statements);
+    },
     execute: (stmt) => {
       const sql = typeof stmt === "string" ? stmt : stmt.sql;
       writtenSql.push(sql);