@@ -0,0 +1,16 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/driver-sql': patch
+'@objectstack/cli': patch
+---
+
+fix(objectql): a server boot's schema sync takes the same schema-migration lock as `os migrate apply`, so replicas starting together create each table once
+
+Clause-②: no
+Metadata-protocol: none
+
+Several servers booting against one Postgres or MySQL database at the same time (replicas of one deployment, or several `OS_MIGRATE_AND_EXIT=1` jobs) each read the same missing tables and each created them. Postgres then refused one of the duplicate `CREATE TABLE` statements with a `pg_type` unique-key collision, and the boot that lost logged `Schema sync FAILED` for that object while still exiting 0. The boot's schema sync now takes the schema-migration lock that `os migrate apply` takes (one name, `objectstack:schema-migrate`, and one Postgres key), on the default datasource's database, and releases it as soon as the sync is done. It is never held while the server runs. A boot that finds another migration running prints one line saying it waits, then finds the tables already there.
+
+On a single node nothing changes: the lock is uncontended and prints nothing, and SQLite (with Turso and WASM SQLite) takes no lock at all: the lock reads the dialect from the driver's `dialectName` and never asks a SQLite-dialect driver for its Knex, so a remote Turso transport, which refuses to hand its Knex out, boots as before. A boot with `skipSchemaSync` / `OS_SKIP_SCHEMA_SYNC=1` takes none either, since it runs no DDL. A waiting boot gives up after half of the engine plugin's start budget (60 s by default), changes nothing and fails the boot with a message naming the lock; start it again once the other migration has finished.
+
+The lock now lives in `@objectstack/objectql` (`acquireSchemaMigrationLock`, `SCHEMA_MIGRATION_LOCK_NAME`), so the engine's boot can take it; `@objectstack/cli` keeps importing it from there. `SqlDriver` gains a read-only `schemaDdlDeferred` getter, which tells the engine's boot that `os migrate plan` / `apply` is holding the driver's DDL back and will take the lock itself.
@@ -23,6 +23,15 @@
  * the first one left. The third run is the control: uncontended, it prints
  * no wait line and finds the schema in sync.
  *
+ * ## Server boots take the same lock (#31715)
+ *
+ * The second describe stages three `os serve` boots with
+ * `OS_MIGRATE_AND_EXIT=1` the same way: the engine's boot schema sync
+ * (`ObjectQLPlugin.start()`) takes this lock. Measured before it, with three
+ * such boots held together at their first database round trip: one table
+ * created twice, a `pg_type` collision, `Schema sync FAILED` in the losing
+ * boot's output, and every boot still exiting 0.
+ *
  * ## The driver axis
  *
  * Postgres only, and only when `OS_TEST_POSTGRES_URL` is set, in a database
@@ -37,6 +46,7 @@ import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer, type AddressInfo } from 'node:net';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -264,3 +274,156 @@ if (!PG_URL) {
     });
   });
 }
