orez 0.2.26 → 0.2.29

package/src/index.ts

@@ -1,1215 +0,0 @@
-/**
- * orez: pglite-powered zero-sync development backend.
- *
- * starts a pglite instance, tcp proxy, and zero-cache process.
- * replaces docker-based postgresql and zero-cache with a single
- * `bun run` command.
- */
-
-import { spawn, spawnSync, type ChildProcess } from 'node:child_process'
-import { randomUUID } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-
-import {
-  createHttpLogStore,
-  startHttpProxy,
-  type HttpLogStore,
-} from './admin/http-proxy.js'
-import { createLogStore, type LogStore } from './admin/log-store.js'
-import {
-  isChildProcessRunning,
-  isPidRunning,
-  killProcessTree,
-  waitForChildProcessExit,
-} from './child-process.js'
-import { getConfig, getConnectionString } from './config.js'
-import { log, port, setLogLevel, setLogStore } from './log.js'
-import { DoBackend } from './pg-proxy-do-backend.js'
-import { startPgProxy } from './pg-proxy.js'
-import {
-  createPGliteInstances,
-  createPGliteWorkerInstances,
-  createSinglePGliteInstance,
-  createSinglePGliteWorkerInstance,
-  createPGliteWorker,
-  runMigrations,
-  startPeriodicCheckpoint,
-} from './pglite-manager.js'
-import { findPort } from './port.js'
-import { orezTitle } from './process-title.js'
-import {
-  cleanCdcStateOnStartup,
-  hasCdcCorruptionSignature,
-  recoverFromCdcCorruption,
-} from './recovery.js'
-import { installChangeTracking } from './replication/change-tracker.js'
-import { resetReplicationState } from './replication/handler.js'
-import {
-  applySqliteMode,
-  cleanupShim,
-  formatNativeBootstrapInstructions,
-  hasMissingNativeBinarySignature,
-  inspectNativeSqliteBinary,
-  resolveSqliteMode,
-  resolveSqliteModeConfig,
-  type SqliteMode,
-  type SqliteModeConfig,
-} from './sqlite-mode/index.js'
-
-import type { ZeroLiteConfig } from './config.js'
-import type { PGlite } from '@electric-sql/pglite'
-
-type ZeroChildProcess = ChildProcess & { __orezTail?: string[] }
-
-function ensureDoBackendNamespace(dataDir: string): string {
-  const marker = resolve(dataDir, 'do-backend-namespace')
-  if (existsSync(marker)) {
-    const existing = readFileSync(marker, 'utf8').trim()
-    if (existing) return existing
-  }
-  const next = randomUUID()
-  writeFileSync(marker, `${next}\n`)
-  return next
-}
-
-function resolveNodeBinary(): string {
-  const explicitNode = process.env.NODE
-  if (explicitNode && existsSync(explicitNode)) {
-    return explicitNode
-  }
-
-  if (process.execPath.endsWith('/node')) {
-    return process.execPath
-  }
-
-  const whichResult = spawnSync('which', ['node'], {
-    encoding: 'utf8',
-    env: process.env,
-  })
-  const candidate = whichResult.stdout?.trim()
-  if (whichResult.status === 0 && candidate && existsSync(candidate)) {
-    return candidate
-  }
-
-  throw new Error(
-    'could not resolve a node binary for zero-cache; set process.env.NODE or ensure node is in PATH'
-  )
-}
-
-export { defineConfig, getConfig, getConnectionString } from './config.js'
-export type { Hook, LogLevel, OrezConfig, ZeroLiteConfig } from './config.js'
-export { installChangeTracking } from './replication/change-tracker.js'
-
-// helper to run a hook (string command or callback function)
-async function runHook(
-  hook: string | (() => void | Promise<void>) | undefined,
-  name: string,
-  env: Record<string, string>
-): Promise<void> {
-  if (!hook) return
-
-  if (typeof hook === 'function') {
-    log.debug.orez(`running ${name} callback`)
-    await hook()
-    log.orez(`${name} done`)
-    return
-  }
-
-  // string command
-  log.debug.orez(`running ${name}: ${hook}`)
-  await new Promise<void>((resolve, reject) => {
-    const child = spawn(hook, {
-      shell: true,
-      stdio: 'inherit',
-      env: { ...process.env, ...env },
-    })
-    child.on('exit', (code) => {
-      if (code === 0) {
-        log.orez(`${name} done`)
-        resolve()
-      } else {
-        reject(new Error(`${name} exited with code ${code}`))
-      }
-    })
-    child.on('error', reject)
-  })
-}
-
-function getManagedPublicationConfig(): { names: string[]; managedByOrez: boolean } {
-  const existing = process.env.ZERO_APP_PUBLICATIONS?.trim()
-  if (existing) {
-    const names = existing
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean)
-    return { names, managedByOrez: false }
-  }
-
-  const appId = (process.env.ZERO_APP_ID || 'zero').trim() || 'zero'
-  const fallback = `orez_${appId}_public`
-  process.env.ZERO_APP_PUBLICATIONS = fallback
-  return { names: [fallback], managedByOrez: true }
-}
-
-async function syncManagedPublications(
-  db: PGlite,
-  names: string[],
-  managedByOrez: boolean
-): Promise<void> {
-  if (!managedByOrez || names.length === 0) return
-
-  const tables = await db.query<{ tablename: string }>(
-    `SELECT tablename
-     FROM pg_tables
-     WHERE schemaname = 'public'
-       AND tablename NOT LIKE '_zero_%'`
-  )
-  const publicTables = tables.rows
-    .map((r) => r.tablename)
-    .filter((t) => !t.startsWith('_'))
-
-  for (const pub of names) {
-    const quotedPub = '"' + pub.replace(/"/g, '""') + '"'
-    await db.exec(`CREATE PUBLICATION ${quotedPub}`).catch(() => {})
-
-    if (publicTables.length === 0) continue
-    const inPub = await db.query<{ tablename: string }>(
-      `SELECT tablename
-       FROM pg_publication_tables
-       WHERE pubname = $1
-         AND schemaname = 'public'`,
-      [pub]
-    )
-    const inPubSet = new Set(inPub.rows.map((r) => r.tablename))
-    const toAdd = publicTables.filter((t) => !inPubSet.has(t))
-    if (toAdd.length === 0) continue
-    const tableList = toAdd.map((t) => `"public"."${t.replace(/"/g, '""')}"`).join(', ')
-    await db.exec(`ALTER PUBLICATION ${quotedPub} ADD TABLE ${tableList}`)
-    log.debug.orez(`added ${toAdd.length} table(s) to publication "${pub}"`)
-  }
-}
-
-/**
- * ensure publications have table membership after on-db-ready.
- * handles the case where orez pre-created an empty publication and the app's
- * migration skipped adding tables because the publication already existed.
- */
-async function ensurePublicationHasTables(db: PGlite, names: string[]): Promise<void> {
-  for (const pub of names) {
-    const inPub = await db.query<{ count: string }>(
-      `SELECT count(*)::text as count FROM pg_publication_tables
-       WHERE pubname = $1 AND schemaname = 'public'`,
-      [pub]
-    )
-    if (Number(inPub.rows[0]?.count) > 0) continue
-
-    // publication exists but has no tables — add all public tables
-    const pubExists = await db.query<{ count: string }>(
-      `SELECT count(*)::text as count FROM pg_publication WHERE pubname = $1`,
-      [pub]
-    )
-    if (Number(pubExists.rows[0]?.count) === 0) continue
-
-    const tables = await db.query<{ tablename: string }>(
-      `SELECT tablename FROM pg_tables
-       WHERE schemaname = 'public'
-         AND tablename NOT LIKE '_zero_%'
-         AND tablename NOT LIKE '\\_%'`
-    )
-    if (tables.rows.length === 0) continue
-
-    const tableList = tables.rows
-      .map((t) => `"public"."${t.tablename.replace(/"/g, '""')}"`)
-      .join(', ')
-    const quotedPub = '"' + pub.replace(/"/g, '""') + '"'
-    await db.exec(`ALTER PUBLICATION ${quotedPub} ADD TABLE ${tableList}`)
-    log.orez(`publication "${pub}" was empty, added ${tables.rows.length} table(s)`)
-  }
-}
-
-// resolvePackage moved to sqlite-mode/resolve-mode.ts
-import { resolvePackage } from './sqlite-mode/resolve-mode.js'
-
-export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
-  const config = getConfig(overrides)
-  setLogLevel(config.logLevel)
-
-  // find available ports
-  const pgPort = await findPort(config.pgPort)
-  const zeroPort = config.skipZeroCache
-    ? config.zeroPort
-    : await findPort(config.zeroPort)
-  const adminPort = config.adminPort > 0 ? await findPort(config.adminPort) : 0
-  if (pgPort !== config.pgPort)
-    log.debug.orez(`port ${config.pgPort} in use, using ${pgPort}`)
-  if (!config.skipZeroCache && zeroPort !== config.zeroPort)
-    log.debug.orez(`port ${config.zeroPort} in use, using ${zeroPort}`)
-  if (adminPort > 0 && adminPort !== config.adminPort)
-    log.debug.orez(`port ${config.adminPort} in use, using ${adminPort}`)
-  config.pgPort = pgPort
-  config.zeroPort = zeroPort
-  config.adminPort = adminPort
-
-  // create log store for admin dashboard
-  const logStore: LogStore | undefined =
-    adminPort > 0
-      ? createLogStore(config.dataDir, !config.disableDiskLogs, config.maxLogFileSize)
-      : undefined
-
-  // wire up logStore so all log.* calls flow to admin dashboard
-  setLogStore(logStore)
-
-  // create http log store for HTTP tab
-  const httpLog: HttpLogStore | undefined =
-    adminPort > 0 ? createHttpLogStore() : undefined
-
-  log.debug.orez(`data dir: ${resolve(config.dataDir)}`)
-
-  // resolve sqlite mode config early (used for shim application and cleanup)
-  // auto-detects native if available, falls back to wasm
-  let sqliteMode = resolveSqliteMode(config.disableWasmSqlite, config.forceWasmSqlite)
-  let sqliteModeConfig = resolveSqliteModeConfig(
-    config.disableWasmSqlite,
-    config.forceWasmSqlite
-  )
-  if (sqliteMode === 'wasm' && !sqliteModeConfig) {
-    log.orez(
-      'warning: wasm sqlite requested but dependencies are missing, falling back to native'
-    )
-    sqliteMode = 'native'
-    config.disableWasmSqlite = true
-    sqliteModeConfig = resolveSqliteModeConfig(true, false)
-  }
-
-  mkdirSync(config.dataDir, { recursive: true })
-
-  // write pid file for IPC (pg_restore uses this to signal restart).
-  // before overwriting, check for orphaned zero-cache processes from a
-  // previous orez run that didn't shut down cleanly (e.g. SIGKILL'd before
-  // the in-process watchdog could notice). sweep anything still holding
-  // the zero port so the new run can bind.
-  const pidFile = resolve(config.dataDir, 'orez.pid')
-  if (!config.skipZeroCache && process.platform !== 'win32') {
-    try {
-      const priorPid = Number(readFileSync(pidFile, 'utf8').trim())
-      if (priorPid > 0 && priorPid !== process.pid && !isPidRunning(priorPid)) {
-        const result = spawnSync('lsof', ['-ti', `:${config.zeroPort}`], {
-          encoding: 'utf8',
-        })
-        const orphans = (result.stdout || '')
-          .split(/\s+/)
-          .map((v) => Number(v.trim()))
-          .filter((v) => Number.isInteger(v) && v > 0 && v !== process.pid)
-        for (const pid of orphans) {
-          log.orez(
-            `killing orphan pid ${pid} holding zero port ${config.zeroPort} from previous orez run`
-          )
-          try {
-            killProcessTree(pid, 'SIGKILL')
-          } catch {}
-        }
-      }
-    } catch {}
-  }
-  writeFileSync(pidFile, String(process.pid))
-
-  // write admin port file so pg_restore can find it
-  const adminFile = resolve(config.dataDir, 'orez.admin')
-  if (adminPort > 0) {
-    writeFileSync(adminFile, String(adminPort))
-  }
-
-  // remove any stale ready marker from a previous run so external waiters
-  // (e.g. CI scripts) don't see a stale "ready" before this run finishes
-  // initializing. the marker is (re-)written after on-db-ready completes.
-  const readyFile = resolve(config.dataDir, 'orez.ready')
-  try {
-    unlinkSync(readyFile)
-  } catch {}
-
-  // start pglite instance(s).
-  // single-db mode uses one instance for all databases (lighter for constrained envs).
-  // otherwise, separate instances for postgres, zero_cvr, zero_cdb with optional
-  // worker threads for non-blocking WASM execution.
-
-  // ── DO backend path (replaces PGlite) ──────────────────────────────
-  let instances: any, db: any, stopCheckpoint: any
-  let migrationsApplied = 0
-  let isDoBackend = false
-
-  if (config.doBackendUrl) {
-    isDoBackend = true
-    log.orez(`using DO backend: ${config.doBackendUrl}`)
-    const backendUrl = config.doBackendUrl.replace(/\/+$/, '')
-    const doNamespace = ensureDoBackendNamespace(config.dataDir)
-    const doInstances = {
-      postgres: new DoBackend(backendUrl, 'postgres', doNamespace),
-      cvr: new DoBackend(backendUrl, 'zero_cvr', doNamespace),
-      cdb: new DoBackend(backendUrl, 'zero_cdb', doNamespace),
-      postgresReplicas: [],
-    }
-    await Promise.all([
-      doInstances.postgres.waitReady,
-      doInstances.cvr.waitReady,
-      doInstances.cdb.waitReady,
-    ])
-    instances = doInstances
-    db = doInstances.postgres
-    stopCheckpoint = () => {}
-  } else {
-    // ── PGlite backend (default) ────────────────────────────────────────────
-    instances = config.singleDb
-      ? config.useWorkerThreads
-        ? await createSinglePGliteWorkerInstance(config)
-        : await createSinglePGliteInstance(config)
-      : config.useWorkerThreads
-        ? await createPGliteWorkerInstances(config)
-        : await createPGliteInstances(config)
-    db = instances.postgres
-
-    // periodic WAL checkpoint
-    stopCheckpoint =
-      config.checkpointIntervalMs > 0
-        ? startPeriodicCheckpoint(instances, config.checkpointIntervalMs)
-        : () => {}
-
-    // config-based publications
-    if (config.zeroPublications && !process.env.ZERO_APP_PUBLICATIONS) {
-      process.env.ZERO_APP_PUBLICATIONS = config.zeroPublications
-    }
-
-    // run migrations & change tracking
-    migrationsApplied = await runMigrations(db, config)
-    log.debug.orez('installing change tracking')
-    await installChangeTracking(db)
-  }
-
-  // shared: publications config
-  if (config.zeroPublications && !process.env.ZERO_APP_PUBLICATIONS) {
-    process.env.ZERO_APP_PUBLICATIONS = config.zeroPublications
-  }
-  const managedPub = getManagedPublicationConfig()
-  if (managedPub.managedByOrez) {
-    log.debug.orez(`using managed publication: ${managedPub.names.join(', ')}`)
-  }
-
-  // sync publications. for DO backend this goes through the TCP proxy, which
-  // rewrites the catalog queries and forwards CREATE PUBLICATION / ALTER PUBLICATION
-  // as no-ops or DO-native equivalents (PGlite still owns the real path).
-  await syncManagedPublications(db, managedPub.names, managedPub.managedByOrez)
-
-  // start tcp proxy (routes connections to correct instance by database name)
-  const pgServer = await startPgProxy(instances, config)
-
-  if (migrationsApplied > 0)
-    log.orez(
-      `${migrationsApplied} migration${migrationsApplied === 1 ? '' : 's'} applied`
-    )
-
-  // seed data if needed
-  await seedIfNeeded(db, config)
-
-  // run on-db-ready hook (e.g. migrations) before zero-cache starts
-  if (config.onDbReady) {
-    const upstreamUrl = getConnectionString(config, 'postgres')
-    const cvrUrl = getConnectionString(config, 'zero_cvr')
-    const cdbUrl = getConnectionString(config, 'zero_cdb')
-    await runHook(config.onDbReady, 'on-db-ready', {
-      ZERO_UPSTREAM_DB: upstreamUrl,
-      ZERO_CVR_DB: cvrUrl,
-      ZERO_CHANGE_DB: cdbUrl,
-      DATABASE_URL: upstreamUrl,
-      OREZ_PG_PORT: String(config.pgPort),
-    })
-
-    // re-sync publication membership
-    await syncManagedPublications(db, managedPub.names, managedPub.managedByOrez)
-    await ensurePublicationHasTables(db, managedPub.names)
-    log.debug.orez('re-installing change tracking after on-db-ready')
-    await installChangeTracking(db)
-  }
-
-  if (isDoBackend) {
-    await installChangeTracking(db)
-  }
-
-  // write the ready marker so external orchestrators (e.g. CI scripts that
-  // currently `wait:ports 6434`) can wait for orez to be fully initialized.
-  // important: the pg port is bound earlier (startPgProxy above) so that
-  // on-db-ready can connect, but external clients connecting before this
-  // marker exists race with on-db-ready and corrupt transaction state on
-  // the shared pglite session.
-  writeFileSync(readyFile, String(Date.now()))
-
-  // create read replicas after the primary is fully initialized
-  // (migrations, seed, change tracking, publications all set up)
-  if (config.readReplicas > 0 && config.useWorkerThreads) {
-    const { createReadReplicas } = await import('./pglite-manager.js')
-    instances.postgresReplicas = await createReadReplicas(db, config.readReplicas, config)
-  }
-
-  // clean up stale lock files from previous crash (keep replica for fast restart).
-  // if lock files were present, it means the previous shutdown was unclean (SIGKILL)
-  // and CDC state may be corrupt — clean it along with the replica to avoid
-  // duplicate watermark errors when zero-cache tries to replay changes.
-  const hadStaleLocks = cleanupStaleLockFiles(config)
-  if (hadStaleLocks) {
-    log.debug.orez('unclean shutdown detected, cleaning CDC state and replica')
-    cleanupStaleReplica(config)
-    await cleanCdcStateOnStartup(instances.cdb)
-  }
-
-  // when admin is enabled, zero-cache runs on internal port with http proxy in front
-  let zeroInternalPort = config.zeroPort
-  let httpProxyServer: import('node:net').Server | null = null
-  if (httpLog && !config.skipZeroCache) {
-    zeroInternalPort = await findPort(config.zeroPort + 1000)
-    log.debug.orez(`http proxy: public ${config.zeroPort} → internal ${zeroInternalPort}`)
-  }
-
-  // start zero-cache
-  let zeroCacheProcess: ChildProcess | null = null
-  let zeroEnv: Record<string, string> = {}
-  if (!config.skipZeroCache) {
-    // use internal port when http proxy is enabled
-    const zeroConfig = httpLog ? { ...config, zeroPort: zeroInternalPort } : config
-
-    // helper to start zero-cache and wait for it (including stability check)
-    const tryStartZeroCache = async () => {
-      const result = await startZeroCache(
-        zeroConfig,
-        logStore,
-        sqliteMode,
-        sqliteModeConfig
-      )
-      zeroCacheProcess = result.process
-      zeroEnv = result.env
-      await waitForZeroCache(zeroConfig, zeroCacheProcess, 60000, sqliteMode)
-
-      // stability check: wait a bit to catch early crashes (e.g. change-streamer)
-      // zero-cache can pass health check but crash shortly after when workers start
-      await new Promise((r) => setTimeout(r, 2000))
-      if (zeroCacheProcess.exitCode !== null) {
-        const tail = (zeroCacheProcess as ZeroChildProcess).__orezTail
-        const details = tail?.length ? tail.slice(-20).join('\n') : ''
-        throw new Error(`zero-cache crashed during startup stability check\n${details}`)
-      }
-    }
-
-    try {
-      await tryStartZeroCache()
-    } catch (err: any) {
-      const errMsg = err?.message || String(err)
-      // check for CDC corruption (duplicate key in changeLog)
-      if (hasCdcCorruptionSignature(errMsg)) {
-        await recoverFromCdcCorruption({
-          config,
-          instances,
-          zeroCacheProcess,
-        })
-        log.orez('retrying zero-cache startup...')
-        await tryStartZeroCache()
-        log.orez('CDC corruption auto-recovery successful')
-      } else if (
-        // native sqlite failed to load at runtime - fallback to wasm
-        sqliteMode === 'native' &&
-        !config.disableWasmSqlite &&
-        hasMissingNativeBinarySignature(errMsg)
-      ) {
-        log.orez('native sqlite failed to load, falling back to wasm...')
-        sqliteMode = 'wasm'
-        sqliteModeConfig = resolveSqliteModeConfig(false, true) // force wasm
-        await tryStartZeroCache()
-        log.orez('wasm fallback successful')
-      } else {
-        // unrecoverable error, rethrow
-        throw err
-      }
-    }
-
-    // start http proxy in front of zero-cache when admin is enabled
-    // also exposes read-only /__orez/api/logs and /__orez/api/status
-    if (httpLog) {
-      httpProxyServer = await startHttpProxy({
-        listenPort: config.zeroPort,
-        targetPort: zeroInternalPort,
-        httpLog,
-        logStore,
-        config,
-        startTime: Date.now(),
-      })
-      log.debug.orez(`http proxy listening on ${config.zeroPort}`)
-    }
-
-    log.zero(`ready ${port(config.zeroPort, 'magenta')} (sqlite: ${sqliteMode})`)
-  } else {
-    log.orez('skip zero-cache')
-  }
-
-  // run on-healthy hook after all services are ready
-  if (config.onHealthy) {
-    await runHook(config.onHealthy, 'on-healthy', {
-      OREZ_PG_PORT: String(config.pgPort),
-      OREZ_ZERO_PORT: String(config.zeroPort),
-    })
-  }
-
-  const killZeroCache = async () => {
-    const child = zeroCacheProcess
-    if (!isChildProcessRunning(child)) return
-
-    try {
-      child.kill('SIGTERM')
-    } catch (err: any) {
-      if (err?.code !== 'ESRCH') throw err
-      return
-    }
-
-    const exitedGracefully = await waitForChildProcessExit(child, 5000)
-    if (exitedGracefully) return
-
-    log.debug.orez(
-      `zero-cache pid ${child.pid} did not exit after SIGTERM, force killing`
-    )
-    if (child.pid) killProcessTree(child.pid, 'SIGKILL')
-    else child.kill('SIGKILL')
-    await waitForChildProcessExit(child, 1000)
-  }
-
-  // simple restart without any state cleanup
-  const restartZeroCache = async () => {
-    await killZeroCache()
-    // use internal port when http proxy is enabled
-    const zeroConfig = httpLog ? { ...config, zeroPort: zeroInternalPort } : config
-    const result = await startZeroCache(
-      zeroConfig,
-      logStore,
-      sqliteMode,
-      sqliteModeConfig
-    )
-    zeroCacheProcess = result.process
-    zeroEnv = result.env
-    await waitForZeroCache(zeroConfig, zeroCacheProcess, 60000, sqliteMode)
-  }
-
-  // unified reset function for zero state
-  // modes:
-  //   'cache-only' - deletes replica file only (fast, for minor sync issues)
-  //   'full' - deletes CVR/CDB + replica and recreates instances (for schema changes)
-  let resetInProgress = false
-  const resetFile = resolve(config.dataDir, 'orez.resetting')
-  const resetZeroState = async (mode: 'cache-only' | 'full'): Promise<void> => {
-    if (resetInProgress) {
-      log.orez('reset already in progress, skipping')
-      return
-    }
-    resetInProgress = true
-    // write marker file so pg_restore can wait for reset to complete
-    writeFileSync(resetFile, String(Date.now()))
-
-    try {
-      log.orez(`resetting zero state (${mode})...`)
-
-      // stop zero-cache first
-      log.orez('stopping zero-cache...')
-      await killZeroCache()
-      log.orez('zero-cache stopped')
-
-      if (mode === 'full') {
-        // give connections time to drain before closing instances
-        await new Promise((r) => setTimeout(r, 500))
-
-        // close CVR/CDB instances
-        log.orez('closing CVR/CDB...')
-        await instances.cvr.close().catch((e: any) => {
-          log.debug.orez(`cvr close error (expected): ${e?.message || e}`)
-        })
-        await instances.cdb.close().catch((e: any) => {
-          log.debug.orez(`cdb close error (expected): ${e?.message || e}`)
-        })
-        log.orez('CVR/CDB closed')
-
-        // delete CVR/CDB data directories
-        log.orez('deleting CVR/CDB data...')
-        const { rmSync } = await import('node:fs')
-        for (const dir of ['pgdata-cvr', 'pgdata-cdb']) {
-          try {
-            rmSync(resolve(config.dataDir, dir), { recursive: true, force: true })
-          } catch {}
-        }
-
-        // recreate CVR/CDB instances
-        log.orez('recreating CVR/CDB...')
-        if (config.useWorkerThreads) {
-          const cvrProxy = createPGliteWorker(
-            resolve(config.dataDir, 'pgdata-cvr'),
-            'cvr'
-          )
-          const cdbProxy = createPGliteWorker(
-            resolve(config.dataDir, 'pgdata-cdb'),
-            'cdb'
-          )
-          await Promise.all([cvrProxy.waitReady, cdbProxy.waitReady])
-          instances.cvr = cvrProxy as unknown as PGlite
-          instances.cdb = cdbProxy as unknown as PGlite
-        } else {
-          const { PGlite: PGliteCtor } = await import('@electric-sql/pglite')
-          mkdirSync(resolve(config.dataDir, 'pgdata-cvr'), { recursive: true })
-          mkdirSync(resolve(config.dataDir, 'pgdata-cdb'), { recursive: true })
-          instances.cvr = new PGliteCtor({
-            dataDir: resolve(config.dataDir, 'pgdata-cvr'),
-            relaxedDurability: true,
-          })
-          instances.cdb = new PGliteCtor({
-            dataDir: resolve(config.dataDir, 'pgdata-cdb'),
-            relaxedDurability: true,
-          })
-          await instances.cvr.waitReady
-          await instances.cdb.waitReady
-        }
-        log.orez('CVR/CDB recreated')
-
-        // remove stale zero shard schemas from upstream; these can outlive CVR/CDB
-        // and cause dispatcher errors after full reset.
-        const shardSchemas = await db.query(
-          `SELECT DISTINCT schemaname
-           FROM pg_tables
-           WHERE tablename IN ('clients', 'replicas', 'mutations')
-             AND schemaname NOT IN (
-               'pg_catalog',
-               'information_schema',
-               'pg_toast',
-               'public',
-               '_orez'
-             )
-             AND schemaname NOT LIKE 'pg_%'`
-        )
-        for (const { schemaname } of shardSchemas.rows) {
-          const quoted = '"' + schemaname.replace(/"/g, '""') + '"'
-          await db.exec(`DROP SCHEMA IF EXISTS ${quoted} CASCADE`)
-        }
-        if (shardSchemas.rows.length > 0) {
-          log.orez(`dropped ${shardSchemas.rows.length} stale shard schema(s)`)
-        }
-
-        // clear upstream replication tracking so zero-cache starts from a
-        // clean change stream baseline after full reset.
-        await db.exec(`TRUNCATE _orez._zero_changes`).catch(() => {})
-        await db.exec(`TRUNCATE _orez._zero_replication_slots`).catch(() => {})
-        await db
-          .exec(`ALTER SEQUENCE _orez._zero_watermark RESTART WITH 1`)
-          .catch(() => {})
-        log.orez('cleared upstream replication tracking state')
-      }
-
-      // clear cached schema info so the handler re-introspects on reconnect
-      resetReplicationState()
-
-      // always clean up replica file
-      cleanupStaleReplica(config)
-      log.orez('replica cleaned up')
-
-      // re-run on-db-ready hook after full reset (re-runs migrations, syncs publication)
-      if (mode === 'full' && config.onDbReady) {
-        log.orez('re-running on-db-ready...')
-        const upstreamUrl = getConnectionString(config, 'postgres')
-        const cvrUrl = getConnectionString(config, 'zero_cvr')
-        const cdbUrl = getConnectionString(config, 'zero_cdb')
-        await runHook(config.onDbReady, 'on-db-ready', {
-          ZERO_UPSTREAM_DB: upstreamUrl,
-          ZERO_CVR_DB: cvrUrl,
-          ZERO_CHANGE_DB: cdbUrl,
-          DATABASE_URL: upstreamUrl,
-          OREZ_PG_PORT: String(config.pgPort),
-        })
-      }
-
-      // always re-install change tracking after a full reset so public table
-      // triggers reflect any schema changes introduced by restore.
-      await syncManagedPublications(db, managedPub.names, managedPub.managedByOrez)
-      log.debug.orez('re-installing change tracking after full reset')
-      await installChangeTracking(db)
-
-      // restart zero-cache
-      log.orez('starting zero-cache...')
-      // use internal port when http proxy is enabled
-      const zeroConfig = httpLog ? { ...config, zeroPort: zeroInternalPort } : config
-      const result = await startZeroCache(
-        zeroConfig,
-        logStore,
-        sqliteMode,
-        sqliteModeConfig
-      )
-      zeroCacheProcess = result.process
-      zeroEnv = result.env
-
-      await waitForZeroCache(zeroConfig, zeroCacheProcess, 60000, sqliteMode)
-      log.orez(`zero state reset complete (${mode})`)
-      log.zero(`ready ${port(config.zeroPort, 'magenta')}`)
-    } catch (err: any) {
-      log.orez(`reset failed: ${err?.message || err}`)
-      throw err
-    } finally {
-      resetInProgress = false
-      // remove marker file so pg_restore knows we're done
-      try {
-        unlinkSync(resetFile)
-      } catch {}
-    }
-  }
-
-  // handle SIGUSR1 to reset zero state (sent by pg_restore after restore completes)
-  if (!config.skipZeroCache) {
-    process.on('SIGUSR1', () => {
-      log.orez('received SIGUSR1 - full reset')
-      resetZeroState('full').catch((err) => {
-        log.orez(`SIGUSR1 reset failed: ${err?.message || err}`)
-      })
-    })
-
-    // handle SIGUSR2 to quiesce zero-cache (sent by pg_restore before restore starts)
-    process.on('SIGUSR2', () => {
-      log.orez('received SIGUSR2 - stopping zero-cache for restore')
-      killZeroCache().catch((err) => {
-        log.orez(`SIGUSR2 stop failed: ${err?.message || err}`)
-      })
-    })
-  }
-
-  // auto-recover when zero-cache exits unexpectedly. two failure modes:
-  //   - CDC corruption (recognizable signature) — needs a full state reset.
-  //   - any other crash (e.g. a change-streamer statement timeout) — orez
-  //     used to do nothing here, leaving the dead child so the proxy returned
-  //     502 on every /sync until a manual restart. now: restart it, and if
-  //     the crashes keep coming, escalate to one full reset before giving up.
-  let shuttingDown = false
-  const ZERO_CRASH_WINDOW_MS = 5 * 60_000
-  const ZERO_CRASH_RESTART_BUDGET = 5
-  let zeroCrashTimes: number[] = []
-  let zeroFullResetTried = false
-  const installCrashWatcher = () => {
-    if (!zeroCacheProcess || config.skipZeroCache) return
-    zeroCacheProcess.on('exit', (code) => {
-      if (shuttingDown || resetInProgress || code === 0 || code === null) return
-      const tail = (zeroCacheProcess as ZeroChildProcess)?.__orezTail
-      const details = tail?.length ? tail.join('\n') : ''
-      if (hasCdcCorruptionSignature(details)) {
-        log.orez('zero-cache crashed with CDC corruption, auto-recovering...')
-        resetZeroState('full')
-          .then(() => {
-            log.orez('CDC auto-recovery successful')
-            installCrashWatcher()
-          })
-          .catch((err) => {
-            log.orez(`CDC auto-recovery failed: ${err?.message || err}`)
-          })
-        return
-      }
-
-      // non-CDC unexpected crash — restart, bounded by a sliding-window
-      // budget so a genuinely broken instance can't restart-loop forever.
-      zeroCrashTimes = zeroCrashTimes.filter((t) => Date.now() - t < ZERO_CRASH_WINDOW_MS)
-      if (zeroCrashTimes.length === 0) zeroFullResetTried = false
-      zeroCrashTimes.push(Date.now())
-
-      if (zeroCrashTimes.length > ZERO_CRASH_RESTART_BUDGET) {
-        if (zeroFullResetTried) {
-          log.orez('zero-cache kept crashing after a full reset — giving up auto-restart')
-          return
-        }
-        zeroFullResetTried = true
-        log.orez('zero-cache crash-looping — escalating to a full state reset')
-        resetZeroState('full')
-          .then(() => {
-            log.orez('zero-cache full-reset recovery successful')
-            zeroCrashTimes = []
-            installCrashWatcher()
-          })
-          .catch((err) => {
-            log.orez(`zero-cache full-reset recovery failed: ${err?.message || err}`)
-          })
-        return
-      }
-
-      log.orez(
-        `zero-cache exited unexpectedly (code ${code}) — restarting ` +
-          `(${zeroCrashTimes.length}/${ZERO_CRASH_RESTART_BUDGET})`
-      )
-      restartZeroCache()
-        .then(() => {
-          log.orez('zero-cache restart successful')
-          installCrashWatcher()
-        })
-        .catch((err) => {
-          log.orez(`zero-cache restart failed: ${err?.message || err}`)
-        })
-    })
-  }
-  installCrashWatcher()
-
-  const stop = async () => {
-    log.debug.orez('shutting down')
-    shuttingDown = true
-    stopCheckpoint()
-    httpProxyServer?.close()
-    await killZeroCache()
-    pgServer.close()
-    await Promise.all([
-      instances.postgres.close(),
-      instances.cvr.close(),
-      instances.cdb.close(),
-    ])
-    try {
-      unlinkSync(pidFile)
-    } catch {}
-    try {
-      unlinkSync(adminFile)
-    } catch {}
-    try {
-      unlinkSync(readyFile)
-    } catch {}
-    log.debug.orez('stopped')
-  }
-
-  return {
-    config,
-    stop,
-    db,
-    instances,
-    pgPort: config.pgPort,
-    zeroPort: config.zeroPort,
-    logStore,
-    httpLog,
-    zeroEnv,
-    restartZero: config.skipZeroCache ? undefined : restartZeroCache,
-    // stop zero-cache without restart (for pg_restore to safely modify schema)
-    stopZero: config.skipZeroCache ? undefined : killZeroCache,
-    // cache-only reset: just replica file (fast, for minor sync issues)
-    resetZero: config.skipZeroCache ? undefined : () => resetZeroState('cache-only'),
-    // full reset: CVR/CDB + replica (for schema changes, used by pg_restore via SIGUSR1)
-    resetZeroFull: config.skipZeroCache ? undefined : () => resetZeroState('full'),
-  }
-}
-
-/** clean lock files only — keeps replica intact for fast incremental sync on restart.
- *  returns true if any stale lock files were found (indicates unclean shutdown). */
-function cleanupStaleLockFiles(config: ZeroLiteConfig): boolean {
-  const replicaPath = resolve(config.dataDir, 'zero-replica.db')
-  let found = false
-  for (const suffix of ['-wal', '-shm', '-wal2']) {
-    const file = replicaPath + suffix
-    try {
-      if (existsSync(file)) {
-        unlinkSync(file)
-        log.debug.orez(`cleaned up stale ${suffix} file`)
-        found = true
-      }
-    } catch {}
-  }
-  return found
-}
-
-/** delete replica + all lock/wal files — forces zero-cache to do a full resync */
-function cleanupStaleReplica(config: ZeroLiteConfig): void {
-  const replicaPath = resolve(config.dataDir, 'zero-replica.db')
-  for (const suffix of ['', '-wal', '-shm', '-wal2']) {
-    const file = replicaPath + suffix
-    try {
-      if (existsSync(file)) {
-        unlinkSync(file)
-        if (suffix) log.debug.orez(`cleaned up stale ${suffix} file`)
-        else log.debug.orez('cleaned up stale replica (will re-sync)')
-      }
-    } catch {}
-  }
-}
-
-async function seedIfNeeded(db: PGlite, config: ZeroLiteConfig): Promise<void> {
-  // check if we already have data
-  try {
-    const result = await db.query<{ count: string }>(
-      'SELECT count(*) as count FROM public."user"'
-    )
-    if (Number(result.rows[0].count) > 0) {
-      return
-    }
-  } catch {
-    // table might not exist yet
-  }
-
-  log.debug.orez('seeding demo data')
-  const seedFile = resolve(config.seedFile)
-  if (!existsSync(seedFile)) {
-    log.debug.orez('no seed file found, skipping')
-    return
-  }
-
-  const sql = readFileSync(seedFile, 'utf-8')
-  const statements = sql
-    .split('--> statement-breakpoint')
-    .map((s) => s.trim())
-    .filter(Boolean)
-
-  for (const stmt of statements) {
-    await db.exec(stmt)
-  }
-  log.orez('seeded')
-}
-
-async function startZeroCache(
-  config: ZeroLiteConfig,
-  logStore?: LogStore,
-  sqliteMode: SqliteMode = resolveSqliteMode(config.disableWasmSqlite),
-  sqliteModeConfig?: SqliteModeConfig | null
-): Promise<{ process: ChildProcess; env: Record<string, string> }> {
-  // resolve @rocicorp/zero entry for finding zero-cache modules
-  const zeroEntry = resolvePackage('@rocicorp/zero')
-
-  if (!zeroEntry) {
-    throw new Error('zero-cache not found. install @rocicorp/zero')
-  }
-
-  if (sqliteMode === 'native') {
-    log.debug.orez('wasm sqlite disabled, using native @rocicorp/zero-sqlite3')
-  }
-
-  const upstreamUrl = getConnectionString(config, 'postgres')
-  const cvrUrl = getConnectionString(config, 'zero_cvr')
-  const cdbUrl = getConnectionString(config, 'zero_cdb')
-
-  // defaults that can be overridden by user env
-  // when admin is enabled and user hasn't set ZERO_LOG_LEVEL, use 'info'
-  // to avoid flooding stdout with debug logs (each line triggers log processing).
-  // debug was too expensive — tens of thousands of lines per minute.
-  const zeroLogLevel =
-    config.adminPort > 0 && !process.env.ZERO_LOG_LEVEL ? 'info' : config.logLevel
-  const defaults: Record<string, string> = {
-    NODE_ENV: 'development',
-    ZERO_LOG_LEVEL: zeroLogLevel,
-    ZERO_NUM_SYNC_WORKERS: '1',
-    // disable query planner — it relies on scanStatus which causes infinite
-    // loops with wasm sqlite and has caused freezes with native too.
-    // planner is an optimization, not required for correctness.
-    ZERO_ENABLE_QUERY_PLANNER: 'false',
-    // disable otel metrics export — zero-cache has built-in OTEL that tries
-    // to export even without a collector, causing periodic Bad Request errors.
-    // user can override by setting OTEL_SDK_DISABLED=false in their env.
-    OTEL_SDK_DISABLED: 'true',
-  }
-
-  const env: Record<string, string> = {
-    ...defaults,
-    ...(process.env as Record<string, string>),
-    // orez is a development tool — always run zero-cache in development mode
-    // to avoid production requirements like --admin-password
-    NODE_ENV: 'development',
-    ZERO_UPSTREAM_DB: upstreamUrl,
-    ZERO_CVR_DB: cvrUrl,
-    ZERO_CHANGE_DB: cdbUrl,
-    ZERO_REPLICA_FILE: resolve(config.dataDir, 'zero-replica.db'),
-    ZERO_PORT: String(config.zeroPort),
-    ...(config.zeroMutateUrl ? { ZERO_MUTATE_URL: config.zeroMutateUrl } : {}),
-    ...(config.zeroQueryUrl ? { ZERO_QUERY_URL: config.zeroQueryUrl } : {}),
-    // wasm sqlite SHM is file-backed but not as robust as native mmap —
-    // force single sync worker to avoid multi-process SHM contention
-    ...(sqliteMode === 'wasm' ? { ZERO_NUM_SYNC_WORKERS: '1' } : {}),
-  }
-
-  // high worker counts multiply the blast radius of any sync-worker bug
-  // (e.g. orphaned workers busy-looping on EOF'd sibling pipes). dev rarely
-  // benefits from more than a couple; warn so it's obvious where the CPU
-  // went.
-  const workerCount = Number(env.ZERO_NUM_SYNC_WORKERS)
-  if (Number.isFinite(workerCount) && workerCount > 4) {
-    log.orez(
-      `warning: ZERO_NUM_SYNC_WORKERS=${workerCount} is high for development — each worker consumes CPU/memory and amplifies any sync-loop bug. consider 2.`
-    )
-  }
-
-  const zeroCacheBin = resolve(zeroEntry, '..', 'cli.js')
-  if (!existsSync(zeroCacheBin)) {
-    throw new Error('zero-cache cli.js not found. install @rocicorp/zero')
-  }
-
-  // apply sqlite mode shim (wasm: patches lib/index.js, native: restores original)
-  if (sqliteModeConfig) {
-    const shimResult = applySqliteMode(sqliteModeConfig)
-    if (!shimResult.success) {
-      log.orez(`warning: sqlite shim failed: ${shimResult.error}`)
-    }
-  }
-
-  // preload script to label the zero-cache child process AND self-destruct
-  // if the orez parent dies. macOS has no PR_SET_PDEATHSIG, so on a hard
-  // parent kill (SIGKILL) or a crash that skips the `stop()` path, zero-cache
-  // workers get reparented to init and can busy-loop on EOF'd sibling pipes
-  // at 100% CPU indefinitely. every forked zero-cache worker inherits
-  // NODE_OPTIONS, so the --require below runs in each one; they independently
-  // poll the captured orez pid and exit when it disappears.
-  const preloadPath = resolve(config.dataDir, '.orez-zero-title.cjs')
-  const zeroTitle = orezTitle('orez [zero]')
-  writeFileSync(
-    preloadPath,
-    `process.title = ${JSON.stringify(zeroTitle)};\n` +
-      `const __orezPid = ${process.pid};\n` +
-      `setInterval(() => {\n` +
-      `  try { process.kill(__orezPid, 0); } catch { process.exit(0); }\n` +
-      `}, 1000).unref();\n`
-  )
-
-  const nodeOptions = [
-    sqliteMode === 'wasm' ? '--max-old-space-size=16384' : '',
-    `--require ${preloadPath}`,
-    process.env.NODE_OPTIONS || '',
-  ]
-    .filter(Boolean)
-    .join(' ')
-  if (nodeOptions.trim()) env.NODE_OPTIONS = nodeOptions.trim()
-
-  const nodeBinary = resolveNodeBinary()
-  const child = spawn(nodeBinary, [zeroCacheBin], {
-    env,
-    // stdin piped (not 'ignore') so zero-cache's pipe fd to orez closes with
-    // EOF on parent death — belt-and-suspenders alongside the ppid watchdog
-    // in the --require preload above.
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }) as ZeroChildProcess
-  child.__orezTail = []
-
-  const pushTail = (line: string) => {
-    const tail = child.__orezTail!
-    tail.push(line)
-    if (tail.length > 80) tail.splice(0, tail.length - 80)
-  }
-
-  // known transient errors during zero-cache startup — demote to debug
-  const STARTUP_NOISE = [
-    '_zero.tableMetadata',
-    'Unable to create full ReplicationStatusEvent',
-    'replication slot',
-    'does not exist',
-    'error dropping',
-    'EPIPE',
-    'socket has been ended by the other party',
-    'ideal db ping time',
-    'average ping to',
-    // node.js warnings from stale replica timestamps causing negative setTimeout
-    'TimeoutNegativeWarning',
-    'does not allow a negative number',
-    // otel metrics export noise when no collector is configured
-    'PeriodicExportingMetricReader',
-    'OTLPExporterError',
-  ]
-  const isStartupNoise = (line: string): boolean =>
-    STARTUP_NOISE.some((pattern) => line.includes(pattern))
-
-  // detect log level from zero-cache output
-  const detectLevel = (line: string, fallback: string): string => {
-    if (isStartupNoise(line)) return 'debug'
-    const lower = line.toLowerCase()
-    if (
-      lower.includes('"level":"error"') ||
-      lower.includes(' error ') ||
-      lower.includes('error:')
-    )
-      return 'error'
-    if (
-      lower.includes('"level":"warn"') ||
-      lower.includes(' warn ') ||
-      lower.includes('warning:')
-    )
-      return 'warn'
-    if (lower.includes('"level":"debug"') || lower.includes(' debug ')) return 'debug'
-    return fallback
-  }
-
-  child.stdout?.on('data', (data: Buffer) => {
-    const lines = data.toString().trim().split('\n')
-    for (const line of lines) {
-      pushTail(`stdout: ${line}`)
-      const level = detectLevel(line, 'info')
-      if (level === 'warn' || level === 'error') log.zero(line)
-      else log.debug.zero(line)
-      logStore?.push('zero', level, line)
-    }
-  })
-
-  child.stderr?.on('data', (data: Buffer) => {
-    const lines = data.toString().trim().split('\n')
-    for (const line of lines) {
-      pushTail(`stderr: ${line}`)
-      const level = detectLevel(line, 'error')
-      if (level === 'warn' || level === 'error') log.zero(line)
-      else log.debug.zero(line)
-      logStore?.push('zero', level, line)
-    }
-  })
-
-  child.on('exit', (code) => {
-    if (code !== 0 && code !== null) {
-      pushTail(`exit: code ${code}`)
-      log.zero(`exited with code ${code}`)
-      logStore?.push('zero', 'error', `exited with code ${code}`)
-    }
-  })
-
-  return { process: child, env }
-}
-
-async function waitForZeroCache(
-  config: ZeroLiteConfig,
-  zeroProcess?: ChildProcess | null,
-  timeoutMs = 60000,
-  sqliteMode: SqliteMode = resolveSqliteMode(config.disableWasmSqlite)
-): Promise<void> {
-  const start = Date.now()
-  const url = `http://127.0.0.1:${config.zeroPort}/`
-
-  const checkProcessAlive = () => {
-    if (zeroProcess && zeroProcess.exitCode !== null) {
-      const tail = (zeroProcess as ZeroChildProcess).__orezTail
-      const details = tail?.length ? `\n${tail.slice(-20).join('\n')}` : ''
-      throw new Error(
-        `zero-cache exited with code ${zeroProcess.exitCode}${details}${nativeStartupDiagnostics(details, sqliteMode)}`
-      )
-    }
-  }
-
-  // phase 1: wait for HTTP health check
-  while (Date.now() - start < timeoutMs) {
-    checkProcessAlive()
-    try {
-      const controller = new AbortController()
-      const timer = setTimeout(() => controller.abort(), 1000)
-      const res = await fetch(url, { signal: controller.signal })
-      clearTimeout(timer)
-      // zero may return 404 on "/" while still being healthy.
-      if (res.ok || res.status === 404) break
-    } catch {
-      // not ready yet
-    }
-    await new Promise((r) => setTimeout(r, 500))
-  }
-
-  if (Date.now() - start < timeoutMs) {
-    log.debug.orez('zero-cache HTTP health check passed')
-    return
-  }
-
-  const tail = (zeroProcess as ZeroChildProcess | null | undefined)?.__orezTail
-  const details = tail?.length ? `\n${tail.slice(-20).join('\n')}` : ''
-  throw new Error(
-    `zero-cache health check timed out after ${timeoutMs}ms${details}${nativeStartupDiagnostics(details, sqliteMode)}`
-  )
-}
-
-function nativeStartupDiagnostics(details: string, sqliteMode: SqliteMode): string {
-  if (sqliteMode !== 'native') return ''
-  if (!details) return ''
-  if (!hasMissingNativeBinarySignature(details)) return ''
-
-  const check = inspectNativeSqliteBinary()
-  const instructions = formatNativeBootstrapInstructions(check)
-  return `\n\nnative sqlite startup diagnostics:\n${instructions}`
-}