orez 0.2.27 → 0.2.30

package/src/pg-proxy-browser.ts

@@ -1,2022 +0,0 @@
-/**
- * browser proxy that makes pglite speak postgresql wire protocol.
- *
- * browser port of pg-proxy.ts — uses pg-gateway's web DuplexStream
- * instead of TCP sockets. accepts MessagePort connections from zero-cache.
- *
- * regular connections: forwarded to pglite via execProtocolRaw()
- * replication connections: intercepted, replication protocol faked
- *
- * each "database" (postgres, zero_cvr, zero_cdb) maps to its own pglite
- * instance with independent transaction context, preventing cross-database
- * query interleaving that causes CVR concurrent modification errors.
- */
-
-import { PostgresConnection, type DuplexStream } from 'pg-gateway'
-
-import { log } from './log.js'
-import { Mutex } from './mutex.js'
-import {
-  handleReplicationQuery,
-  handleStartReplication,
-  signalReplicationChange,
-} from './replication/handler.js'
-
-import type { PGliteInstances } from './pglite-manager.js'
-import type { PGlite } from '@electric-sql/pglite'
-
-// shared encoder/decoder instances
-const textEncoder = new TextEncoder()
-const textDecoder = new TextDecoder()
-
-// verbose wire-protocol logging. off by default — every postgres message hits
-// the hot path, so unconditional console.debug calls are surprisingly expensive
-// even when devtools is set to hide them (the interpolated strings still get
-// built, and devtools retains them).
-//
-// re-evaluated on every call so you can flip it at runtime from any iframe,
-// worker, or console without restarting. toggle via either:
-//   - env:    OREZ_DEBUG_WIRE=1 (picked up at process start)
-//   - global: globalThis.__OREZ_DEBUG_WIRE__ = true (works anywhere, anytime)
-function isDebugWire(): boolean {
-  try {
-    if ((globalThis as any).__OREZ_DEBUG_WIRE__ === true) return true
-    if (typeof process !== 'undefined' && process.env?.OREZ_DEBUG_WIRE) return true
-  } catch {}
-  return false
-}
-
-// postgres frontend/backend message type bytes — only used for debug-wire logging
-const PG_MSG_TYPE_NAMES: Record<number, string> = {
-  0x50: 'Parse',
-  0x42: 'Bind',
-  0x44: 'Describe',
-  0x45: 'Execute',
-  0x43: 'Close',
-  0x48: 'Flush',
-  0x53: 'Sync',
-  0x51: 'Query',
-  0x58: 'Terminate',
-  0x70: 'Password',
-  0x46: 'FunctionCall',
-  0x64: 'CopyData',
-  0x63: 'CopyDone',
-  0x66: 'CopyFail',
-}
-
-// schema query cache: identical information_schema/catalog queries from multiple
-// zero-cache clients are deduplicated. first query executes, all others get cached result.
-interface CachedQueryResult {
-  result: Uint8Array
-  expiresAt: number
-}
-const schemaQueryCache = new Map<string, CachedQueryResult>()
-const schemaQueryInFlight = new Map<string, Promise<Uint8Array>>()
-const SCHEMA_CACHE_TTL_MS = 30_000
-
-// performance tracking
-const proxyStats = { totalWaitMs: 0, totalExecMs: 0, count: 0, batches: 0 }
-
-// query classification helpers — operate on pre-normalized (trimmed+lowercased) query strings
-const SCHEMA_QUERY_MARKERS = [
-  'information_schema.',
-  'pg_catalog.',
-  'pg_tables',
-  'pg_namespace',
-  'pg_class',
-  'pg_attribute',
-  'pg_type',
-  'pg_publication',
-]
-const WRITE_PREFIXES = ['insert', 'update', 'delete', 'copy', 'truncate']
-const DDL_PREFIXES = ['create', 'alter', 'drop']
-const MUTATING_PREFIXES = [...WRITE_PREFIXES, ...DDL_PREFIXES]
-
-function isCacheableNormalized(q: string): boolean {
-  // fast-fail: mutating queries are never cacheable
-  for (const p of MUTATING_PREFIXES) {
-    if (q.startsWith(p)) return false
-  }
-  // check if it touches schema/catalog tables
-  for (const marker of SCHEMA_QUERY_MARKERS) {
-    if (q.includes(marker)) return true
-  }
-  return false
-}
-
-function isWriteNormalized(q: string): boolean {
-  for (const p of WRITE_PREFIXES) {
-    if (q.startsWith(p)) return true
-  }
-  return false
-}
-
-function isDDLNormalized(q: string): boolean {
-  for (const p of DDL_PREFIXES) {
-    if (q.startsWith(p)) return true
-  }
-  return false
-}
-
-function extractQueryText(data: Uint8Array): string | null {
-  if (data[0] === 0x51) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-    const len = view.getInt32(1)
-    return textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
-  }
-  if (data[0] === 0x50) {
-    return extractParseQuery(data)
-  }
-  return null
-}
-
-function invalidateSchemaCache() {
-  schemaQueryCache.clear()
-}
-
-// abort previous replication handler when a new one starts
-let abortPreviousReplication: (() => void) | null = null
-
-// clean version string: strip emscripten compiler info that breaks pg_restore/pg_dump
-const PG_VERSION_STRING =
-  "'PostgreSQL 17.4 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 12.2.0, 64-bit'"
-
-// query rewrites: make pglite look like real postgres with logical replication
-const QUERY_REWRITES: Array<{ match: RegExp; replace: string }> = [
-  // version() — return a standard-looking version string instead of the emscripten one
-  {
-    match: /\bversion\(\)/gi,
-    replace: PG_VERSION_STRING,
-  },
-  // wal_level check
-  {
-    match: /current_setting\s*\(\s*'wal_level'\s*\)/gi,
-    replace: "'logical'::text",
-  },
-  // strip READ ONLY from BEGIN (pglite is single-session, no read-only transactions)
-  {
-    match: /\bREAD\s+ONLY\b/gi,
-    replace: '',
-  },
-  // strip ISOLATION LEVEL from any query (pglite is single-session, isolation is meaningless)
-  // catches: SET TRANSACTION ISOLATION LEVEL SERIALIZABLE, BEGIN ISOLATION LEVEL SERIALIZABLE, etc.
-  {
-    match:
-      /\bISOLATION\s+LEVEL\s+(SERIALIZABLE|REPEATABLE\s+READ|READ\s+COMMITTED|READ\s+UNCOMMITTED)\b/gi,
-    replace: '',
-  },
-  // strip bare SET TRANSACTION (after ISOLATION LEVEL is removed, this becomes a no-op statement)
-  {
-    match: /\bSET\s+TRANSACTION\s*;/gi,
-    replace: ';',
-  },
-  // redirect pg_replication_slots to our fake table in _orez schema
-  {
-    match: /\bpg_replication_slots\b/g,
-    replace: '_orez._zero_replication_slots',
-  },
-  // rewrite pg_drop_replication_slot() calls to DELETE from the fake table.
-  // PGlite doesn't have real replication slots, so the built-in function errors.
-  // this runs AFTER the table rewrite above, so the table name is already replaced.
-  {
-    match:
-      /SELECT\s+pg_drop_replication_slot\(slot_name\)\s+FROM\s+_orez\._zero_replication_slots/gi,
-    replace: 'DELETE FROM _orez._zero_replication_slots',
-  },
-  // pg_terminate_backend on replication slots — PGlite is single-process, there are
-  // no backends to terminate. rewrite to a plain SELECT so zero-cache sees the slots
-  // but doesn't call the unsupported function.
-  {
-    match:
-      /pg_terminate_backend\(active_pid\)\s+as\s+terminated,\s*active_pid\s+as\s+pid/gi,
-    replace: 'false as terminated, NULL::int as pid',
-  },
-]
-
-// parameter status messages sent during connection handshake
-// pg_restore and other tools read these to determine server capabilities
-const SERVER_PARAMS: [string, string][] = [
-  ['server_encoding', 'UTF8'],
-  ['client_encoding', 'UTF8'],
-  ['DateStyle', 'ISO, MDY'],
-  ['integer_datetimes', 'on'],
-  ['standard_conforming_strings', 'on'],
-  ['TimeZone', 'UTC'],
-  ['IntervalStyle', 'postgres'],
-]
-
-// build a ParameterStatus wire protocol message (type 'S', 0x53)
-function buildParameterStatus(name: string, value: string): Uint8Array {
-  const encoder = textEncoder
-  const nameBytes = encoder.encode(name)
-  const valueBytes = encoder.encode(value)
-  const len = 4 + nameBytes.length + 1 + valueBytes.length + 1
-  const buf = new Uint8Array(1 + len)
-  buf[0] = 0x53 // 'S'
-  new DataView(buf.buffer).setInt32(1, len)
-  let pos = 5
-  buf.set(nameBytes, pos)
-  pos += nameBytes.length
-  buf[pos++] = 0
-  buf.set(valueBytes, pos)
-  pos += valueBytes.length
-  buf[pos] = 0
-  return buf
-}
-
-// queries to intercept and return no-op success (synthetic SET response)
-// pglite rejects SET TRANSACTION if any query (e.g. SET search_path) ran first
-const NOOP_QUERY_PATTERNS: RegExp[] = [/^\s*SET\s+TRANSACTION\b/i, /^\s*SET\s+SESSION\b/i]
-
-// ping queries (SELECT 1, SELECT 2, etc.) — respond synthetically to avoid
-// mutex contention during zero-cache connection warmup
-const PING_QUERY_RE = /^\s*SELECT\s+(\d+)\s*$/i
-
-/**
- * extract query text from a Parse message (0x50).
- */
-function extractParseQuery(data: Uint8Array): string | null {
-  if (data[0] !== 0x50) return null
-  let offset = 5
-  while (offset < data.length && data[offset] !== 0) offset++
-  offset++
-  const queryStart = offset
-  while (offset < data.length && data[offset] !== 0) offset++
-  return textDecoder.decode(data.subarray(queryStart, offset))
-}
-
-// parse postgres ErrorResponse fields. expects `data` to be the full
-// ErrorResponse message (including type byte and length).
-// returns { code, message } extracted from 'C' and 'M' fields.
-function parseErrorFields(
-  data: Uint8Array,
-  start: number,
-  length: number
-): {
-  code: string
-  message: string
-  severity: string
-} {
-  let code = ''
-  let message = ''
-  let severity = ''
-  // body starts after the 1-byte type + 4-byte length
-  let pos = start + 5
-  const end = start + 1 + length
-  while (pos < end) {
-    const fieldType = data[pos]
-    if (fieldType === 0) break
-    pos++
-    const strStart = pos
-    while (pos < end && data[pos] !== 0) pos++
-    const value = textDecoder.decode(data.subarray(strStart, pos))
-    pos++
-    if (fieldType === 0x43)
-      code = value // 'C' SQLSTATE
-    else if (fieldType === 0x4d)
-      message = value // 'M' message
-    else if (fieldType === 0x53) severity = value // 'S' severity
-  }
-  return { code, message, severity }
-}
-
-/**
- * rebuild a Parse message with a modified query string.
- */
-function rebuildParseMessage(data: Uint8Array, newQuery: string): Uint8Array {
-  let offset = 5
-  while (offset < data.length && data[offset] !== 0) offset++
-  const nameEnd = offset + 1
-  const nameBytes = data.subarray(5, nameEnd)
-
-  offset = nameEnd
-  while (offset < data.length && data[offset] !== 0) offset++
-  offset++
-
-  const suffix = data.subarray(offset)
-  const encoder = textEncoder
-  const queryBytes = encoder.encode(newQuery)
-
-  const totalLen = 4 + nameBytes.length + queryBytes.length + 1 + suffix.length
-  const result = new Uint8Array(1 + totalLen)
-  const dv = new DataView(result.buffer)
-  result[0] = 0x50
-  dv.setInt32(1, totalLen)
-  let pos = 5
-  result.set(nameBytes, pos)
-  pos += nameBytes.length
-  result.set(queryBytes, pos)
-  pos += queryBytes.length
-  result[pos++] = 0
-  result.set(suffix, pos)
-  return result
-}
-
-/**
- * rebuild a Simple Query message with a modified query string.
- */
-function rebuildSimpleQuery(newQuery: string): Uint8Array {
-  const encoder = textEncoder
-  const queryBytes = encoder.encode(newQuery + '\0')
-  const buf = new Uint8Array(5 + queryBytes.length)
-  buf[0] = 0x51
-  new DataView(buf.buffer).setInt32(1, 4 + queryBytes.length)
-  buf.set(queryBytes, 5)
-  return buf
-}
-
-// apply all rewrites in one pass, using replace directly (no separate test)
-function applyRewrites(query: string): string {
-  let result = query
-  for (const rw of QUERY_REWRITES) {
-    rw.match.lastIndex = 0
-    result = result.replace(rw.match, rw.replace)
-  }
-  return result
-}
-
-/**
- * intercept and rewrite query messages to make pglite look like real postgres.
- */
-function interceptQuery(data: Uint8Array): Uint8Array {
-  const msgType = data[0]
-
-  if (msgType === 0x51) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-    const len = view.getInt32(1)
-    const original = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
-    const rewritten = applyRewrites(original)
-    if (rewritten !== original) {
-      return rebuildSimpleQuery(rewritten)
-    }
-  } else if (msgType === 0x50) {
-    const original = extractParseQuery(data)
-    if (original) {
-      let rewritten = applyRewrites(original)
-      // for extended protocol, noop queries must be rewritten to a harmless query
-      // (can't return synthetic responses because they're part of a pipeline batch)
-      if (NOOP_QUERY_PATTERNS.some((p) => p.test(rewritten))) {
-        rewritten = 'SELECT 1'
-      }
-      if (rewritten !== original) {
-        return rebuildParseMessage(data, rewritten)
-      }
-    }
-  }
-
-  return data
-}
-
-/**
- * check if a query should be intercepted as a no-op.
- */
-function isNoopQuery(data: Uint8Array): boolean {
-  let query: string | null = null
-  if (data[0] === 0x51) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-    const len = view.getInt32(1)
-    query = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
-  } else if (data[0] === 0x50) {
-    query = extractParseQuery(data)
-  }
-  if (!query) return false
-  return NOOP_QUERY_PATTERNS.some((p) => p.test(query!))
-}
-
-/**
- * build a synthetic "SET" command complete response.
- */
-function buildSetCompleteResponse(): Uint8Array {
-  const encoder = textEncoder
-  const tag = encoder.encode('SET\0')
-  const cc = new Uint8Array(1 + 4 + tag.length)
-  cc[0] = 0x43
-  new DataView(cc.buffer).setInt32(1, 4 + tag.length)
-  cc.set(tag, 5)
-
-  const rfq = new Uint8Array(6)
-  rfq[0] = 0x5a
-  new DataView(rfq.buffer).setInt32(1, 5)
-  rfq[5] = 0x54 // 'T' = in transaction
-
-  const result = new Uint8Array(cc.length + rfq.length)
-  result.set(cc, 0)
-  result.set(rfq, cc.length)
-  return result
-}
-
-/**
- * build a synthetic response for SELECT <n> (ping queries).
- * returns RowDescription + DataRow + CommandComplete + ReadyForQuery
- * without touching PGlite or the mutex.
- */
-function buildSelectIntResponse(val: string): Uint8Array {
-  const enc = textEncoder
-  const parts: Uint8Array[] = []
-
-  // RowDescription: 1 column named "?column?" type int4 (oid 23)
-  const colName = enc.encode('?column?\0')
-  const rdLen = 4 + 2 + colName.length + 4 + 2 + 4 + 2 + 4 + 2
-  const rd = new Uint8Array(1 + rdLen)
-  const rdv = new DataView(rd.buffer)
-  rd[0] = 0x54
-  rdv.setInt32(1, rdLen)
-  rdv.setInt16(5, 1)
-  rd.set(colName, 7)
-  let p = 7 + colName.length
-  rdv.setInt32(p, 0)
-  p += 4 // tableOid
-  rdv.setInt16(p, 0)
-  p += 2 // colAttr
-  rdv.setInt32(p, 23)
-  p += 4 // typeOid (int4)
-  rdv.setInt16(p, 4)
-  p += 2 // typeLen
-  rdv.setInt32(p, -1)
-  p += 4 // typeMod
-  rdv.setInt16(p, 0) // format (text)
-  parts.push(rd)
-
-  // DataRow: 1 column with the value
-  const valBytes = enc.encode(val)
-  const drLen = 4 + 2 + 4 + valBytes.length
-  const dr = new Uint8Array(1 + drLen)
-  const drv = new DataView(dr.buffer)
-  dr[0] = 0x44
-  drv.setInt32(1, drLen)
-  drv.setInt16(5, 1)
-  drv.setInt32(7, valBytes.length)
-  dr.set(valBytes, 11)
-  parts.push(dr)
-
-  // CommandComplete
-  const tag = enc.encode('SELECT 1\0')
-  const cc = new Uint8Array(1 + 4 + tag.length)
-  cc[0] = 0x43
-  new DataView(cc.buffer).setInt32(1, 4 + tag.length)
-  cc.set(tag, 5)
-  parts.push(cc)
-
-  // ReadyForQuery
-  const rfq = new Uint8Array(6)
-  rfq[0] = 0x5a
-  new DataView(rfq.buffer).setInt32(1, 5)
-  rfq[5] = 0x49 // 'I' idle
-  parts.push(rfq)
-
-  const total = parts.reduce((s, p) => s + p.length, 0)
-  const result = new Uint8Array(total)
-  let off = 0
-  for (const part of parts) {
-    result.set(part, off)
-    off += part.length
-  }
-  return result
-}
-
-/** read a big-endian int32 from a Uint8Array at the given offset */
-function concatUint8Arrays(bufs: Uint8Array[]): Uint8Array {
-  const totalLen = bufs.reduce((s, b) => s + b.length, 0)
-  const result = new Uint8Array(totalLen)
-  let offset = 0
-  for (const b of bufs) {
-    result.set(b, offset)
-    offset += b.length
-  }
-  return result
-}
-
-function readInt32BE(data: Uint8Array, offset: number): number {
-  return (
-    ((data[offset] << 24) >>> 0) +
-    (data[offset + 1] << 16) +
-    (data[offset + 2] << 8) +
-    data[offset + 3]
-  )
-}
-
-/**
- * extract ReadyForQuery status byte from a response.
- * returns the status: 'I' (0x49) idle, 'T' (0x54) in transaction, 'E' (0x45) error.
- * returns null if no ReadyForQuery found.
- */
-function getReadyForQueryStatus(data: Uint8Array): number | null {
-  let offset = 0
-  let lastStatus: number | null = null
-  while (offset < data.length) {
-    if (offset + 5 > data.length) break
-    const msgLen = readInt32BE(data, offset + 1)
-    const totalLen = 1 + msgLen
-    if (totalLen <= 0 || offset + totalLen > data.length) break
-    if (data[offset] === 0x5a && totalLen >= 6) {
-      lastStatus = data[offset + 5]
-    }
-    offset += totalLen
-  }
-  return lastStatus
-}
-
-/**
- * per-instance transaction state tracking.
- * pglite is single-connection: if one connection leaves an aborted transaction,
- * it pollutes ALL other connections sharing the same pglite instance.
- * track which connection owns the current transaction so we can auto-ROLLBACK when a
- * DIFFERENT connection encounters the stale aborted state, while still letting the
- * ORIGINAL connection handle its own errors (e.g. ROLLBACK TO SAVEPOINT).
- */
-interface PgLiteTxState {
-  status: number // 0x49='I' idle, 0x54='T' in-transaction, 0x45='E' aborted
-  owner: object | null // opaque connection identity token
-}
-
-// pglite warnings to suppress (benign, but noisy)
-// 25001: "there is already a transaction in progress"
-// 25P01: "there is no transaction in progress"
-// 55000: "wal_level is insufficient to publish logical changes"
-//        pglite internally tries to create a publication for change streaming, but embedded
-//        pglite doesn't support wal_level=logical (server-level postgres config). the
-//        change-streamer still works because it falls back to polling.
-const SUPPRESS_NOTICE_CODES = new Set(['25001', '25P01', '55000'])
-
-/**
- * extract SQLSTATE code from a NoticeResponse message.
- * returns null if not a NoticeResponse or code not found.
- */
-function extractNoticeCode(
-  data: Uint8Array,
-  offset: number,
-  totalLen: number
-): string | null {
-  if (data[offset] !== 0x4e) return null // not a NoticeResponse
-
-  let pos = offset + 5 // skip type byte + length
-  const end = offset + totalLen
-
-  while (pos < end) {
-    const fieldType = data[pos++]
-    if (fieldType === 0) break // terminator
-
-    // find null-terminated string
-    const strStart = pos
-    while (pos < end && data[pos] !== 0) pos++
-    if (pos >= end) break
-
-    if (fieldType === 0x43) {
-      // 'C' = SQLSTATE code
-      return textDecoder.decode(data.subarray(strStart, pos))
-    }
-    pos++ // skip null terminator
-  }
-  return null
-}
-
-/**
- * single-pass response message filter. strips ReadyForQuery messages (when
- * stripRfq=true) and benign transaction state warnings in one scan.
- */
-function stripResponseMessages(data: Uint8Array, stripRfq: boolean): Uint8Array {
-  if (data.length === 0) return data
-
-  const parts: Uint8Array[] = []
-  let offset = 0
-  let stripped = false
-
-  while (offset < data.length) {
-    const msgType = data[offset]
-    if (offset + 5 > data.length) break
-    const msgLen = readInt32BE(data, offset + 1)
-    const totalLen = 1 + msgLen
-
-    if (totalLen <= 0 || offset + totalLen > data.length) break
-
-    // strip ReadyForQuery (0x5a) when requested
-    if (stripRfq && msgType === 0x5a) {
-      stripped = true
-    }
-    // strip benign transaction state notices
-    else {
-      const code = extractNoticeCode(data, offset, totalLen)
-      if (code && SUPPRESS_NOTICE_CODES.has(code)) {
-        stripped = true
-      } else {
-        parts.push(data.subarray(offset, offset + totalLen))
-      }
-    }
-
-    offset += totalLen
-  }
-
-  if (!stripped) return data
-  if (parts.length === 0) return new Uint8Array(0)
-  if (parts.length === 1) return parts[0]
-
-  const total = parts.reduce((sum, p) => sum + p.length, 0)
-  const result = new Uint8Array(total)
-  let pos = 0
-  for (const p of parts) {
-    result.set(p, pos)
-    pos += p.length
-  }
-  return result
-}
-
-/**
- * create a DuplexStream<Uint8Array> from a MessagePort.
- * readable receives Uint8Array messages from the port.
- * writable sends Uint8Array messages via the port.
- */
-let _globalWriteCount = 0
-function messagePortToDuplexWithInject(port: MessagePort): {
-  duplex: DuplexStream<Uint8Array>
-  rawWrite: (data: Uint8Array) => void
-  injectMessage: (data: Uint8Array) => void
-} {
-  let readController: ReadableStreamDefaultController<Uint8Array>
-  let msgCount = 0
-  const readable = new ReadableStream<Uint8Array>({
-    start(controller) {
-      readController = controller
-      port.onmessage = (ev: MessageEvent) => {
-        msgCount++
-        if (ev.data instanceof ArrayBuffer) {
-          controller.enqueue(new Uint8Array(ev.data))
-        } else if (ev.data instanceof Uint8Array) {
-          controller.enqueue(ev.data)
-        }
-      }
-    },
-    cancel() {
-      port.close()
-    },
-  })
-
-  const writable = new WritableStream<Uint8Array>({
-    write(chunk) {
-      const buf = chunk.buffer.slice(
-        chunk.byteOffset,
-        chunk.byteOffset + chunk.byteLength
-      ) as ArrayBuffer
-      port.postMessage(buf)
-    },
-    close() {
-      port.close()
-    },
-  })
-
-  const rawWrite = (data: Uint8Array) => {
-    const buf = data.buffer.slice(
-      data.byteOffset,
-      data.byteOffset + data.byteLength
-    ) as ArrayBuffer
-    port.postMessage(buf)
-  }
-
-  const injectMessage = (data: Uint8Array) => {
-    if (readController) {
-      readController.enqueue(data)
-    }
-  }
-
-  return { duplex: { readable, writable }, rawWrite, injectMessage }
-}
-
-function messagePortToDuplex(port: MessagePort): {
-  duplex: DuplexStream<Uint8Array>
-  rawWrite: (data: Uint8Array) => void
-} {
-  let msgCount = 0
-  const readable = new ReadableStream<Uint8Array>({
-    start(controller) {
-      port.onmessage = (ev: MessageEvent) => {
-        msgCount++
-        if (isDebugWire() && msgCount <= 3) {
-          console.debug(
-            `[pg-proxy-duplex] msg#${msgCount} type=${typeof ev.data} isAB=${ev.data instanceof ArrayBuffer} isU8=${ev.data instanceof Uint8Array} len=${ev.data?.byteLength ?? ev.data?.length ?? '?'}`
-          )
-        }
-        if (ev.data instanceof ArrayBuffer) {
-          controller.enqueue(new Uint8Array(ev.data))
-        } else if (ev.data instanceof Uint8Array) {
-          controller.enqueue(ev.data)
-        } else {
-          console.warn(`[pg-proxy-duplex] unexpected data type:`, typeof ev.data, ev.data)
-        }
-      }
-    },
-    cancel() {
-      port.close()
-    },
-  })
-
-  const writable = new WritableStream<Uint8Array>({
-    write(chunk) {
-      _globalWriteCount++
-      if (isDebugWire() && _globalWriteCount <= 200) {
-        console.debug(`[pg-proxy-ws-write] #${_globalWriteCount} len=${chunk.byteLength}`)
-      }
-      // CF workerd MessagePort does not support transfer lists.
-      const buf = chunk.buffer.slice(
-        chunk.byteOffset,
-        chunk.byteOffset + chunk.byteLength
-      ) as ArrayBuffer
-      port.postMessage(buf)
-    },
-    close() {
-      port.close()
-    },
-  })
-
-  // raw write function for injecting data outside of pg-gateway's stream
-  // (e.g. parameter status messages during onAuthenticated)
-  const rawWrite = (data: Uint8Array) => {
-    const buf = data.buffer.slice(
-      data.byteOffset,
-      data.byteOffset + data.byteLength
-    ) as ArrayBuffer
-    port.postMessage(buf)
-  }
-
-  return { duplex: { readable, writable }, rawWrite }
-}
-
-/**
- * wire-protocol database name. anything not matching `zero_cvr` / `zero_cdb`
- * routes to postgres (see `getDbContext`).
- */
-export type BrowserProxyDbName = 'postgres' | 'zero_cvr' | 'zero_cdb'
-
-export interface BrowserProxy {
-  handleConnection(port: MessagePort): void
-  close(): void
-  createExternalSession(dbName?: BrowserProxyDbName): BrowserProxyExternalSession
-  /**
-   * mutex-coordinated query for out-of-band JSON callers (e.g. soot's
-   * project-server / main-thread SAB JSON channels). takes the same per-db
-   * mutex the wire-protocol path uses and rescues a stale aborted txn before
-   * running. critical in singleDb mode where wire-protocol roles share a
-   * single PGlite session with these external callers — without going through
-   * here, an external query can land on an `E`-state session left by a
-   * different role and fail with "current transaction is aborted".
-   */
-  query(
-    dbName: BrowserProxyDbName,
-    sql: string,
-    params?: unknown[]
-  ): Promise<{ rows: unknown[]; affectedRows?: number }>
-  exec(dbName: BrowserProxyDbName, sql: string): Promise<Array<{ affectedRows: number }>>
-}
-
-export interface BrowserProxyExternalSession {
-  query(
-    sql: string,
-    params?: unknown[]
-  ): Promise<{ rows: unknown[]; affectedRows?: number }>
-  exec(sql: string): Promise<Array<{ affectedRows: number }>>
-  close(): Promise<void>
-}
-
-export async function createBrowserProxy(
-  dbInput: PGlite | PGliteInstances,
-  config: {
-    pgPassword: string
-    pgUser: string
-    pgPort?: number
-    logLevel?: string
-    /**
-     * declares that postgres/cvr/cdb are all backed by the same underlying
-     * PGlite, even if the references are distinct proxy wrappers. forces
-     * mutex coalescing so concurrent protocol messages cannot interleave on
-     * the shared instance (named-statement collisions, replication-slot races).
-     * defaults to autodetect via reference equality — set explicitly when the
-     * caller wraps one PGlite in three thin façades (e.g. orez-web's port
-     * proxies) that fool the reference check.
-     */
-    singleDb?: boolean
-  }
-): Promise<BrowserProxy> {
-  // normalize input: single PGlite instance = use it for all databases (backwards compat for tests)
-  const instances: PGliteInstances =
-    'postgres' in dbInput
-      ? (dbInput as PGliteInstances)
-      : {
-          postgres: dbInput as PGlite,
-          cvr: dbInput as PGlite,
-          cdb: dbInput as PGlite,
-          postgresReplicas: [],
-        }
-
-  // per-instance mutexes for serializing pglite access.
-  // when all instances are the same object (single-db mode), share one mutex
-  // to prevent concurrent protocol messages on the same pglite instance.
-  // explicit singleDb wins over reference equality — callers like orez-web
-  // hand us three distinct wrapper objects that all point at one PGlite.
-  const sharedInstance =
-    config.singleDb === true ||
-    (instances.postgres === instances.cvr && instances.postgres === instances.cdb)
-  const pgMutex = new Mutex()
-  const mutexes = {
-    postgres: pgMutex,
-    cvr: sharedInstance ? pgMutex : new Mutex(),
-    cdb: sharedInstance ? pgMutex : new Mutex(),
-  }
-
-  // per-instance transaction state: tracks which connection owns the current transaction
-  // so we can auto-ROLLBACK stale aborted transactions from other connections.
-  // shared-instance (singleDb) coalesces txState too — pglite is single-session,
-  // so an 'E' state from role A's aborted txn poisons every subsequent query
-  // unless role B can see "yes there's an aborted txn here" and ROLLBACK before
-  // its own work. without coalesce, each role's per-role txState reads idle
-  // even when pglite's actual session is in E, and the rescue at every
-  // mutex.acquire() site never fires for the foreign role.
-  const pgTxState: PgLiteTxState = { status: 0x49, owner: null }
-  const txStates: Record<string, PgLiteTxState> = {
-    postgres: pgTxState,
-    cvr: sharedInstance ? pgTxState : { status: 0x49, owner: null },
-    cdb: sharedInstance ? pgTxState : { status: 0x49, owner: null },
-  }
-
-  // helper to get instance + mutex + tx state for a database name
-  function getDbContext(dbName: string): {
-    db: PGlite
-    mutex: Mutex
-    txState: PgLiteTxState
-  } {
-    if (dbName === 'zero_cvr')
-      return { db: instances.cvr, mutex: mutexes.cvr, txState: txStates.cvr }
-    if (dbName === 'zero_cdb')
-      return { db: instances.cdb, mutex: mutexes.cdb, txState: txStates.cdb }
-    return { db: instances.postgres, mutex: mutexes.postgres, txState: txStates.postgres }
-  }
-
-  const waitOneTurn = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
-
-  async function acquireForOwner(
-    db: PGlite,
-    mutex: Mutex,
-    txState: PgLiteTxState,
-    owner: object | null
-  ) {
-    while (true) {
-      await mutex.acquire()
-      const ownsCurrentTransaction = owner !== null && txState.owner === owner
-      if (txState.status === 0x54 && !ownsCurrentTransaction) {
-        mutex.release()
-        await waitOneTurn()
-        continue
-      }
-      if (txState.status === 0x45 && !ownsCurrentTransaction) {
-        try {
-          await db.exec('ROLLBACK')
-        } catch {}
-        txState.status = 0x49
-        txState.owner = null
-      }
-      return
-    }
-  }
-
-  function tryAcquireForOwner(
-    mutex: Mutex,
-    txState: PgLiteTxState,
-    owner: object | null
-  ) {
-    if (!mutex.tryAcquire()) return false
-    const ownsCurrentTransaction = owner !== null && txState.owner === owner
-    if ((txState.status === 0x54 || txState.status === 0x45) && !ownsCurrentTransaction) {
-      mutex.release()
-      return false
-    }
-    return true
-  }
-
-  function transactionAwareMutex(
-    db: PGlite,
-    mutex: Mutex,
-    txState: PgLiteTxState,
-    owner: object | null
-  ): Mutex {
-    return {
-      get isLocked() {
-        return mutex.isLocked
-      },
-      acquire: () => acquireForOwner(db, mutex, txState, owner),
-      tryAcquire: () => tryAcquireForOwner(mutex, txState, owner),
-      release: () => mutex.release(),
-    } as Mutex
-  }
-
-  // signal replication handler after extended protocol writes complete.
-  // 8ms leading-edge debounce: fires exactly 8ms after the FIRST write,
-  // subsequent writes within that window are batched (handler polls all
-  // changes at once). gives the PushProcessor time to confirm the mutation
-  // before replication streams the same change to zero-cache.
-  // signal replication after writes. uses queueMicrotask instead of setTimeout
-  // because macrotasks (setTimeout) get starved by continuous microtask chains
-  // (async/await) and by Atomics.wait in SAB mode.
-  let signalPending = false
-  function signalWrite() {
-    if (signalPending) return
-    signalPending = true
-    queueMicrotask(() => {
-      signalPending = false
-      signalReplicationChange()
-    })
-  }
-
-  let closed = false
-
-  function handleConnection(port: MessagePort) {
-    if (closed) {
-      port.close()
-      return
-    }
-
-    port.start()
-
-    // peek at the first message to detect replication connections.
-    // replication connections bypass pg-gateway entirely and are handled
-    // with raw MessagePort communication — matching orez-node where
-    // handleReplicationMessage writes directly to the TCP socket.
-    // buffer messages until the connection handler is installed
-    const buffered: MessageEvent[] = []
-    let handlerInstalled = false
-
-    port.onmessage = (ev: MessageEvent) => {
-      if (handlerInstalled) return // shouldn't happen — handler replaced port.onmessage
-      buffered.push(ev)
-      if (buffered.length > 1) return // only process first message
-
-      const data = ev.data instanceof ArrayBuffer ? new Uint8Array(ev.data) : ev.data
-      if (!(data instanceof Uint8Array) || data.length < 8) {
-        handlerInstalled = true
-        handleRegularConnection(port, ev)
-        // flush buffered messages to the new handler
-        for (let i = 1; i < buffered.length; i++) {
-          port.onmessage?.(buffered[i])
-        }
-        return
-      }
-
-      // parse startup message params
-      try {
-        const params = parseStartupParams(data)
-        const dbName = params.database || 'postgres'
-        const isRepl = params.replication === 'database'
-        if (isDebugWire())
-          console.debug(`[pg-proxy] connection: db=${dbName} repl=${isRepl}`)
-        // all connections handled with raw MessagePort (no pg-gateway).
-        // pg-gateway uses for-await on ReadableStream which is broken
-        // in browser Web Workers (same root cause as patches #9, #18, #20).
-        handleRawConnection(port, data, params, getDbContext(dbName), isRepl)
-        handlerInstalled = true
-        // flush any messages that arrived while we were processing the startup
-        for (let i = 1; i < buffered.length; i++) {
-          if (port.onmessage) {
-            port.onmessage(buffered[i])
-          }
-        }
-      } catch (err: any) {
-        console.error(`[pg-proxy] connection error: ${err?.message || err}`)
-      }
-    }
-  }
-
-  /** parse startup message key-value params */
-  function parseStartupParams(data: Uint8Array): Record<string, string> {
-    const params: Record<string, string> = {}
-    // skip: int32 length + int32 protocol version = 8 bytes
-    let pos = 8
-    while (pos < data.length - 1) {
-      const keyStart = pos
-      while (pos < data.length && data[pos] !== 0) pos++
-      if (pos >= data.length) break
-      const key = textDecoder.decode(data.subarray(keyStart, pos))
-      pos++ // skip null
-      const valStart = pos
-      while (pos < data.length && data[pos] !== 0) pos++
-      const val = textDecoder.decode(data.subarray(valStart, pos))
-      pos++ // skip null
-      if (key) params[key] = val
-    }
-    return params
-  }
-
-  /** handle ANY connection with raw MessagePort (no pg-gateway) */
-  function handleRawConnection(
-    port: MessagePort,
-    startupData: Uint8Array,
-    params: Record<string, string>,
-    ctx: { db: PGlite; mutex: Mutex; txState: PgLiteTxState },
-    isReplicationConnection: boolean
-  ) {
-    const { db, mutex, txState } = ctx
-    const connId = {}
-    const dbName = params.database || 'postgres'
-    let connClosed = false
-
-    const write = (data: Uint8Array) => {
-      if (connClosed) return
-      // copy instead of transfer — transfer detaches the buffer which can
-      // cause issues if the caller still references the original data
-      const copy = new Uint8Array(data.length)
-      copy.set(data)
-      port.postMessage(copy.buffer)
-    }
-
-    // step 1: send AuthenticationClearTextPassword (R, type=3) — ask for password
-    const authRequest = new Uint8Array([0x52, 0, 0, 0, 8, 0, 0, 0, 3])
-    write(authRequest)
-
-    // step 2: wait for Password message (p), then send AuthOk + params
-    port.onmessage = (ev: MessageEvent) => {
-      const data2 =
-        ev.data instanceof ArrayBuffer ? new Uint8Array(ev.data) : (ev.data as Uint8Array)
-      if (isDebugWire()) {
-        console.debug(
-          `[pg-proxy-raw-auth] ${dbName} repl=${isReplicationConnection} got msg type=0x${data2?.[0]?.toString(16)} len=${data2?.length}`
-        )
-      }
-      if (!data2 || data2[0] !== 0x70) {
-        console.warn(
-          '[pg-proxy-raw-auth] expected password, got type=0x' + data2?.[0]?.toString(16)
-        )
-      }
-
-      // send ALL auth response messages as ONE combined buffer.
-      // the postgres package reads from the socket and buffers data.
-      // sending as individual postMessage calls creates separate data events,
-      // which is fine for TCP but may cause issues with MessagePort timing.
-      const parts: Uint8Array[] = []
-
-      // AuthenticationOk (R, type=0)
-      parts.push(new Uint8Array([0x52, 0, 0, 0, 8, 0, 0, 0, 0]))
-
-      // ParameterStatus messages
-      for (const [name, value] of SERVER_PARAMS) {
-        parts.push(buildParameterStatus(name, value))
-      }
-
-      // BackendKeyData (K)
-      const bkd = new Uint8Array(13)
-      bkd[0] = 0x4b
-      new DataView(bkd.buffer).setInt32(1, 12)
-      new DataView(bkd.buffer).setInt32(5, 1)
-      new DataView(bkd.buffer).setInt32(9, 0)
-      parts.push(bkd)
-
-      // ReadyForQuery (Z)
-      const rfq = new Uint8Array(6)
-      rfq[0] = 0x5a
-      new DataView(rfq.buffer).setInt32(1, 5)
-      rfq[5] = 0x49
-      parts.push(rfq)
-
-      // combine and send as single message
-      const totalLen = parts.reduce((s, p) => s + p.length, 0)
-      const combined = new Uint8Array(totalLen)
-      let pos = 0
-      for (const p of parts) {
-        combined.set(p, pos)
-        pos += p.length
-      }
-      write(combined)
-
-      if (isDebugWire())
-        console.debug('[pg-proxy-repl-raw] auth complete, ready for queries')
-
-      // step 3: handle subsequent messages (queries, replication commands)
-      installQueryHandler()
-    }
-
-    let pipelineMutexHeld = false
-    let extWritePending = false
-    let pipelineBuffer: Uint8Array[] = []
-    // remember the most recent Parse / SimpleQuery for diagnostic logging when
-    // an ErrorResponse fires. trimmed to 200 chars so we don't blow up logs.
-    let lastQueryForDiag = ''
-
-    function installQueryHandler() {
-      // message buffer: postgres sends multiple protocol messages in one write,
-      // we need to split them and process each individually
-      let pendingBuffer: Uint8Array | null = null
-      // guard against re-entrant onmessage: async handlers can interleave at
-      // await points, causing concurrent modifications to pendingBuffer.
-      let processing = false
-
-      port.onmessage = async (ev: MessageEvent) => {
-        if (connClosed) return
-        const incoming =
-          ev.data instanceof ArrayBuffer
-            ? new Uint8Array(ev.data)
-            : (ev.data as Uint8Array)
-        if (!incoming || !(incoming instanceof Uint8Array)) return
-
-        // append to pending buffer
-        if (pendingBuffer && pendingBuffer.length > 0) {
-          const combined = new Uint8Array(pendingBuffer.length + incoming.length)
-          combined.set(pendingBuffer)
-          combined.set(incoming, pendingBuffer.length)
-          pendingBuffer = combined
-        } else {
-          pendingBuffer = incoming
-        }
-
-        // if another invocation is already processing, just buffer
-        if (processing) return
-        processing = true
-        try {
-          // process all complete messages in the buffer
-          while (pendingBuffer && pendingBuffer.length >= 5) {
-            const msgType: number = pendingBuffer[0]
-            const msgLen: number = new DataView(
-              pendingBuffer.buffer,
-              pendingBuffer.byteOffset,
-              pendingBuffer.byteLength
-            ).getInt32(1)
-            const totalLen: number = 1 + msgLen
-            if (totalLen > pendingBuffer.length) break // incomplete message, wait for more data
-
-            // extract single message
-            const data = pendingBuffer.slice(0, totalLen)
-            pendingBuffer =
-              pendingBuffer.length > totalLen ? pendingBuffer.slice(totalLen) : null
-
-            await processMessage(data)
-          }
-        } finally {
-          processing = false
-        }
-      }
-
-      let _pmCount = 0
-      async function processMessage(data: Uint8Array) {
-        _pmCount++
-        const msgType = data[0]
-        if (isDebugWire()) {
-          const name = PG_MSG_TYPE_NAMES[msgType] || `unknown(0x${msgType.toString(16)})`
-          console.debug(`[pg-proxy-pm] #${_pmCount} ${dbName} ${name} len=${data.length}`)
-        }
-
-        // replication connection: handle replication commands
-        if (isReplicationConnection && msgType === 0x51) {
-          const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-          const len = view.getInt32(1)
-          const query = textDecoder
-            .decode(data.subarray(5, 1 + len - 1))
-            .replace(/\0$/, '')
-          const upper = query.trim().toUpperCase()
-
-          if (upper.startsWith('START_REPLICATION')) {
-            if (abortPreviousReplication) abortPreviousReplication()
-            let aborted = false
-            const writer = {
-              write(chunk: Uint8Array) {
-                if (!connClosed && !aborted) {
-                  try {
-                    write(chunk)
-                  } catch {
-                    aborted = true
-                  }
-                }
-              },
-              get closed() {
-                return connClosed || aborted
-              },
-            }
-            abortPreviousReplication = () => {
-              aborted = true
-              connClosed = true
-              port.close()
-            }
-            port.onmessage = () => {}
-            handleStartReplication(
-              query,
-              writer,
-              db,
-              transactionAwareMutex(db, mutex, txState, null)
-            ).catch(() => {})
-            return
-          }
-
-          // replication queries (IDENTIFY_SYSTEM, CREATE/DROP SLOT)
-          await acquireForOwner(db, mutex, txState, null)
-          try {
-            const response = await handleReplicationQuery(query, db)
-            if (response) {
-              write(response)
-              return
-            }
-            data = interceptQuery(data)
-            let result = await db.execProtocolRaw(data, { syncToFs: false })
-            result = stripResponseMessages(result, false)
-            write(result)
-          } finally {
-            mutex.release()
-          }
-          return
-        }
-
-        // Terminate (0x58) — client wants to close the connection
-        if (msgType === 0x58) {
-          // release mutex if held — connection terminated mid-pipeline
-          if (pipelineMutexHeld) {
-            mutex.release()
-            pipelineMutexHeld = false
-          }
-          connClosed = true
-          port.close()
-          return
-        }
-
-        // regular query handling (SimpleQuery or extended protocol)
-        if (isDebugWire()) {
-          if (msgType === 0x50) {
-            const q = extractParseQuery(data)
-            if (q) console.debug(`[pg-proxy-raw] ${dbName}: Parse ${q.slice(0, 80)}`)
-          } else if (msgType === 0x51) {
-            console.debug(`[pg-proxy-raw] ${dbName}: SimpleQuery len=${data.length}`)
-          }
-        }
-
-        // extended protocol pipeline: Parse(0x50), Bind(0x42), Describe(0x44),
-        // Execute(0x45), Close(0x43), Flush(0x48)
-        const isExtendedMsg =
-          msgType === 0x50 ||
-          msgType === 0x42 ||
-          msgType === 0x44 ||
-          msgType === 0x45 ||
-          msgType === 0x43 ||
-          msgType === 0x48
-        const isSyncInPipeline = msgType === 0x53 && pipelineMutexHeld
-
-        if (isExtendedMsg || isSyncInPipeline) {
-          if (!pipelineMutexHeld) {
-            await acquireForOwner(db, mutex, txState, connId)
-            pipelineMutexHeld = true
-            pipelineBuffer = []
-          }
-
-          // detect writes for replication signaling and remember last query
-          if (msgType === 0x50) {
-            const parsed = extractParseQuery(data)
-            if (parsed) lastQueryForDiag = parsed.slice(0, 200)
-            if (dbName === 'postgres') {
-              const q = parsed?.trimStart().toLowerCase()
-              if (q && /^(insert|update|delete|copy|truncate)/.test(q)) {
-                extWritePending = true
-              }
-            }
-          }
-
-          data = interceptQuery(data)
-
-          // batch: accumulate pipeline messages, send all at once on Sync.
-          // reduces MessagePort round-trips from 5 per query to 1.
-          // (browser MessagePort is ~40ms/hop vs TCP ~0.1ms — batching saves ~5s on init)
-          if (msgType !== 0x53) {
-            pipelineBuffer.push(data)
-            // Flush (0x48): send buffered messages now — describeFirst queries
-            // need the response before the postgres package sends Bind
-            if (msgType === 0x48) {
-              const combined = concatUint8Arrays(pipelineBuffer)
-              pipelineBuffer = []
-              let flushResult: Uint8Array
-              try {
-                flushResult = await db.execProtocolRaw(combined, { syncToFs: false })
-              } catch (err) {
-                console.warn(
-                  `[pg-proxy-raw] execProtocolRaw flush error on ${dbName}: ${(err as any)?.message}`
-                )
-                mutex.release()
-                pipelineMutexHeld = false
-                return
-              }
-              flushResult = stripResponseMessages(flushResult, true)
-              write(flushResult)
-            }
-            return // buffered or flushed, don't fall through to Sync handling
-          }
-
-          // Sync: flush all buffered messages + Sync in one call to PGlite
-          pipelineBuffer.push(data)
-          const combined = concatUint8Arrays(pipelineBuffer)
-          pipelineBuffer = []
-
-          let result: Uint8Array
-          const t0 = performance.now()
-          try {
-            result = await db.execProtocolRaw(combined, { syncToFs: false })
-          } catch (err) {
-            console.warn(
-              `[pg-proxy-raw] execProtocolRaw error on ${dbName}: ${(err as any)?.message}`
-            )
-            mutex.release()
-            pipelineMutexHeld = false
-            return
-          }
-          const dt = performance.now() - t0
-          if (isDebugWire() && dt > 100)
-            console.debug(`[pg-proxy-raw] slow query on ${dbName}: ${dt.toFixed(0)}ms`)
-
-          // update transaction state
-          const rfqStatus = getReadyForQueryStatus(result)
-          if (rfqStatus !== null) {
-            txState.status = rfqStatus
-            txState.owner = rfqStatus === 0x49 ? null : connId
-          }
-
-          // release mutex on Sync
-          if (msgType === 0x53) {
-            mutex.release()
-            pipelineMutexHeld = false
-            if (dbName === 'postgres' && extWritePending) {
-              extWritePending = false
-              signalWrite()
-            }
-            // verify ReadyForQuery and check for errors in the response
-            const rfq = getReadyForQueryStatus(result)
-            if (rfq === null) {
-              console.warn(
-                `[pg-proxy-raw] Sync missing RFQ! db=${dbName} len=${result.length}`
-              )
-            }
-            // check for ErrorResponse (0x45 'E')
-            let pos = 0
-            while (pos < result.length) {
-              if (pos + 5 > result.length) break
-              const t = result[pos]
-              const l = readInt32BE(result, pos + 1)
-              if (t === 0x45) {
-                const errFields = parseErrorFields(result, pos, l)
-                console.warn(
-                  `[pg-proxy-raw] ErrorResponse in Sync! db=${dbName} rfq=${rfq === 0x49 ? 'I' : rfq === 0x45 ? 'E' : rfq} ` +
-                    `code=${errFields.code} severity=${errFields.severity} ` +
-                    `msg=${JSON.stringify(errFields.message)} ` +
-                    `query=${JSON.stringify(lastQueryForDiag)}`
-                )
-              }
-              pos += 1 + l
-            }
-          } else {
-            // strip ReadyForQuery + notices from non-Sync pipeline messages
-            result = stripResponseMessages(result, true)
-          }
-
-          // strip benign notices (25P01 etc.) from ALL results including Sync
-          result = stripResponseMessages(result, false)
-          write(result)
-          return
-        }
-
-        // SimpleQuery (0x51) or standalone Sync
-        if (msgType === 0x51) {
-          const queryText = extractQueryText(data)
-          // ping fast-path
-          if (queryText) {
-            const pingMatch = queryText.match(PING_QUERY_RE)
-            if (pingMatch) {
-              write(buildSelectIntResponse(pingMatch[1]))
-              return
-            }
-          }
-          if (isNoopQuery(data)) {
-            write(buildSetCompleteResponse())
-            return
-          }
-        }
-
-        data = interceptQuery(data)
-        await acquireForOwner(db, mutex, txState, connId)
-        try {
-          let result = await db.execProtocolRaw(data, { syncToFs: false })
-          const rfqStatus = getReadyForQueryStatus(result)
-          if (rfqStatus !== null) {
-            txState.status = rfqStatus
-            txState.owner = rfqStatus === 0x49 ? null : connId
-          }
-          // strip notices (wal_level warnings, transaction state notices)
-          result = stripResponseMessages(result, false)
-          // signal writes
-          if (dbName === 'postgres' && msgType === 0x51) {
-            const qn = extractQueryText(data)?.trimStart().toLowerCase()
-            if (qn && isWriteNormalized(qn)) signalReplicationChange()
-          }
-          write(result)
-        } finally {
-          mutex.release()
-        }
-      } // end processMessage
-    } // end installQueryHandler
-  }
-
-  function handleRegularConnection(port: MessagePort, firstEvent: MessageEvent) {
-    // create duplex AFTER we know it's not a replication connection.
-    // the first message (startup) needs to be re-injected into the readable stream.
-    const { duplex, rawWrite, injectMessage } = messagePortToDuplexWithInject(port)
-    // re-inject the startup message that we consumed for detection
-    if (firstEvent.data instanceof ArrayBuffer) {
-      injectMessage(new Uint8Array(firstEvent.data))
-    } else if (firstEvent.data instanceof Uint8Array) {
-      injectMessage(firstEvent.data)
-    }
-
-    // opaque identity token for this connection (used for tx state ownership)
-    const connId = {}
-
-    let dbName = 'postgres'
-    let isReplicationConnection = false
-    // track extended protocol writes (Parse with INSERT/UPDATE/DELETE/COPY/TRUNCATE)
-    // so we can signal replication on Sync (0x53) after the pipeline completes
-    let extWritePending = false
-    // hold mutex across entire extended protocol pipeline (Parse→Sync).
-    // prevents other connections from interleaving and corrupting PGlite's
-    // unnamed portal/statement state during the pipeline.
-    let pipelineMutexHeld = false
-    // connection closed flag
-    let connClosed = false
-
-    // clean up pglite transaction state when the connection ends.
-    // CRITICAL: only ROLLBACK if THIS connection owns the current pglite
-    // transaction. pglite is single-session and the singleDb path coalesces
-    // txState across roles, so an unconditional ROLLBACK here clobbers any
-    // OTHER connection's active transaction — exactly the cross-role
-    // pollution that 2eb1873 fixed on the node side. browser cleanup was
-    // missed and showed up as "current transaction is aborted, commands
-    // ignored" when a foreign connection closed mid-someone-else's-txn.
-    const cleanup = async () => {
-      if (connClosed) return
-      connClosed = true
-      // replication connections don't own a transaction — skip ROLLBACK
-      if (isReplicationConnection) return
-      try {
-        const { db, mutex, txState } = getDbContext(dbName)
-        await mutex.acquire()
-        try {
-          if (txState.owner === connId && txState.status !== 0x49) {
-            await db.exec('ROLLBACK')
-            txState.status = 0x49
-            txState.owner = null
-          }
-        } catch {
-          // db is closed or rollback failed — ignore
-        } finally {
-          mutex.release()
-        }
-      } catch {
-        // instance may have been replaced during reset, ignore
-      }
-    }
-
-    try {
-      let connection!: PostgresConnection
-      connection = new PostgresConnection(duplex, {
-        serverVersion: '17.4',
-        auth: {
-          method: 'password',
-          getClearTextPassword() {
-            return config.pgPassword
-          },
-          validateCredentials(credentials: {
-            username: string
-            password: string
-            clearTextPassword: string
-          }) {
-            return (
-              credentials.password === credentials.clearTextPassword &&
-              credentials.username === config.pgUser
-            )
-          },
-        },
-
-        // send ParameterStatus messages that standard postgres tools expect
-        // pg-gateway sends server_version via the serverVersion option above,
-        // but tools like pg_restore also need encoding, datestyle, etc.
-        // write directly to the port since pg-gateway owns the writable stream
-        onAuthenticated() {
-          if (isDebugWire()) console.debug(`[pg-proxy-conn] authenticated db=${dbName}`)
-          for (const [name, value] of SERVER_PARAMS) {
-            rawWrite(buildParameterStatus(name, value))
-          }
-        },
-
-        async onStartup(state) {
-          const params = state.clientParams
-          if (params?.replication === 'database') {
-            isReplicationConnection = true
-          }
-          dbName = params?.database || 'postgres'
-          if (isDebugWire()) {
-            console.debug(
-              `[pg-proxy-conn] startup: db=${dbName} user=${params?.user} repl=${params?.replication || 'none'}`
-            )
-          }
-          const { db } = getDbContext(dbName)
-          await db.waitReady
-        },
-
-        async onMessage(data, state) {
-          if (!state.isAuthenticated) {
-            if (isDebugWire()) {
-              console.debug(
-                `[pg-proxy-conn] msg before auth, type=0x${data[0].toString(16)}`
-              )
-            }
-            return
-          }
-          if (isDebugWire()) {
-            console.debug(
-              `[pg-proxy-conn] msg db=${dbName} type=0x${data[0].toString(16)} len=${data.length}`
-            )
-          }
-
-          // handle replication connections (always go to postgres instance)
-          if (isReplicationConnection) {
-            if (data[0] === 0x51) {
-              const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-              const len = view.getInt32(1)
-              const query = textDecoder
-                .decode(data.subarray(5, 1 + len - 1))
-                .replace(/\0$/, '')
-              log.debug.proxy(`repl query: ${query.slice(0, 200)}`)
-            }
-            return handleReplicationMessageBrowser(
-              data,
-              rawWrite,
-              () => connClosed,
-              () => {
-                connClosed = true
-                port.close()
-              },
-              instances.postgres,
-              mutexes.postgres,
-              connection
-            )
-          }
-
-          const msgType = data[0]
-          const { db, mutex, txState } = getDbContext(dbName)
-
-          // extended protocol pipeline: hold mutex across Parse→Sync to prevent
-          // other connections from interleaving and corrupting unnamed portal state.
-          // 0x50=Parse, 0x42=Bind, 0x44=Describe, 0x45=Execute, 0x43=Close, 0x48=Flush
-          const isExtendedMsg =
-            msgType === 0x50 ||
-            msgType === 0x42 ||
-            msgType === 0x44 ||
-            msgType === 0x45 ||
-            msgType === 0x43 ||
-            msgType === 0x48
-          const isSyncInPipeline = msgType === 0x53 && pipelineMutexHeld
-
-          if (isExtendedMsg || isSyncInPipeline) {
-            // acquire mutex on first message of pipeline
-            if (!pipelineMutexHeld) {
-              const t0 = performance.now()
-              await acquireForOwner(db, mutex, txState, connId)
-              proxyStats.totalWaitMs += performance.now() - t0
-              pipelineMutexHeld = true
-            }
-
-            // detect extended protocol writes for replication signaling
-            if (dbName === 'postgres' && msgType === 0x50) {
-              const q = extractParseQuery(data)?.trimStart().toLowerCase()
-              if (q && /^(insert|update|delete|copy|truncate)/.test(q)) {
-                extWritePending = true
-                log.debug.proxy(`ext-write: detected ${q.slice(0, 40)}`)
-              }
-            }
-
-            // apply query rewrites
-            data = interceptQuery(data)
-
-            const t1 = performance.now()
-            let result: Uint8Array
-            try {
-              result = await db.execProtocolRaw(data, { syncToFs: false })
-            } catch (err) {
-              mutex.release()
-              pipelineMutexHeld = false
-              throw err
-            }
-            const t2 = performance.now()
-            proxyStats.totalExecMs += t2 - t1
-            proxyStats.count++
-
-            // update transaction state
-            const rfqStatus = getReadyForQueryStatus(result)
-            if (rfqStatus !== null) {
-              txState.status = rfqStatus
-              txState.owner = rfqStatus === 0x49 ? null : connId
-            }
-
-            // release mutex on Sync (end of pipeline)
-            if (msgType === 0x53) {
-              mutex.release()
-              pipelineMutexHeld = false
-              proxyStats.batches++
-
-              // signal replication handler on postgres writes
-              if (dbName === 'postgres' && extWritePending) {
-                extWritePending = false
-                signalWrite()
-              }
-            } else {
-              // strip ReadyForQuery from non-Sync pipeline messages
-              // result = stripResponseMessages(result, true) // disabled for debugging
-            }
-
-            if (proxyStats.count % 200 === 0) {
-              log.debug.proxy(
-                `perf: ${proxyStats.count} ops (${proxyStats.batches} batches) | mutex ${proxyStats.totalWaitMs.toFixed(0)}ms | pglite ${proxyStats.totalExecMs.toFixed(0)}ms`
-              )
-            }
-
-            return result
-          }
-
-          // Simple Query (0x51) or standalone Sync — per-message mutex
-
-          // fast-path for ping queries (SELECT 1, SELECT 2, etc.)
-          // zero-cache fires these in parallel during warmup — bypass mutex entirely
-          if (msgType === 0x51) {
-            const queryText = extractQueryText(data)
-            if (queryText) {
-              const pingMatch = queryText.match(PING_QUERY_RE)
-              if (pingMatch) {
-                return buildSelectIntResponse(pingMatch[1])
-              }
-            }
-          }
-
-          // check for no-op queries (only SimpleQuery has queries worth intercepting)
-          if (isNoopQuery(data)) {
-            if (msgType === 0x51) {
-              return buildSetCompleteResponse()
-            }
-          }
-
-          // intercept and rewrite queries
-          data = interceptQuery(data)
-
-          // normalize query once for all classification checks
-          const isSimpleQuery = msgType === 0x51
-          const queryText = isSimpleQuery ? extractQueryText(data) : null
-          const queryNorm = queryText ? queryText.trimStart().toLowerCase() : null
-          const cacheable = queryNorm && isCacheableNormalized(queryNorm)
-
-          // cache Simple Query schema queries
-          if (cacheable) {
-            const cached = schemaQueryCache.get(queryText!)
-            if (cached && Date.now() < cached.expiresAt) {
-              return stripResponseMessages(cached.result, false)
-            }
-            const inflight = schemaQueryInFlight.get(queryText!)
-            if (inflight) {
-              return stripResponseMessages(await inflight, false)
-            }
-          }
-
-          const execute = async (): Promise<Uint8Array> => {
-            const t0 = performance.now()
-            await acquireForOwner(db, mutex, txState, connId)
-            const t1 = performance.now()
-            let result: Uint8Array
-            try {
-              result = await db.execProtocolRaw(data, { syncToFs: false })
-            } catch (err) {
-              mutex.release()
-              throw err
-            }
-            const rfqStatus = getReadyForQueryStatus(result)
-            if (rfqStatus !== null) {
-              txState.status = rfqStatus
-              txState.owner = rfqStatus === 0x49 ? null : connId
-            }
-            const t2 = performance.now()
-            mutex.release()
-            proxyStats.totalWaitMs += t1 - t0
-            proxyStats.totalExecMs += t2 - t1
-            proxyStats.count++
-            if (proxyStats.count % 200 === 0) {
-              log.debug.proxy(
-                `perf: ${proxyStats.count} ops (${proxyStats.batches} batches) | mutex ${proxyStats.totalWaitMs.toFixed(0)}ms | pglite ${proxyStats.totalExecMs.toFixed(0)}ms`
-              )
-            }
-            return result
-          }
-
-          let result: Uint8Array
-          if (cacheable) {
-            const promise = execute()
-            schemaQueryInFlight.set(queryText!, promise)
-            try {
-              result = await promise
-              schemaQueryCache.set(queryText!, {
-                result,
-                expiresAt: Date.now() + SCHEMA_CACHE_TTL_MS,
-              })
-            } finally {
-              schemaQueryInFlight.delete(queryText!)
-            }
-          } else {
-            result = await execute()
-            if (queryNorm && isDDLNormalized(queryNorm)) {
-              invalidateSchemaCache()
-            }
-          }
-
-          const stripRfq = msgType !== 0x53 && msgType !== 0x51
-          result = stripResponseMessages(result, stripRfq)
-
-          // signal replication handler on postgres writes for instant sync
-          if (dbName === 'postgres' && queryNorm && isWriteNormalized(queryNorm)) {
-            signalReplicationChange()
-          }
-
-          return result
-        },
-      })
-
-      // when the pg-gateway connection's readable stream ends (port closed),
-      // run cleanup. the PostgresConnection constructor starts init() which
-      // reads from duplex.readable — when the port closes, the readable ends
-      // and init() resolves, but there's no explicit "close" callback.
-      // we rely on the readable stream ending to trigger cleanup.
-      // the readable's cancel() calls port.close(), but if the port is closed
-      // externally, the readable controller will error/close and init resolves.
-      void (async () => {
-        // wait for the connection to finish processing
-        // PostgresConnection.init() returns when the readable stream ends
-        try {
-          // small delay to allow init() to start (constructor kicks it off synchronously)
-          await new Promise((r) => setTimeout(r, 0))
-          // poll until the connection is detached or the port signals close
-          // since MessagePort has no 'close' event, we detect when
-          // the connection's internal processing ends
-        } catch {
-          // ignore
-        }
-        cleanup()
-      })()
-    } catch {
-      cleanup()
-    }
-  }
-
-  // detect writes that need replication signaling. wire path does this on
-  // postgres-bound INSERT/UPDATE/DELETE/COPY/TRUNCATE — same rule applies to
-  // out-of-band callers. without it, a project-server write via SAB JSON
-  // wouldn't wake up the replication stream until the next wire-protocol
-  // write came along.
-  function maybeSignalWriteForExternal(dbName: string, sql: string) {
-    if (dbName !== 'postgres' && dbName !== '') return
-    const head = sql.trimStart().toLowerCase()
-    if (/^(insert|update|delete|copy|truncate)/.test(head)) {
-      signalWrite()
-    }
-  }
-
-  function classifyExternalTransactionControl(
-    sql: string
-  ): 'begin' | 'commit' | 'rollback' | null {
-    const head = sql
-      .trimStart()
-      .replace(/;+\s*$/, '')
-      .toLowerCase()
-    if (/^(begin|start\s+transaction)\b/.test(head)) return 'begin'
-    if (/^(commit|end)\b/.test(head)) return 'commit'
-    if (/^(rollback|abort)\b/.test(head)) return 'rollback'
-    return null
-  }
-
-  function updateExternalTxStateAfterSuccess(
-    txState: PgLiteTxState,
-    owner: object,
-    sql: string
-  ) {
-    const control = classifyExternalTransactionControl(sql)
-    if (control === 'begin') {
-      txState.status = 0x54
-      txState.owner = owner
-    } else if (control === 'commit' || control === 'rollback') {
-      txState.status = 0x49
-      txState.owner = null
-    }
-  }
-
-  function updateExternalTxStateAfterError(
-    txState: PgLiteTxState,
-    owner: object,
-    sql: string
-  ) {
-    const control = classifyExternalTransactionControl(sql)
-    if (control === 'commit' || control === 'rollback') {
-      txState.status = 0x49
-      txState.owner = null
-      return
-    }
-    txState.status = 0x45
-    txState.owner = owner
-  }
-
-  const defaultExternalOwner = {}
-
-  async function externalQuery(
-    dbName: string,
-    sql: string,
-    params?: unknown[],
-    owner: object = defaultExternalOwner
-  ) {
-    if (closed) throw new Error('pg-proxy is closed')
-    const { db, mutex, txState } = getDbContext(dbName)
-    await acquireForOwner(db, mutex, txState, owner)
-    try {
-      const result = await db.query(sql, params as Array<unknown> | undefined)
-      updateExternalTxStateAfterSuccess(txState, owner, sql)
-      maybeSignalWriteForExternal(dbName, sql)
-      return {
-        rows: result.rows as unknown[],
-        affectedRows: result.affectedRows,
-      }
-    } catch (err) {
-      updateExternalTxStateAfterError(txState, owner, sql)
-      throw err
-    } finally {
-      mutex.release()
-    }
-  }
-
-  async function externalExec(
-    dbName: string,
-    sql: string,
-    owner: object = defaultExternalOwner
-  ) {
-    if (closed) throw new Error('pg-proxy is closed')
-    const { db, mutex, txState } = getDbContext(dbName)
-    await acquireForOwner(db, mutex, txState, owner)
-    try {
-      const result = await db.exec(sql)
-      updateExternalTxStateAfterSuccess(txState, owner, sql)
-      maybeSignalWriteForExternal(dbName, sql)
-      return result.map((r: { affectedRows?: number }) => ({
-        affectedRows: r.affectedRows ?? 0,
-      }))
-    } catch (err) {
-      updateExternalTxStateAfterError(txState, owner, sql)
-      throw err
-    } finally {
-      mutex.release()
-    }
-  }
-
-  function createExternalSession(
-    dbName: BrowserProxyDbName = 'postgres'
-  ): BrowserProxyExternalSession {
-    const owner = {}
-    return {
-      query(sql: string, params?: unknown[]) {
-        return externalQuery(dbName, sql, params, owner)
-      },
-      exec(sql: string) {
-        return externalExec(dbName, sql, owner)
-      },
-      async close() {
-        const { db, mutex, txState } = getDbContext(dbName)
-        await mutex.acquire()
-        try {
-          if (txState.owner === owner && txState.status !== 0x49) {
-            try {
-              await db.exec('ROLLBACK')
-            } catch {}
-            txState.status = 0x49
-            txState.owner = null
-          }
-        } finally {
-          mutex.release()
-        }
-      },
-    }
-  }
-
-  return {
-    handleConnection,
-    close() {
-      closed = true
-      signalPending = false
-    },
-    createExternalSession,
-    query: externalQuery,
-    exec: externalExec,
-  }
-}
-
-async function handleReplicationMessageBrowser(
-  data: Uint8Array,
-  rawWrite: (data: Uint8Array) => void,
-  isClosed: () => boolean,
-  closeConn: () => void,
-  db: PGlite,
-  mutex: Mutex,
-  connection: PostgresConnection
-): Promise<Uint8Array | undefined> {
-  if (isDebugWire()) {
-    console.debug(
-      `[pg-proxy-repl] ENTRY type=0x${data[0].toString(16)} len=${data.length}`
-    )
-  }
-
-  // for non-SimpleQuery messages (extended protocol), execute against PGlite directly.
-  if (data[0] !== 0x51) {
-    if (isDebugWire()) {
-      console.debug(
-        `[pg-proxy-repl] ext protocol msg type=0x${data[0].toString(16)} len=${data.length}`
-      )
-    }
-    await mutex.acquire()
-    try {
-      const result = await db.execProtocolRaw(data, { syncToFs: false })
-      if (isDebugWire()) {
-        console.debug(`[pg-proxy-repl] ext protocol result len=${result.length}`)
-      }
-      return result
-    } finally {
-      mutex.release()
-    }
-  }
-
-  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
-  const len = view.getInt32(1)
-  const query = textDecoder.decode(data.subarray(5, 1 + len - 1)).replace(/\0$/, '')
-  const upper = query.trim().toUpperCase()
-
-  // check if this is a START_REPLICATION command
-  if (upper.startsWith('START_REPLICATION')) {
-    await connection.detach()
-
-    // abort any previous replication handler to prevent zombies
-    if (abortPreviousReplication) {
-      log.proxy('aborting previous replication handler')
-      abortPreviousReplication()
-    }
-
-    let aborted = false
-    const writer = {
-      write(chunk: Uint8Array) {
-        if (!isClosed() && !aborted) {
-          try {
-            rawWrite(chunk)
-          } catch {
-            // port may have closed between our check and write
-            aborted = true
-          }
-        }
-      },
-      get closed() {
-        return isClosed() || aborted
-      },
-    }
-
-    const abort = () => {
-      aborted = true
-      closeConn()
-    }
-    abortPreviousReplication = abort
-
-    handleStartReplication(query, writer, db, mutex).catch((err) => {
-      log.proxy(`replication stream ended: ${err}`)
-    })
-    return undefined
-  }
-
-  // handle replication queries + fallthrough to pglite, all under mutex
-  if (isDebugWire()) {
-    console.debug(`[pg-proxy-repl] query: ${query.slice(0, 100)}`)
-    console.debug(`[pg-proxy-repl] acquiring mutex...`)
-  }
-  await mutex.acquire()
-  if (isDebugWire()) console.debug(`[pg-proxy-repl] mutex acquired, testing db access...`)
-  try {
-    const testResult = await db.query('SELECT 1 as test')
-    if (isDebugWire()) {
-      console.debug(`[pg-proxy-repl] db.query works: ${JSON.stringify(testResult.rows)}`)
-    }
-    const response = await handleReplicationQuery(query, db)
-    if (isDebugWire()) {
-      console.debug(
-        `[pg-proxy-repl] handleReplicationQuery result: ${response ? 'bytes(' + response.length + ')' : 'null'}`
-      )
-    }
-    if (response) return response
-
-    // apply query rewrites before forwarding
-    data = interceptQuery(data)
-
-    // fall through to pglite for unrecognized queries
-    const result = await db.execProtocolRaw(data, {
-      throwOnError: false,
-    })
-    return stripResponseMessages(result, false)
-  } finally {
-    mutex.release()
-  }
-}