+
+/** A port nothing listens on right now, for one `os serve` child. */
+function freePort(): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    const probe = createServer();
+    probe.once('error', reject);
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address() as AddressInfo;
+      probe.close(() => resolvePort(port));
+    });
+  });
+}
+
+/**
+ * [#31715] One `os serve` boot with `OS_MIGRATE_AND_EXIT=1` against this file's
+ * database: the kernel bootstrap — its schema sync included — then an exit. A
+ * home of its own, so the boot persists nothing into the runner's.
+ */
+async function migrateAndExit(cwd: string, home: string): Promise<Run> {
+  const port = await freePort();
+  return new Promise((resolvePromise) => {
+    execFile(
+      process.execPath,
+      [CLI, 'serve', '--port', String(port), '--no-ui'],
+      {
+        cwd,
+        maxBuffer: 64 * 1024 * 1024,
+        env: {
+          ...childEnv(),
+          NODE_ENV: 'production',
+          OS_DATABASE_URL: liveUrl(),
+          OS_HOME: home,
+          OS_MIGRATE_AND_EXIT: '1',
+          OS_AUTH_SECRET: 'a1b2'.repeat(16),
+        },
+      },
+      (err, stdout, stderr) => {
+        resolvePromise({
+          code: err ? (typeof (err as { code?: unknown }).code === 'number' ? (err as unknown as { code: number }).code : 1) : 0,
+          stdout: String(stdout),
+          stderr: String(stderr),
+        });
+      },
+    );
+  });
+}
+
+/**
+ * Every `CREATE TABLE` that succeeds on this file's database, recorded by an
+ * event trigger in a schema of its own (an event trigger needs a superuser,
+ * as this cell's `CREATE DATABASE` needs `CREATEDB`). A statement that fails —
+ * the collision this cell is about — rolls its row back with it; that half is
+ * read from the boots' own output, `Schema sync FAILED`.
+ */
+const DDL_AUDIT = [
+  'create schema os_ddl_audit',
+  'create table os_ddl_audit.created (identity text not null)',
+  'create function os_ddl_audit.record() returns event_trigger language plpgsql as $$ '
+    + 'declare r record; begin '
+    + "for r in select * from pg_event_trigger_ddl_commands() where command_tag = 'CREATE TABLE' and schema_name = 'public' loop "
+    + 'insert into os_ddl_audit.created values (r.object_identity); end loop; end $$',
+  "create event trigger os_ddl_audit on ddl_command_end when tag in ('CREATE TABLE') execute function os_ddl_audit.record()",
+];
+
+const SYNC_FAILED = /Schema sync FAILED/;
+const BOOT_WAIT_LINE = /^.*Another schema migration is running on the default datasource's database.*$/gm;
+
+if (PG_URL) {
+  describe('server boots (OS_MIGRATE_AND_EXIT=1) serialize on the same lock (#31715, live postgres)', () => {
+    const BOOTS = 3;
+    let dir: string;
+    let runs: Run[] = [];
+    let control: Run;
+    let queuedBehindHolder = 0;
+    let created: string[] = [];
+    let createdByControl = -1;
+
+    beforeAll(async () => {
+      await adminExecute(`DROP DATABASE IF EXISTS "${LIVE_DATABASE}" WITH (FORCE)`);
+      await adminExecute(`CREATE DATABASE "${LIVE_DATABASE}"`);
+      dir = mkdtempSync(join(tmpdir(), 'os-boot-migration-lock-'));
+      writeFileSync(join(dir, 'objectstack.config.ts'), CONFIG);
+
+      const holder = new SqlDriver({ client: 'pg', connection: liveUrl() });
+      const knex = holder.getKnex();
+      for (const statement of DDL_AUDIT) await knex.raw(statement);
+      const session = await knex.client.acquireRawConnection();
+      try {
+        // The holder first, as the apply cell above stages it: every boot then
+        // waits by construction, and each one after the first reads the
+        // database the one before it left.
+        await knex.raw('select pg_advisory_lock(?::bigint)', [SCHEMA_MIGRATION_PG_LOCK_KEY]).connection(session);
+        const pending = Array.from({ length: BOOTS }, (_, i) => migrateAndExit(dir, join(dir, `home-${i}`)));
+        const deadline = Date.now() + CELL_TIMEOUT_MS / 2;
+        while (Date.now() < deadline) {
+          const r = await knex.raw(
+            "select count(*)::int as n from pg_locks l join pg_database d on d.oid = l.database "
+              + "where l.locktype = 'advisory' and not l.granted and d.datname = ?",
+            [LIVE_DATABASE],
+          ).connection(session) as { rows: Array<{ n: number }> };
+          queuedBehindHolder = r.rows[0].n;
+          if (queuedBehindHolder >= BOOTS) break;
+          await new Promise((r2) => setTimeout(r2, 250));
+        }
+        await knex.raw('select pg_advisory_unlock(?::bigint)', [SCHEMA_MIGRATION_PG_LOCK_KEY]).connection(session);
+        runs = await Promise.all(pending);
+      } finally {
+        await knex.client.destroyRawConnection(session);
+      }
+      const audit = async (): Promise<string[]> => {
+        const r = await knex.raw('select identity from os_ddl_audit.created order by identity') as { rows: Array<{ identity: string }> };
+        return r.rows.map((row) => row.identity);
+      };
+      try {
+        created = await audit();
+        control = await migrateAndExit(dir, join(dir, 'home-control'));
+        createdByControl = (await audit()).length - created.length;
+      } finally {
+        await holder.disconnect();
+      }
+    }, CELL_TIMEOUT_MS);
+
+    afterAll(async () => {
+      if (dir) rmSync(dir, { recursive: true, force: true });
+      await adminExecute(`DROP DATABASE IF EXISTS "${LIVE_DATABASE}" WITH (FORCE)`);
+    }, CELL_TIMEOUT_MS);
+
+    it('all three boots queued behind the held lock — the contention is staged, not a race that happened to miss', () => {
+      expect(queuedBehindHolder).toBe(BOOTS);
+    });
+
+    it('each boot exits 0 and says ONCE that it waited; none logs a failed schema sync', () => {
+      for (const run of runs) {
+        expect(run.code).toBe(0);
+        expect(`${run.stdout}${run.stderr}`.match(BOOT_WAIT_LINE)).toHaveLength(1);
+        expect(`${run.stdout}${run.stderr}`).not.toMatch(SYNC_FAILED);
+      }
+    });
+
+    it('⭐ each table is created ONCE across the three boots', () => {
+      expect(created.length).toBeGreaterThan(0);
+      expect(created).toContain('public.ml_ticket');
+      expect(new Set(created).size).toBe(created.length);
+    });
+
+    it('control — an uncontended boot prints no wait line, creates nothing, and exits 0', () => {
+      expect(control.code).toBe(0);
+      expect(createdByControl).toBe(0);
+      expect(`${control.stdout}${control.stderr}`.match(BOOT_WAIT_LINE)).toBeNull();
+      expect(`${control.stdout}${control.stderr}`).not.toMatch(SYNC_FAILED);
+    });
+  });
+}
@@ -2,149 +2,15 @@
 
 /**
  * The schema-migration lock `bootSchemaStack` (`./schema-migrate.ts`) takes on
- * a boot that can apply (#31598): one migrator per database at a time.
- *
- * Its own module, importing nothing but `node:crypto`, so the pins on it load
- * the lock and not the migration stack around it.
+ * a boot that can apply (#31598). [#31715] The module moved to
+ * `@objectstack/objectql`, whose `ObjectQLPlugin.start()` takes the same lock
+ * around every other boot's schema sync: re-exported here, never re-declared,
+ * so `os migrate apply` and a server boot lock on one name and one key.
  */
