mixdog 0.7.17 → 0.8.0

package/src/memory/lib/pg/adapter.mjs

@@ -1,308 +0,0 @@
-// pg-adapter.mjs — PG connection manager for mixdog 0.4.0
-// Single owner: supervisor-pg.ensurePgInstance(dataDir) starts PG.
-// pg-adapter calls supervisor-pg — never pg-process directly.
-//
-// Public API:
-//   ensurePgInstance(dataDir, { schema? }) → { db, pool, host, port, runtimeDir, pgdataDir }
-//   closePgInstance(dataDir)               → void
-//
-// The returned `db` exposes the native PG query surface:
-//   db.query(sql, params?)          → { rows, rowCount }
-//   db.exec(sql)                    → multi-statement; resolves on completion
-//   db.transaction(async tx => …)  → auto BEGIN/COMMIT, ROLLBACK on throw
-
-import { resolve } from 'path'
-import { ensurePgInstance as supervisorEnsure } from './supervisor.mjs'
-
-// ---------------------------------------------------------------------------
-// One-shot bootstrap guard — keyed by resolved dataDir (cluster-level, not schema)
-// ---------------------------------------------------------------------------
-
-const _bootstrapped = new Set()
-
-// ---------------------------------------------------------------------------
-// Cross-process advisory-lock keys (two-int4 form: classid + objid).
-//
-// pg advisory locks are CLUSTER-global regardless of which database the session
-// is connected to, so a single shared classid namespaces all mixdog first-boot
-// locks; distinct objids separate the CREATE DATABASE race from the per-cluster
-// extension/schema DDL race. Fixed app-specific keys → concurrent first-boot
-// workers serialize on the exact same lock rather than racing the DDL path.
-// ---------------------------------------------------------------------------
-
-const ADVISORY_LOCK_CLASSID = 0x6d696478 // "midx" — mixdog bootstrap namespace
-const ADVISORY_OBJID_CREATE_DB = 1       // CREATE DATABASE mixdog
-export const ADVISORY_OBJID_SCHEMA_BOOTSTRAP = 2 // extensions + schema DDL
-
-// ---------------------------------------------------------------------------
-// In-process cache
-// ---------------------------------------------------------------------------
-
-const instances = new Map() // `${dataDir}|${schema}` → instance handle
-const opening   = new Map() // same key → Promise (dedupe concurrent calls)
-
-// ---------------------------------------------------------------------------
-// Per-connection init — WeakSet-guarded so settings run exactly once per client
-// ---------------------------------------------------------------------------
-
-const _clientInited = new WeakSet()
-
-async function _initClient(client, schema) {
-  if (_clientInited.has(client)) return
-  // Set search_path so unqualified table names resolve to the correct schema.
-  //
-  // CROSS-SCHEMA QUERY RULE: search_path is per-connection and biases every
-  // unqualified table reference toward the connection's primary schema. Any
-  // query that intentionally touches the OTHER schema (e.g. orphan sweep on
-  // memory.entries from a trace-schema connection, or recall × trace JOIN
-  // analytics) MUST use fully-qualified names (memory.entries / trace.trace_events).
-  // Relying on search_path silently in cross-schema code = bug magnet.
-  const sp = schema === 'trace' ? 'trace, public' : 'memory, public'
-  await client.query(`SET search_path = ${sp}`)
-  // pg_trgm similarity threshold: session-local, must be set per connection.
-  await client.query(`SELECT set_limit(0.10)`)
-  await client.query(`SET default_transaction_isolation TO 'read committed'`)
-  // Mark seen only after all init statements succeed; failure leaves client
-  // unmarked so the next checkout retries init.
-  _clientInited.add(client)
-}
-
-// Wrapper around pool.connect() that runs per-client init before returning.
-// Exported so external callers (e.g. trace-store.insertBridgeCalls) can obtain
-// a connection with search_path already set; raw _pool.connect() leaves it at
-// the PG default and unqualified table lookups resolve in the wrong schema.
-export async function checkedConnect(pgPool, schema) {
-  const client = await pgPool.connect()
-  try {
-    await _initClient(client, schema)
-  } catch (e) {
-    client.release()
-    throw e
-  }
-  return client
-}
-const _checkedConnect = checkedConnect
-
-// ---------------------------------------------------------------------------
-// native PG db shim
-// ---------------------------------------------------------------------------
-
-function makeCompatDb(pgPool, schema) {
-  const db = {
-    // query: use pool directly for single-statement queries
-    query: async (sql, params) => {
-      const client = await _checkedConnect(pgPool, schema)
-      try {
-        return await client.query(sql, params)
-      } finally {
-        client.release()
-      }
-    },
-
-    // exec: multi-statement SQL (semicolon-separated); single client for session state
-    exec: async (sql) => {
-      const client = await _checkedConnect(pgPool, schema)
-      try {
-        await client.query(sql)
-      } finally {
-        client.release()
-      }
-    },
-
-    // transaction: check out one client, BEGIN, run callback(tx), COMMIT or ROLLBACK
-    transaction: async (fn) => {
-      const client = await _checkedConnect(pgPool, schema)
-      try {
-        await client.query('BEGIN')
-        const tx = {
-          query: (sql, params) => client.query(sql, params),
-          exec:  (sql)         => client.query(sql),
-        }
-        const result = await fn(tx)
-        await client.query('COMMIT')
-        return result
-      } catch (err) {
-        try { await client.query('ROLLBACK') } catch {}
-        throw err
-      } finally {
-        client.release()
-      }
-    },
-
-    // close: drain pool
-    close: () => pgPool.end(),
-
-    // Internal access for callers that need raw pool
-    _pool: pgPool,
-  }
-  return db
-}
-
-// ---------------------------------------------------------------------------
-// Instance bootstrap — extensions + schemas (idempotent)
-// ---------------------------------------------------------------------------
-
-// Run `fn` while holding the cluster-global schema-bootstrap advisory lock on a
-// dedicated client. Concurrent first-boot workers across processes serialize on
-// the fixed key so the CREATE TYPE / CREATE EXTENSION / schema DDL path is never
-// raced. The lock is session-scoped (held by this client) and released in
-// finally; `fn`'s own DDL may run on other pool connections — the lock only has
-// to provide cross-process mutual exclusion, not cover the same session.
-export async function withSchemaBootstrapLock(pgPool, fn) {
-  const client = await pgPool.connect()
-  // Tracks whether the advisory lock is provably released. Stays false until a
-  // successful pg_advisory_unlock; any failure/uncertainty keeps it false so we
-  // never return a still-locked session to the pool.
-  let unlockErr = new Error('schema-bootstrap advisory lock release not attempted')
-  try {
-    await client.query(`SELECT pg_advisory_lock($1, $2)`, [
-      ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_SCHEMA_BOOTSTRAP,
-    ])
-    try {
-      return await fn()
-    } finally {
-      try {
-        await client.query(`SELECT pg_advisory_unlock($1, $2)`, [
-          ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_SCHEMA_BOOTSTRAP,
-        ])
-        unlockErr = null // lock provably released → client is clean to reuse
-      } catch (err) {
-        unlockErr = err instanceof Error ? err : new Error(String(err))
-      }
-    }
-  } finally {
-    // A client whose advisory-lock state is uncertain must never be reused:
-    // release(truthy) makes node-pg destroy it instead of pooling it.
-    client.release(unlockErr || undefined)
-  }
-}
-
-async function bootstrapInstance(pgPool, dataDirKey) {
-  if (_bootstrapped.has(dataDirKey)) return
-  // Serialize the cluster-level DDL across concurrent first-boot processes.
-  await withSchemaBootstrapLock(pgPool, async () => {
-    // Use a raw client bypassing per-client schema settings (bootstrap targets
-    // the cluster level, not a specific schema).
-    const client = await pgPool.connect()
-    try {
-      await client.query(`CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA public`)
-      await client.query(`CREATE EXTENSION IF NOT EXISTS pg_trgm WITH SCHEMA public`)
-      await client.query(`CREATE SCHEMA IF NOT EXISTS memory`)
-      await client.query(`CREATE SCHEMA IF NOT EXISTS trace`)
-    } finally {
-      client.release()
-    }
-  })
-  _bootstrapped.add(dataDirKey)
-}
-
-// ---------------------------------------------------------------------------
-// ensurePgInstance — public API
-// ---------------------------------------------------------------------------
-
-/**
- * Ensure a live PG instance and return a native PG db handle.
- *
- * @param {string} dataDir      Plugin data directory.
- * @param {{ schema?: 'memory' | 'trace' }} [opts]
- * @returns {Promise<{ db, pool, host, port, runtimeDir, pgdataDir }>}
- */
-export async function ensurePgInstance(dataDir, opts = {}) {
-  const schema = opts.schema ?? 'memory'
-  const key    = `${resolve(dataDir)}|${schema}`
-
-  if (instances.has(key)) return instances.get(key)
-  if (opening.has(key))   return opening.get(key)
-
-  const promise = (async () => {
-    // 1. Let supervisor-pg own PG startup and health-checking.
-    //    Returns { host, port, runtimeDir, pgdataDir }.
-    const { host, port, runtimeDir, pgdataDir } = await supervisorEnsure(dataDir)
-
-    // 2. Connect via node-postgres; auto-create the mixdog database if absent.
-    const { default: pg } = await import('pg')
-
-    const PG_USER = 'postgres'
-    const PG_DB   = 'mixdog'
-
-    const adminPool = new pg.Pool({
-      host, port, user: PG_USER, database: 'postgres',
-      password: '', max: 1, idleTimeoutMillis: 5_000,
-    })
-    try {
-      // CREATE DATABASE cannot run inside a transaction, so guard the
-      // check-then-create with a session-level advisory lock held on a single
-      // dedicated client. Concurrent first-boot workers block on the same
-      // cluster-global key here and only one issues the CREATE; the rest see
-      // the row present after the holder releases. Released in finally.
-      const adminClient = await adminPool.connect()
-      // Same invariant as withSchemaBootstrapLock: only reuse the client if the
-      // advisory lock is provably released.
-      let unlockErr = new Error('create-db advisory lock release not attempted')
-      try {
-        await adminClient.query(`SELECT pg_advisory_lock($1, $2)`, [
-          ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_CREATE_DB,
-        ])
-        try {
-          const r = await adminClient.query(`SELECT 1 FROM pg_database WHERE datname = $1`, [PG_DB])
-          if (r.rows.length === 0) {
-            await adminClient.query(`CREATE DATABASE ${PG_DB}`)
-            process.stderr.write(`[pg-adapter] created database ${PG_DB}\n`)
-          }
-        } finally {
-          try {
-            await adminClient.query(`SELECT pg_advisory_unlock($1, $2)`, [
-              ADVISORY_LOCK_CLASSID, ADVISORY_OBJID_CREATE_DB,
-            ])
-            unlockErr = null // lock provably released → client is clean to reuse
-          } catch (err) {
-            unlockErr = err instanceof Error ? err : new Error(String(err))
-          }
-        }
-      } finally {
-        // Uncertain advisory-lock state → destroy the client (truthy release arg)
-        // so a still-locked session never re-enters the admin pool.
-        adminClient.release(unlockErr || undefined)
-      }
-    } finally {
-      await adminPool.end()
-    }
-
-    // 3. Production pool.
-    const pgPool = new pg.Pool({
-      host, port, user: PG_USER, database: PG_DB,
-      password: '', max: 5, idleTimeoutMillis: 30_000,
-      connectionTimeoutMillis: 10_000,
-    })
-
-    // 4. Bootstrap extensions + schemas once (idempotent).
-    await bootstrapInstance(pgPool, resolve(dataDir))
-
-    // 5. Build the compat db shim.
-    const db = makeCompatDb(pgPool, schema)
-
-    const result = { db, pool: pgPool, host, port, runtimeDir, pgdataDir }
-    instances.set(key, result)
-    return result
-  })()
-
-  opening.set(key, promise)
-  try {
-    return await promise
-  } finally {
-    opening.delete(key)
-  }
-}
-
-// ---------------------------------------------------------------------------
-// closePgInstance — drain pool
-// ---------------------------------------------------------------------------
-
-export async function closePgInstance(dataDir, opts = {}) {
-  const schema = opts.schema ?? 'memory'
-  const key    = `${resolve(dataDir)}|${schema}`
-  const inst   = instances.get(key)
-  if (!inst) return
-  try { await inst.pool.end() } catch {}
-  instances.delete(key)
-}

