fix(db): bootstrap migrations on local-tier gateway startup

Fresh `mosaic gateway install` (npm) left the gateway DB schema empty —
sign-in 500'd with `relation "users" does not exist`, and every entry
point (auth, bootstrap setup) failed because they all query the users
table first. Five stacked bugs on the local (PGlite) tier:

1. `packages/db/package.json` `files: ["dist"]` excluded the `drizzle/`
   SQL migrations from the published tarball.
2. `runMigrations()` only supports postgres-js — unusable for embedded
   PGlite.
3. `apps/gateway/src/database/database.module.ts` never invoked
   migrations at startup.
4. `createPgliteDb` didn't load pgvector, so migration 0001's
   `CREATE EXTENSION vector` failed.
5. Drizzle's PG migrator wraps every migration in one outer
   transaction, which trips Postgres' `check_safe_enum_use` on
   migration 0009 (`ALTER TYPE ADD VALUE 'pending'` → `SET DEFAULT
   'pending'` in the same tx).

Changes:
- Ship `drizzle/` in the published tarball.
- `createPgliteDb` loads `@electric-sql/pglite/vector`.
- New `runPgliteMigrations(handle)` walks the Drizzle journal and
  runs each statement-breakpoint chunk through PGlite's `client.exec()`
  (autocommit per statement). Records into `drizzle.__drizzle_migrations`
  for interop with the postgres-js path. Per-statement try/catch
  surfaces which statement of which migration failed.
- `DatabaseModule` runs migrations in `OnModuleInit` before
  `app.listen()`. Local tier: explicit `runPgliteMigrations` then
  `storageAdapter.migrate()`. Postgres tier: just `storageAdapter.migrate()`,
  which already calls `runMigrations(url)` internally — no double-call.
- Removed `packages/storage/src/test-utils/pglite-with-vector.ts`. The
  "intentionally not exported" rationale is moot now that migration
  0001 forces pgvector load anyway. The integration test uses
  `createPgliteDb` + `runPgliteMigrations` from `@mosaicstack/db`.

Tests: BetterAuth tables exist after migrate; idempotent (re-runs 0009);
partial-failure surfaces statement-level context and leaves no ledger row.

QA on a fresh PGlite install:
- `Applying PGlite schema migrations...` then `Initializing storage
  adapter (pglite)...` in startup log.
- `GET /api/bootstrap/status` → `{"needsSetup":true}` HTTP 200 (was 500).
- `POST /api/bootstrap/setup` reaches Zod validator (was 500).

Scope: this PR fixes the local (PGlite) tier. Postgres-tier first
install still has the outer-transaction problem and a journal ordering
bug (0009's `when` < 0008's). Documented inline as TODO and in the
scratchpad — needs a separate change with real-Postgres validation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/db/package.json

@@ -42,6 +42,7 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "drizzle"
   ]
 }

packages/db/src/client-pglite.ts

@@ -1,10 +1,12 @@
 import { PGlite } from '@electric-sql/pglite';
+import { vector } from '@electric-sql/pglite/vector';
 import { drizzle } from 'drizzle-orm/pglite';
 import * as schema from './schema.js';
 import type { DbHandle } from './client.js';
 
 export function createPgliteDb(dataDir: string): DbHandle {
-  const client = new PGlite(dataDir);
+  // pgvector extension is required by migration 0001 (insights.embedding column).
+  const client = new PGlite(dataDir, { extensions: { vector } });
   const db = drizzle(client, { schema });
   return {
     db: db as unknown as DbHandle['db'],

packages/db/src/index.ts

@@ -1,6 +1,6 @@
 export { createDb, type Db, type DbHandle } from './client.js';
 export { createPgliteDb } from './client-pglite.js';
-export { runMigrations } from './migrate.js';
+export { runMigrations, runPgliteMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
 export {

packages/db/src/migrate.test.ts

@@ -0,0 +1,70 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sql } from 'drizzle-orm';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createPgliteDb } from './client-pglite.js';
+import { runPgliteMigrations } from './migrate.js';
+import type { DbHandle } from './client.js';
+
+interface PgliteExec {
+  exec(query: string): Promise<unknown>;
+}
+
+describe('runPgliteMigrations', () => {
+  let dataDir: string;
+  let handle: DbHandle;
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), 'mosaic-db-migrate-test-'));
+    handle = createPgliteDb(dataDir);
+  });
+
+  afterEach(async () => {
+    await handle.close();
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('creates the BetterAuth tables required by the gateway', async () => {
+    await runPgliteMigrations(handle);
+
+    const result = (await handle.db.execute(sql`
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public'
+      ORDER BY table_name
+    `)) as unknown as { rows: Array<{ table_name: string }> };
+
+    const tables = result.rows.map((r) => r.table_name);
+
+    // Auth tables — required for sign-in / bootstrap to function.
+    expect(tables).toContain('users');
+    expect(tables).toContain('sessions');
+    expect(tables).toContain('accounts');
+    expect(tables).toContain('verifications');
+
+    // Schema sanity check — admin token table consumed by mosaic gateway config.
+    expect(tables).toContain('admin_tokens');
+  });
+
+  it('is idempotent — running twice does not error', async () => {
+    await runPgliteMigrations(handle);
+    await expect(runPgliteMigrations(handle)).resolves.toBeUndefined();
+  });
+
+  it('surfaces statement-level error context on failure and leaves no ledger row', async () => {
+    // Pre-create a `users` table that conflicts with migration 0000's CREATE TABLE,
+    // forcing it to fail without IF NOT EXISTS.
+    const client = (handle.db as unknown as { $client: PgliteExec }).$client;
+    await client.exec('CREATE TABLE users (sentinel text)');
+
+    await expect(runPgliteMigrations(handle)).rejects.toThrow(
+      /migration hash=[a-f0-9]+ statement #\d+ failed/,
+    );
+
+    // Ledger should be empty — partial application must not pretend to be complete.
+    const ledger = (await handle.db.execute(
+      sql`SELECT count(*)::int AS count FROM drizzle.__drizzle_migrations`,
+    )) as unknown as { rows: Array<{ count: number }> };
+    expect(ledger.rows[0]?.count).toBe(0);
+  });
+});