-import { createHash } from 'node:crypto';
-
-/**
- * The one name every migrator locks on (#31598): two `os migrate apply` runs
- * against one database — one per pod, from an init container on each replica —
- * otherwise both read the same pending work and both perform it. Measured on
- * Postgres before this lock: three concurrent applies against one fresh
- * database each reported creating tables (82 + 86 + 37 for 86 tables), and the
- * third applied drift on tables the others were still creating.
- *
- * ⛔ Never derived from the database name, the project or the release: every
- * CLI version that can migrate this database must take the SAME lock, or a
- * rolling upgrade runs an old and a new migrator side by side. The unit pin
- * holds the derived Postgres key to its value for that reason.
- */
-export const SCHEMA_MIGRATION_LOCK_NAME = 'objectstack:schema-migrate';
-
-/**
- * The Postgres advisory-lock key: the first 8 bytes of SHA-256 of
- * {@link SCHEMA_MIGRATION_LOCK_NAME}, as the signed 64-bit integer
- * `pg_advisory_lock(bigint)` takes. In `pg_locks` it appears with `locktype =
- * 'advisory'`, its high 32 bits as `classid` and its low 32 as `objid`.
- * A string, so no JavaScript number rounds it on the way to the bind.
- */
-export const SCHEMA_MIGRATION_PG_LOCK_KEY = BigInt.asIntN(
-  64,
-  BigInt(`0x${createHash('sha256').update(SCHEMA_MIGRATION_LOCK_NAME).digest('hex').slice(0, 16)}`),
-).toString();
-
-/**
- * How long a migrator waits for another to finish before it refuses. No
- * environment override: none exists for migration timeouts to follow.
- */
-export const SCHEMA_MIGRATION_LOCK_WAIT_MS = 10 * 60_000;
-
-/** The slice of knex the lock uses, typed structurally. */
-interface LockKnex {
-  client: {
-    dialect?: string;
-    acquireRawConnection(): Promise<unknown>;
-    destroyRawConnection(connection: unknown): Promise<void>;
-  };
-  raw(sql: string, bindings?: readonly unknown[]): { connection(connection: unknown): Promise<unknown> };
-}
-
-/** A held schema-migration lock. `release()` is idempotent and never throws. */
-export interface SchemaMigrationLock {
-  release(): Promise<void>;
-}
-
-/** The single row a lock statement answers, whichever client shaped the result. */
-function lockRow(result: unknown): Record<string, unknown> | undefined {
-  // pg answers `{ rows }`; mysql2 answers `[rows, fields]`.
-  const rows = Array.isArray(result) ? result[0] : (result as { rows?: unknown } | null)?.rows;
-  return Array.isArray(rows) ? (rows[0] as Record<string, unknown> | undefined) : undefined;
-}
-
-/**
- * Take the schema-migration lock on `driver`'s database (#31598): Postgres
- * `pg_advisory_lock`, MySQL `GET_LOCK`. Every other dialect answers `null` and
- * runs no statement — SQLite (and the Turso / WASM drivers on it) serializes
- * writers in the database file itself, and the CLI's primary database is never
- * MSSQL or Oracle (`resolveStandaloneDatabase` refuses their URL schemes).
- *
- * Uncontended, it is silent: one statement, no output. Contended, it prints
- * ONE line through `warn`, then waits up to `waitMs` and refuses on timeout —
- * this run then migrates nothing, and says so.
- *
- * The lock lives on a connection of its own, opened through the driver's own
- * client (its configuration, credentials and TLS) but OUTSIDE its pool: both
- * locks are session-scoped, so the lock and its release must run on one
- * session, which a pool does not promise; a pooled connection idle past the
- * pool's reaper would be closed and the lock released with it; and an
- * `OS_DATABASE_POOL_MAX=1` pool would have none left for the migration. A
- * session lock excludes every other session on the database, so the
- * migration's own pooled connections are serialized by it all the same.
- */
-export async function acquireSchemaMigrationLock(
-  driver: unknown,
-  opts: { database: string; warn: (line: string) => void; waitMs?: number },
-): Promise<SchemaMigrationLock | null> {
-  const knex = (driver as { getKnex?: () => LockKnex } | null)?.getKnex?.();
-  const dialect = knex?.client?.dialect;
-  if (!knex || (dialect !== 'postgresql' && dialect !== 'mysql')) return null;
-  const pg = dialect === 'postgresql';
-  const waitMs = opts.waitMs ?? SCHEMA_MIGRATION_LOCK_WAIT_MS;
-  const connection = await knex.client.acquireRawConnection();
-  const run = async (sql: string, bindings: readonly unknown[]): Promise<Record<string, unknown> | undefined> =>
-    lockRow(await knex.raw(sql, bindings).connection(connection));
-  const close = async (): Promise<void> => {
-    try { await knex.client.destroyRawConnection(connection); } catch { /* closing releases the lock anyway */ }
-  };
-  const refuse = (): Error => new Error(
-    `Refusing to migrate ${opts.database}: another schema migration still held the migration lock `
-    + `('${SCHEMA_MIGRATION_LOCK_NAME}') after ${waitMs} ms, so this run changed nothing. `
-    + 'Run it again once that migration has finished.',
-  );
-  try {
-    const tried = pg
-      ? await run('select pg_try_advisory_lock(?::bigint) as locked', [SCHEMA_MIGRATION_PG_LOCK_KEY])
-      : await run('select GET_LOCK(?, 0) as locked', [SCHEMA_MIGRATION_LOCK_NAME]);
-    if (!(tried?.locked === true || Number(tried?.locked) === 1)) {
-      opts.warn(
-        `Another schema migration is running on ${opts.database}; waiting up to `
-        + `${Math.ceil(waitMs / 1000)} s for it to finish…`,
-      );
-      if (pg) {
-        await run(`set lock_timeout = ${Math.max(1, Math.trunc(waitMs))}`, []);
-        try {
-          await run('select pg_advisory_lock(?::bigint)', [SCHEMA_MIGRATION_PG_LOCK_KEY]);
-        } catch (error) {
-          // 55P03 lock_not_available: `lock_timeout` ran out.
-          if ((error as { code?: unknown } | null)?.code === '55P03') throw refuse();
-          throw error;
-        }
-      } else {
-        // GET_LOCK answers 1 (taken), 0 (timed out) or NULL (an error).
-        const waited = await run('select GET_LOCK(?, ?) as locked', [
-          SCHEMA_MIGRATION_LOCK_NAME,
-          Math.max(1, Math.ceil(waitMs / 1000)),
-        ]);
-        if (Number(waited?.locked) !== 1) throw refuse();
-      }
-    }
-  } catch (error) {
-    await close();
-    throw error;
-  }
-  let held = true;
-  return {
-    release: async () => {
-      if (!held) return;
-      held = false;
-      try {
-        if (pg) await run('select pg_advisory_unlock(?::bigint)', [SCHEMA_MIGRATION_PG_LOCK_KEY]);
-        else await run('select RELEASE_LOCK(?)', [SCHEMA_MIGRATION_LOCK_NAME]);
-      } catch { /* closing the session below releases it */ }
-      await close();
-    },
-  };
-}
+export {
+  acquireSchemaMigrationLock,
+  SCHEMA_MIGRATION_LOCK_NAME,
+  SCHEMA_MIGRATION_LOCK_WAIT_MS,
+  SCHEMA_MIGRATION_PG_LOCK_KEY,
+} from '@objectstack/objectql';
+export type { SchemaMigrationLock } from '@objectstack/objectql';
@@ -5063,6 +5063,15 @@ export class SqlDriver implements IDataDriver {
     return DeferredDdlFacet.setDeferredDdl.call(deferredDdlHost.of(this), deferred);
   }
 