package/src/memory/lib/pg/process.mjs

@@ -1,360 +0,0 @@
-// pg-process.mjs — lower-level PG lifecycle helpers for mixdog 0.4.0
-// Track B can wire these into the supervisor; pg-adapter calls them directly.
-//
-// Public API:
-//   startPg({ runtimeDir, pgdataDir, port?, logPath? }) → { pid, port }
-//   stopPg({ runtimeDir, pgdataDir })                   → void
-//   healthcheckPg({ port, host? })                      → boolean
-
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
-import { join } from 'path'
-import { spawnSync } from 'child_process'
-import { createConnection } from 'net'
-import { createServer } from 'net'
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function pgBin(runtimeDir, name) {
-  const ext = process.platform === 'win32' ? '.exe' : ''
-  return join(runtimeDir, 'bin', `${name}${ext}`)
-}
-
-function libEnv(runtimeDir) {
-  // Bundled shared libraries must be visible to the PG binaries at runtime.
-  const libDir = join(runtimeDir, 'lib')
-  if (process.platform === 'linux') {
-    return { ...process.env, LD_LIBRARY_PATH: libDir }
-  }
-  if (process.platform === 'darwin') {
-    return { ...process.env, DYLD_LIBRARY_PATH: libDir }
-  }
-  // win32: DLLs live in bin/ — add to PATH.
-  return { ...process.env, PATH: `${join(runtimeDir, 'bin')};${process.env.PATH}` }
-}
-
-// ---------------------------------------------------------------------------
-// Free port detection
-// ---------------------------------------------------------------------------
-
-function isTcpPortFree(port) {
-  return new Promise(resolve => {
-    const srv = createServer()
-    srv.once('error', () => resolve(false))
-    srv.once('listening', () => { srv.close(); resolve(true) })
-    srv.listen(port, '127.0.0.1')
-  })
-}
-
-const PG_PORT_MIN = 55432
-const PG_PORT_MAX = 55632
-
-async function findFreePort(preferred) {
-  // I2: clamp out-of-range callers to the valid window.
-  if (preferred < PG_PORT_MIN || preferred > PG_PORT_MAX) preferred = PG_PORT_MIN
-  if (await isTcpPortFree(preferred)) return preferred
-  for (let p = preferred + 1; p <= PG_PORT_MAX; p++) {
-    if (await isTcpPortFree(p)) return p
-  }
-  throw new Error(`[pg-process] no free port found in range ${preferred}–${PG_PORT_MAX}`)
-}
-
-// ---------------------------------------------------------------------------
-// postgresql.conf v2 reconcile — appended on every startPg call so existing
-// pgdata directories pick up the bgwriter / checkpoint-distribution tuning
-// without requiring a fresh initdb.
-// ---------------------------------------------------------------------------
-
-const MIXDOG_CONF_V2_MARKER = '# mixdog overrides v2 — bgwriter / checkpoint distribution'
-
-// Lines emitted into postgresql.conf for v2. effective_io_concurrency is
-// posix_fadvise-only; PG rejects non-zero values on Windows with an invalid-
-// parameter error on every reload. Skip it there.
-function buildV2Block() {
-  const lines = [
-    '',
-    MIXDOG_CONF_V2_MARKER,
-    'checkpoint_completion_target = 0.9',  // spread checkpoint write across 90% of timeout window
-    'bgwriter_lru_maxpages = 1000',        // up to 1000 dirty pages per round (default 100)
-    'bgwriter_delay = 50ms',               // wake bgwriter every 50ms (default 200ms)
-  ]
-  if (process.platform !== 'win32') {
-    lines.push('effective_io_concurrency = 32')  // I/O concurrency hint (POSIX only)
-  }
-  return lines.join('\n') + '\n'
-}
-
-// Migration: an earlier v2 always emitted effective_io_concurrency. On Windows
-// that line is invalid — strip it so pg_ctl reload stops logging a parse error
-// every cycle.
-function stripWindowsInvalidLines(conf) {
-  if (process.platform !== 'win32') return conf
-  return conf.replace(/^effective_io_concurrency\s*=\s*\d+\s*\r?\n/m, '')
-}
-
-function ensureConfV2(pgdataDir) {
-  const confPath = join(pgdataDir, 'postgresql.conf')
-  if (!existsSync(confPath)) return false
-  const original = readFileSync(confPath, 'utf8')
-  let conf = stripWindowsInvalidLines(original)
-  const stripped = conf !== original
-  const hasMarker = conf.includes(MIXDOG_CONF_V2_MARKER)
-  if (hasMarker && !stripped) return false
-  if (!hasMarker) conf = conf + buildV2Block()
-  writeFileSync(confPath, conf)
-  return true
-}
-
-// Public reconcile: idempotent conf v2 append + pg_ctl reload on a running
-// instance. Single source of truth for v2 application — supervisor and other
-// callers route through this rather than re-implementing the conf/reload pair.
-// All v2 settings are reload-applicable (no restart required).
-export function reconcileConfV2(runtimeDir, pgdataDir) {
-  const applied = ensureConfV2(pgdataDir)
-  if (!applied) return { applied: false, reloaded: false }
-  const reload = spawnSync(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
-    env: libEnv(runtimeDir), stdio: 'pipe', timeout: 5_000, windowsHide: true,
-  })
-  const reloaded = reload.status === 0
-  if (reloaded) {
-    process.stderr.write('[pg-process] postgresql.conf v2 overrides applied via pg_ctl reload\n')
-  } else {
-    process.stderr.write(`[pg-process] pg_ctl reload after v2 append failed (non-fatal): ${reload.stderr?.toString() || ''}\n`)
-  }
-  return { applied, reloaded }
-}
-
-// ---------------------------------------------------------------------------
-// startPg
-// ---------------------------------------------------------------------------
-
-export async function startPg({ runtimeDir, pgdataDir, port: preferredPort = 55432, logPath }) {
-  mkdirSync(pgdataDir, { recursive: true })
-
-  if (process.platform === 'darwin') {
-    try { writeFileSync(join(pgdataDir, '.metadata_never_index'), '') } catch {}
-  }
-
-  // Idempotent v2 conf reconcile — runs before attach/init. Returns true if
-  // the block was just appended (so the attach path can trigger pg_ctl reload).
-  // Fresh-init path falls through to confAppend below which already includes v2.
-  const v2Applied = ensureConfV2(pgdataDir)
-
-  // Pre-check: if postmaster.pid exists and the instance is reachable, attach
-  // rather than attempting a second pg_ctl start (which would crash the worker).
-  const postmasterPidPath = join(pgdataDir, 'postmaster.pid')
-  if (existsSync(postmasterPidPath)) {
-    try {
-      const lines = readFileSync(postmasterPidPath, 'utf8').split('\n')
-      const existingPid  = parseInt(lines[0], 10)
-      // Line 4 (index 3) in postmaster.pid holds the port number.
-      const existingPort = parseInt(lines[3], 10)
-      if (existingPid > 0 && existingPort > 0) {
-        // Liveness must be confirmed by pg_isready (status 0). A bare open TCP
-        // port is insufficient: any unrelated listener that happened to grab
-        // this port would be mistaken for our PG instance, causing a false
-        // attach. pg_isready performs a real PG protocol handshake, so a
-        // non-Postgres listener returns non-zero and we correctly fall through
-        // to normal startup (which reclaims the stale postmaster.pid).
-        const pgIsReady = pgBin(runtimeDir, 'pg_isready')
-        const probe = spawnSync(pgIsReady, ['-h', '127.0.0.1', '-p', String(existingPort)], {
-          env: libEnv(runtimeDir), stdio: 'pipe', timeout: 3_000, windowsHide: true,
-        })
-        const alive = probe.status === 0
-        if (alive) {
-          process.stderr.write(`[pg-process] attaching to existing PG pid=${existingPid} port=${existingPort}\n`)
-          // Route through the single reconcile entry point so v1 → v2 conf
-          // upgrades land on already-running instances without restart.
-          if (v2Applied) reconcileConfV2(runtimeDir, pgdataDir)
-          return { pid: existingPid, port: existingPort, attached: true }
-        }
-        // Dead instance — fall through to normal startup; pg_ctl will reclaim stale lock.
-      }
-    } catch {}
-  }
-
-  const env    = libEnv(runtimeDir)
-  const initdb = pgBin(runtimeDir, 'initdb')
-  const pgctl  = pgBin(runtimeDir, 'pg_ctl')
-
-  // initdb if pgdata is not yet initialised (no PG_VERSION file).
-  const pgVersionFile = join(pgdataDir, 'PG_VERSION')
-  if (!existsSync(pgVersionFile)) {
-    process.stderr.write(`[pg-process] initdb → ${pgdataDir}\n`)
-    const r = spawnSync(initdb, [
-      '-D', pgdataDir,
-      '--auth-local=trust',
-      '--no-locale',
-      '-E', 'UTF8',
-      '-U', 'postgres',
-    ], { env, stdio: 'pipe', windowsHide: true })
-
-    if (r.status !== 0) {
-      const detail = r.error?.message
-        || r.stderr?.toString()
-        || r.stdout?.toString()
-        || `status=${r.status} signal=${r.signal} (no captured output)`
-      throw new Error(`[pg-process] initdb failed: ${detail}`)
-    }
-
-    // Append mixdog-specific postgresql.conf overrides.
-    // default_transaction_isolation: native PG default is read committed.
-    // Native PG does not default to serializable; set isolation level explicitly
-    // so behaviour is unambiguous across PG major versions.
-    const confPath   = join(pgdataDir, 'postgresql.conf')
-    const confAppend = [
-      '',
-      '# mixdog overrides — appended by pg-process.mjs',
-      "default_transaction_isolation = 'read committed'",
-      "listen_addresses = '127.0.0.1'",
-      'log_min_messages = warning',
-      'log_line_prefix = \'%t [%p]: \'',
-      '',
-      '# Defender/AV latency mitigations',
-      'synchronous_commit = off',          // defers fsync ack; trade-off: crash → latest async commits since last WAL flush may be lost; acceptable for local memory store
-      'checkpoint_timeout = 15min',        // halves checkpoint frequency vs 5min default; fewer sync storms
-      'max_wal_size = 2GB',                // suppresses forced checkpoints driven by WAL volume
-      'wal_compression = on',              // smaller WAL segments; fewer bytes for Defender to scan per segment
-      'wal_init_zero = off',               // skips zero-fill on new WAL segment; cuts Defender contact at segment creation
-      'wal_recycle = off',                 // disables WAL rename/recycle loop; eliminates rename-storm EPERM pattern in pgdata
-    ].join('\n') + '\n' + buildV2Block()
-
-    try {
-      const existing = readFileSync(confPath, 'utf8')
-      writeFileSync(confPath, existing + confAppend)
-    } catch (e) {
-      process.stderr.write(`[pg-process] postgresql.conf append failed: ${e?.message}\n`)
-    }
-
-    if (process.platform === 'win32') {
-      process.stderr.write(
-        `[pg-process] Windows tip: if startup feels slow, add the data folder to Defender exclusions.\n` +
-        `  Folder: ${pgdataDir}\n` +
-        `  PowerShell (run as admin): Add-MpPreference -ExclusionPath '${pgdataDir}'\n`
-      )
-    }
-  }
-
-  // Choose a free port (guards against stale postmaster from prior crash).
-  const port    = await findFreePort(preferredPort)
-  const logFile = logPath ?? join(pgdataDir, 'pg.log')
-
-  process.stderr.write(`[pg-process] pg_ctl start -D ${pgdataDir} -p ${port}\n`)
-
-  const r = spawnSync(pgctl, [
-    'start', '-w',
-    '-D', pgdataDir,
-    '-l', logFile,
-    '-o', `-p ${port} -h 127.0.0.1`,
-  ], { env, stdio: 'pipe', timeout: 30_000, windowsHide: true })
-
-  if (r.status !== 0) {
-    const errText = r.stderr?.toString() || r.stdout?.toString() || ''
-    // "another server might be running" — try status + immediate stop before failing.
-    if (errText.includes('another server might be running')) {
-      process.stderr.write(`[pg-process] pg_ctl start: "another server might be running" — probing status\n`)
-      const statusR = spawnSync(pgctl, ['status', '-D', pgdataDir], { env, stdio: 'pipe', timeout: 3_000, windowsHide: true })
-      process.stderr.write(`[pg-process] pg_ctl status: ${statusR.stdout?.toString() || statusR.stderr?.toString() || 'no output'}\n`)
-      const stopR = spawnSync(pgctl, ['stop', '-m', 'immediate', '-D', pgdataDir], { env, stdio: 'pipe', timeout: 3_000, windowsHide: true })
-      if (stopR.status === 0) {
-        // Retry start once after clearing the stale instance.
-        const r2 = spawnSync(pgctl, [
-          'start', '-w',
-          '-D', pgdataDir,
-          '-l', logPath ?? join(pgdataDir, 'pg.log'),
-          '-o', `-p ${port} -h 127.0.0.1`,
-        ], { env, stdio: 'pipe', timeout: 30_000, windowsHide: true })
-        if (r2.status === 0) {
-          let pid = null
-          try {
-            const pidFile = join(pgdataDir, 'postmaster.pid')
-            if (existsSync(pidFile)) pid = parseInt(readFileSync(pidFile, 'utf8').split('\n')[0], 10) || null
-          } catch {}
-          return { pid, port }
-        }
-        process.stderr.write(`[pg-process] retry start after stop also failed: ${r2.stderr?.toString() || ''}\n`)
-      } else {
-        process.stderr.write(`[pg-process] immediate stop failed: ${stopR.stderr?.toString() || ''} — treating as degraded\n`)
-      }
-    }
-    throw new Error(`[pg-process] pg_ctl start failed: ${errText}`)
-  }
-
-  // Read PID from postmaster.pid (first line).
-  let pid = null
-  try {
-    const pidFile = join(pgdataDir, 'postmaster.pid')
-    if (existsSync(pidFile)) {
-      pid = parseInt(readFileSync(pidFile, 'utf8').split('\n')[0], 10) || null
-    }
-  } catch {}
-
-  return { pid, port }
-}
-
-// ---------------------------------------------------------------------------
-// stopPg
-// ---------------------------------------------------------------------------
-
-export async function stopPg({ runtimeDir, pgdataDir }) {
-  const pgctl = pgBin(runtimeDir, 'pg_ctl')
-  const env   = libEnv(runtimeDir)
-
-  const r = spawnSync(pgctl, ['stop', '-m', 'fast', '-w', '-D', pgdataDir], {
-    env,
-    stdio: 'pipe',
-    timeout: 15_000,
-    windowsHide: true,
-  })
-
-  if (r.status !== 0) {
-    const msg = r.stderr?.toString() || r.stdout?.toString() || ''
-    // Stale postmaster.pid — PG is already down; clean up and continue.
-    if (
-      msg.includes('no server running') ||
-      msg.includes('PID file') ||
-      msg.includes('not running')
-    ) {
-      process.stderr.write(`[pg-process] stopPg: already stopped (${msg.slice(0, 80)})\n`)
-      try { rmSync(join(pgdataDir, 'postmaster.pid'), { force: true }) } catch {}
-    } else {
-      process.stderr.write(`[pg-process] pg_ctl stop warning: ${msg}\n`)
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// healthcheckPg
-// ---------------------------------------------------------------------------
-
-export async function healthcheckPg({ port, host = '127.0.0.1' }) {
-  // Phase 1: TCP listen check (fast, no PG client dependency).
-  const tcpOk = await new Promise(resolve => {
-    const sock = createConnection({ host, port })
-    sock.setTimeout(1000)
-    sock.once('connect', () => { sock.destroy(); resolve(true) })
-    sock.once('error',   () => { sock.destroy(); resolve(false) })
-    sock.once('timeout', () => { sock.destroy(); resolve(false) })
-  })
-  if (!tcpOk) return false
-
-  // Phase 2: SELECT 1 via a transient pg client.
-  let client
-  try {
-    const { default: pg } = await import('pg')
-    client = new pg.Client({
-      host, port, user: 'postgres', database: 'postgres', password: '',
-      connectionTimeoutMillis: 2000,
-    })
-    await client.connect()
-    await client.query('SELECT 1')
-    return true
-  } catch {
-    return false
-  } finally {
-    if (client) {
-      try { await client.end() } catch {}
-    }
-  }
-}