packages/db/src/migrate.ts

@@ -1,18 +1,109 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { drizzle } from 'drizzle-orm/postgres-js';
-import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import { sql } from 'drizzle-orm';
+import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
+import { migrate as migratePostgres } from 'drizzle-orm/postgres-js/migrator';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
 import postgres from 'postgres';
 import { DEFAULT_DATABASE_URL } from './defaults.js';
+import type { DbHandle } from './client.js';
+
+interface PgliteExecutor {
+  exec(query: string): Promise<unknown>;
+}
+
+interface ExecuteRows<T> {
+  rows: T[];
+}
+
+function migrationsFolder(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '../drizzle');
+}
 
 export async function runMigrations(url?: string): Promise<void> {
   const connectionString = url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
-  const sql = postgres(connectionString, { max: 1 });
-  const db = drizzle(sql);
-  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const sqlClient = postgres(connectionString, { max: 1 });
+  const db = drizzlePostgres(sqlClient);
   try {
-    await migrate(db, { migrationsFolder: resolve(__dirname, '../drizzle') });
+    // TODO: postgres-tier first-install also fails because (a) Drizzle wraps every
+    // migration in one transaction (breaks 0009's ALTER TYPE ADD VALUE → SET DEFAULT
+    // sequence) and (b) drizzle/meta/_journal.json has 0009 ordered before 0008,
+    // which the postgres-js migrator skips by `created_at < folderMillis`. The
+    // PGlite path below sidesteps both. A follow-up should either share the
+    // per-statement loop (see runPgliteMigrations) or fix the journal ordering.
+    await migratePostgres(db, { migrationsFolder: migrationsFolder() });
   } finally {
-    await sql.end();
+    await sqlClient.end();
+  }
+}
+
+// Apply Drizzle migrations against an embedded PGlite database.
+//
+// We don't reuse drizzle's pglite migrator because it wraps ALL migrations in
+// one outer transaction, which breaks Postgres' `check_safe_enum_use` rule —
+// e.g. migration 0009 does `ALTER TYPE ADD VALUE 'pending'` then references
+// `'pending'` as a default in the same tx. PGlite's `exec()` runs each
+// statement under the Simple Query protocol, autocommitting between them.
+//
+// We still write to the standard `drizzle.__drizzle_migrations` ledger so the
+// result is interoperable with `runMigrations()` on a postgres-backed deploy
+// (modulo the journal-ordering bug noted above).
+//
+// We skip-by-hash rather than skip-by-folderMillis (which is what Drizzle's
+// postgres-js migrator does). That's deliberate — out-of-order timestamps in
+// `_journal.json` won't silently drop migrations.
+//
+// Failure model: each statement autocommits, and the ledger row is written
+// only after all statements in a migration succeed. A crash mid-migration
+// leaves the prefix applied with no ledger entry, so the next boot will
+// replay those statements and fail loudly on "already exists". Recovery:
+// drop the partially-applied objects, or insert the migration's hash into
+// `drizzle.__drizzle_migrations` manually. The error log identifies which
+// statement of which migration was the culprit.
+export async function runPgliteMigrations(handle: DbHandle): Promise<void> {
+  const client = (handle.db as unknown as { $client?: PgliteExecutor }).$client;
+  if (!client || typeof client.exec !== 'function') {
+    throw new Error('runPgliteMigrations: handle.db is not backed by a PGlite client');
+  }
+
+  await client.exec('CREATE SCHEMA IF NOT EXISTS drizzle');
+  await client.exec(`
+    CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+      id SERIAL PRIMARY KEY,
+      hash text NOT NULL,
+      created_at bigint
+    )
+  `);
+
+  const appliedRows = (await handle.db.execute(
+    sql`SELECT hash FROM drizzle.__drizzle_migrations`,
+  )) as unknown as ExecuteRows<{ hash: string }>;
+  const applied = new Set(appliedRows.rows.map((r) => r.hash));
+
+  const migrations = readMigrationFiles({ migrationsFolder: migrationsFolder() });
+  for (const migration of migrations) {
+    if (applied.has(migration.hash)) continue;
+
+    // Run each statement-breakpoint chunk in its own exec() call so PGlite
+    // commits between statements — this is what lets `ALTER TYPE ADD VALUE`
+    // become visible before a subsequent statement references the new value.
+    for (const [stmtIdx, stmt] of migration.sql.entries()) {
+      const trimmed = stmt.trim();
+      if (!trimmed) continue;
+      try {
+        await client.exec(trimmed);
+      } catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `runPgliteMigrations: migration hash=${migration.hash} statement #${stmtIdx} failed: ${cause}\n` +
+            `Statement: ${trimmed.slice(0, 200)}${trimmed.length > 200 ? '…' : ''}`,
+          { cause: err },
+        );
+      }
+    }
+    await handle.db.execute(
+      sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${migration.hash}, ${migration.folderMillis})`,
+    );
   }
 }