+  /**
+   * [#31715] Whether {@link setDeferredDdl} holds this driver's schema DDL back
+   * right now. The engine's boot reads it to leave the schema-migration lock to
+   * the command that deferred the DDL, which takes it before the flush.
+   */
+  get schemaDdlDeferred(): boolean {
+    return this.deferredDdl;
+  }
+
   /** How many objects are waiting for {@link flushDeferredSchemaDdl}. */
   get deferredSchemaObjectCount(): number {
     return this.deferredSchemaObjects.size;
 
@@ -1107,8 +1107,13 @@ export const REMOTE_FACE_ANSWERS = {
   // declares, the input its drift detector diffs against.
   registerObjectMetadata: 'remote',
   // Deferred DDL: arming is refused, so nothing is ever deferred here, and the
-  // three inherited members answer that truthfully without reaching Knex.
+  // four inherited members answer that truthfully without reaching Knex
+  // (`schemaDdlDeferred` reads `false`, so the engine's boot asks for the
+  // schema-migration lock, #31715; the lock reads `dialectName`, `'sqlite'`
+  // here, and answers `null` WITHOUT calling `getKnex()`, which this face
+  // refuses by throwing).
   setDeferredDdl: 'refused',
+  schemaDdlDeferred: 'inherited',
   deferredSchemaObjectCount: 'inherited',
   previewDeferredSchemaWork: 'inherited',
   flushDeferredSchemaDdl: 'inherited',