orez 0.0.46 → 0.0.48

package/src/replication/change-tracker.ts

@@ -67,35 +67,6 @@ export async function installChangeTracking(db: PGlite): Promise<void> {
     $$ LANGUAGE plpgsql;
   `)
 
-  // auto-install change tracking on tables created after startup (e.g. via restore
-  // or wire protocol). uses a DDL event trigger that fires on CREATE TABLE.
-  await db.exec(`
-    CREATE OR REPLACE FUNCTION public._zero_auto_track() RETURNS event_trigger AS $$
-    DECLARE
-      obj record;
-    BEGIN
-      FOR obj IN SELECT * FROM pg_event_trigger_ddl_commands()
-                 WHERE command_tag = 'CREATE TABLE'
-      LOOP
-        IF obj.schema_name = 'public'
-           AND obj.object_identity NOT LIKE '%._zero_%'
-           AND obj.object_identity NOT LIKE '%.migrations'
-        THEN
-          EXECUTE format(
-            'CREATE TRIGGER _zero_change_trigger AFTER INSERT OR UPDATE OR DELETE ON %s FOR EACH ROW EXECUTE FUNCTION public._zero_track_change()',
-            obj.object_identity
-          );
-        END IF;
-      END LOOP;
-    END;
-    $$ LANGUAGE plpgsql;
-
-    DROP EVENT TRIGGER IF EXISTS _zero_auto_track_trigger;
-    CREATE EVENT TRIGGER _zero_auto_track_trigger ON ddl_command_end
-      WHEN TAG IN ('CREATE TABLE')
-      EXECUTE FUNCTION public._zero_auto_track();
-  `)
-
   // install triggers on all public tables
   await installTriggersOnAllTables(db)
 }
@@ -239,10 +210,29 @@ export async function installTriggersOnShardTables(db: PGlite): Promise<void> {
 
   if (result.rows.length === 0) return
 
+  // only track `clients` — that's the table zero-cache expects in the
+  // replication stream (needed for .server promise resolution).  other shard
+  // tables like `replicas` are zero-cache internal state and streaming them
+  // back causes "Unknown table" crashes in zero-cache's change-processor.
   let count = 0
   for (const { nspname } of result.rows) {
+    // remove stale triggers from non-clients tables (from previous versions)
+    const stale = await db.query<{ event_object_table: string }>(
+      `SELECT DISTINCT event_object_table FROM information_schema.triggers
+       WHERE trigger_name = '_zero_change_trigger'
+         AND event_object_schema = $1
+         AND event_object_table != 'clients'`,
+      [nspname]
+    )
+    for (const { event_object_table } of stale.rows) {
+      const qs = quoteIdent(nspname)
+      const qt = quoteIdent(event_object_table)
+      await db.exec(`DROP TRIGGER IF EXISTS _zero_change_trigger ON ${qs}.${qt}`)
+      log.debug.pglite(`removed stale shard trigger from ${nspname}.${event_object_table}`)
+    }
+
     const tables = await db.query<{ tablename: string }>(
-      `SELECT tablename FROM pg_tables WHERE schemaname = $1`,
+      `SELECT tablename FROM pg_tables WHERE schemaname = $1 AND tablename = 'clients'`,
       [nspname]
     )
 

package/src/replication/handler.ts

@@ -12,7 +12,6 @@ import {
   getCurrentWatermark,
   purgeConsumedChanges,
   installTriggersOnShardTables,
-  ensureChangeTrackingOnAllTables,
   type ChangeRecord,
 } from './change-tracker.js'
 import {
@@ -33,6 +32,9 @@ import {
 import type { Mutex } from '../mutex.js'
 import type { PGlite } from '@electric-sql/pglite'
 
+// track concurrent replication handlers to detect reconnect-purge race
+let activeHandlerCount = 0
+
 export interface ReplicationWriter {
   write(data: Uint8Array): void
 }
@@ -263,6 +265,11 @@ export async function handleStartReplication(
   db: PGlite,
   mutex: Mutex
 ): Promise<void> {
+  activeHandlerCount++
+  const handlerId = activeHandlerCount
+  console.info(
+    `[orez-repl#${handlerId}] START_REPLICATION (active handlers: ${activeHandlerCount})`
+  )
   log.debug.proxy('replication: entering streaming mode')
 
   // send CopyBothResponse to enter streaming mode
@@ -286,9 +293,6 @@ export async function handleStartReplication(
   // "already in transaction" errors when they interleave.
   await mutex.acquire()
   try {
-    // install change tracking triggers on any tables created after startup
-    await ensureChangeTrackingOnAllTables(db)
-
     // install change tracking triggers on shard schema tables (e.g. chat_0.clients)
     // these track zero-cache's lastMutationID for .server promise resolution
     await installTriggersOnShardTables(db)
@@ -347,7 +351,7 @@ export async function handleStartReplication(
     for (const schema of relevantSchemas) {
       if (schema === 'public') continue
       const shardTables = await db.query<{ tablename: string }>(
-        `SELECT tablename FROM pg_tables WHERE schemaname = $1`,
+        `SELECT tablename FROM pg_tables WHERE schemaname = $1 AND tablename = 'clients'`,
         [schema]
       )
       for (const { tablename } of shardTables.rows) {
@@ -457,6 +461,10 @@ export async function handleStartReplication(
     mutex.release()
   }
 
+  console.info(
+    `[orez-repl#${handlerId}] setup complete, starting poll (lastWatermark=${lastWatermark})`
+  )
+
   // track which tables we've sent RELATION messages for
   const sentRelations = new Set<string>()
   let txCounter = 1
@@ -469,6 +477,7 @@ export async function handleStartReplication(
   const purgeEveryN = 10
   let running = true
   let pollsSincePurge = 0
+  let lastIdleLog = 0
 
   const poll = async () => {
     while (running) {
@@ -483,6 +492,29 @@ export async function handleStartReplication(
         }
 
         if (changes.length > 0) {
+          // filter out shard tables that zero-cache doesn't expect.
+          // only `clients` is needed (for .server promise resolution).
+          // other shard tables (replicas, mutations) crash zero-cache
+          // with "Unknown table" in change-processor.
+          const batchEnd = changes[changes.length - 1].watermark
+          changes = changes.filter((c) => {
+            const dot = c.table_name.indexOf('.')
+            if (dot === -1) return true
+            const schema = c.table_name.substring(0, dot)
+            if (schema === 'public') return true
+            const table = c.table_name.substring(dot + 1)
+            return table === 'clients'
+          })
+
+          if (changes.length === 0) {
+            lastWatermark = batchEnd
+            continue
+          }
+
+          const tables = [...new Set(changes.map((c) => c.table_name))].join(',')
+          console.info(
+            `[orez-repl#${handlerId}] found ${changes.length} changes [${tables}] (wm ${lastWatermark}→${changes[changes.length - 1].watermark}, type=${typeof changes[0].watermark})`
+          )
           await streamChanges(
             changes,
             writer,
@@ -492,7 +524,7 @@ export async function handleStartReplication(
             excludedColumns,
             columnTypeOids
           )
-          lastWatermark = changes[changes.length - 1].watermark
+          lastWatermark = batchEnd
 
           // purge consumed changes periodically to free wasm memory
           pollsSincePurge++
@@ -502,12 +534,23 @@ export async function handleStartReplication(
             try {
               const purged = await purgeConsumedChanges(db, lastWatermark)
               if (purged > 0) {
-                log.debug.proxy(`purged ${purged} consumed changes`)
+                console.info(
+                  `[orez-repl#${handlerId}] purged ${purged} changes (wm<=${lastWatermark})`
+                )
               }
             } finally {
               mutex.release()
             }
           }
+        } else {
+          // throttled idle logging (every 10s)
+          const now = Date.now()
+          if (now - lastIdleLog > 10000) {
+            lastIdleLog = now
+            console.info(
+              `[orez-repl#${handlerId}] idle (lastWatermark=${lastWatermark}, type=${typeof lastWatermark})`
+            )
+          }
         }
 
         // send keepalive
@@ -531,7 +574,10 @@ export async function handleStartReplication(
 
   log.debug.proxy('replication: starting poll loop')
   await poll()
-  log.debug.proxy('replication: poll loop exited')
+  activeHandlerCount--
+  console.info(
+    `[orez-repl#${handlerId}] poll loop exited (remaining handlers: ${activeHandlerCount})`
+  )
 }
 
 async function streamChanges(

package/src/replication/pgoutput-encoder.test.ts

@@ -364,6 +364,223 @@ describe('pgoutput-encoder', () => {
     })
   })
 
+  // roundtrip tests: encode with orez → parse with zero-cache's parser
+  // this validates the fundamental contract between orez and zero-cache
+  describe('roundtrip: orez encoder → zero-cache parser', () => {
+    // absolute path bypasses package.json exports restriction
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { PgoutputParser } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/services/change-source/pg/logical-replication/pgoutput-parser.js')
+
+    // mock type parsers: unknown OIDs default to String (identity for text)
+    const typeParsers = { getTypeParser: () => String }
+
+    function makeParser() {
+      return new PgoutputParser(typeParsers)
+    }
+
+    it('BEGIN roundtrip', () => {
+      const lsn = 0x1000200n
+      const ts = BigInt(Date.now()) * 1000n
+      const parser = makeParser()
+      const parsed = parser.parse(encodeBegin(lsn, ts, 42))
+
+      expect(parsed.tag).toBe('begin')
+      expect(parsed.commitLsn).toBe('00000000/01000200')
+      expect(parsed.xid).toBe(42)
+      expect(parsed.commitTime).toBe(ts)
+    })
+
+    it('COMMIT roundtrip', () => {
+      const lsn = 0x1000200n
+      const endLsn = 0x1000300n
+      const ts = BigInt(Date.now()) * 1000n
+      const parser = makeParser()
+      const parsed = parser.parse(encodeCommit(0, lsn, endLsn, ts))
+
+      expect(parsed.tag).toBe('commit')
+      expect(parsed.commitLsn).toBe('00000000/01000200')
+      expect(parsed.commitEndLsn).toBe('00000000/01000300')
+      expect(parsed.commitTime).toBe(ts)
+    })
+
+    it('RELATION roundtrip', () => {
+      const oid = getTableOid('rt.rel_test')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'name', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      const parsed = parser.parse(encodeRelation(oid, 'public', 'rel_test', 0x64, cols))
+
+      expect(parsed.tag).toBe('relation')
+      expect(parsed.schema).toBe('public')
+      expect(parsed.name).toBe('rel_test')
+      expect(parsed.columns).toHaveLength(2)
+      expect(parsed.keyColumns).toEqual(['id'])
+    })
+
+    it('INSERT roundtrip', () => {
+      const oid = getTableOid('rt.ins_test')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'val', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      parser.parse(encodeRelation(oid, 'public', 'ins_test', 0x64, cols))
+
+      const parsed = parser.parse(encodeInsert(oid, { id: 'abc', val: 'hello' }, cols))
+      expect(parsed.tag).toBe('insert')
+      expect(parsed.new.id).toBe('abc')
+      expect(parsed.new.val).toBe('hello')
+    })
+
+    it('INSERT with null', () => {
+      const oid = getTableOid('rt.null_test')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'opt', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      parser.parse(encodeRelation(oid, 'public', 'null_test', 0x64, cols))
+
+      const parsed = parser.parse(encodeInsert(oid, { id: 'x', opt: null }, cols))
+      expect(parsed.new.opt).toBeNull()
+    })
+
+    it('UPDATE with old row roundtrip', () => {
+      const oid = getTableOid('rt.upd_test')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'val', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      parser.parse(encodeRelation(oid, 'public', 'upd_test', 0x64, cols))
+
+      const parsed = parser.parse(
+        encodeUpdate(oid, { id: '1', val: 'new' }, { id: '1', val: 'old' }, cols)
+      )
+      expect(parsed.tag).toBe('update')
+      expect(parsed.new.val).toBe('new')
+      expect(parsed.old.val).toBe('old')
+    })
+
+    it('UPDATE without old row', () => {
+      const oid = getTableOid('rt.upd_no_old')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'val', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      parser.parse(encodeRelation(oid, 'public', 'upd_no_old', 0x64, cols))
+
+      const parsed = parser.parse(encodeUpdate(oid, { id: '1', val: 'v' }, null, cols))
+      expect(parsed.tag).toBe('update')
+      expect(parsed.new.val).toBe('v')
+      expect(parsed.old).toBeNull()
+      expect(parsed.key).toBeNull()
+    })
+
+    it('DELETE roundtrip', () => {
+      const oid = getTableOid('rt.del_test')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'val', typeOid: 25, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      parser.parse(encodeRelation(oid, 'public', 'del_test', 0x64, cols))
+
+      const parsed = parser.parse(encodeDelete(oid, { id: 'gone', val: 'x' }, cols))
+      expect(parsed.tag).toBe('delete')
+      expect(parsed.key.id).toBe('gone')
+    })
+
+    it('full transaction: BEGIN → RELATION → INSERT → COMMIT', () => {
+      const parser = makeParser()
+      const lsn = 0x2000000n
+      const endLsn = 0x2000100n
+      const ts = BigInt(Date.now()) * 1000n
+
+      const begin = parser.parse(encodeBegin(lsn, ts, 1))
+      expect(begin.commitLsn).toBe('00000000/02000000')
+
+      const oid = getTableOid('rt.full_tx')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'data', typeOid: 25, typeMod: -1 },
+      ]
+      parser.parse(encodeRelation(oid, 'public', 'full_tx', 0x64, cols))
+
+      const ins = parser.parse(encodeInsert(oid, { id: '1', data: 'test' }, cols))
+      expect(ins.new.id).toBe('1')
+
+      const commit = parser.parse(encodeCommit(0, lsn, endLsn, ts))
+      expect(commit.commitLsn).toBe(begin.commitLsn)
+    })
+
+    it('XLogData + CopyData wrapper roundtrip with parser', () => {
+      const lsn = 0x3000000n
+      const ts = BigInt(Date.now()) * 1000n
+      const pgoutput = encodeBegin(lsn, ts, 1)
+      const xlog = wrapXLogData(lsn, lsn, ts, pgoutput)
+      const frame = wrapCopyData(xlog)
+
+      // unwrap CopyData
+      const copyLen = r32(frame, 1)
+      const inner = frame.subarray(5, 1 + copyLen)
+
+      // parse like stream.js
+      expect(inner[0]).toBe(0x77)
+      const streamLsn = new DataView(inner.buffer, inner.byteOffset).getBigUint64(1)
+      expect(streamLsn).toBe(lsn)
+
+      // parse pgoutput
+      const parser = makeParser()
+      const parsed = parser.parse(inner.subarray(25))
+      expect(parsed.tag).toBe('begin')
+      expect(parsed.commitLsn).toBe('00000000/03000000')
+    })
+
+    it('shard schema encoding', () => {
+      const oid = getTableOid('rt.chat_0.clients')
+      const cols: ColumnInfo[] = [
+        { name: 'id', typeOid: 25, typeMod: -1, isKey: true },
+        { name: 'lastMutationID', typeOid: 20, typeMod: -1 },
+      ]
+      const parser = makeParser()
+      const rel = parser.parse(encodeRelation(oid, 'chat_0', 'clients', 0x64, cols))
+      expect(rel.schema).toBe('chat_0')
+      expect(rel.name).toBe('clients')
+    })
+
+    it('LSN ordering: slot < streaming changes', () => {
+      // validates that streaming changes will be seen as "new" by zero-cache
+      let testLsn = 0x1000000n
+      const next = () => { testLsn += 0x100n; return testLsn }
+
+      const slotLsn = next()    // CREATE_REPLICATION_SLOT
+      const beginLsn = next()   // first streaming BEGIN
+      const commitLsn = next()  // first streaming COMMIT
+
+      expect(beginLsn).toBeGreaterThan(slotLsn)
+      expect(commitLsn).toBeGreaterThan(beginLsn)
+
+      // verify lexi version ordering is preserved
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { versionToLexi } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/types/lexi-version.js')
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { toBigInt: lsnToBigInt } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/services/change-source/pg/lsn.js')
+
+      const slotHex = `00000000/${slotLsn.toString(16).padStart(8, '0')}`.toUpperCase()
+      const beginHex = `00000000/${beginLsn.toString(16).padStart(8, '0')}`.toUpperCase()
+
+      const slotVersion = versionToLexi(lsnToBigInt(slotHex))
+      const beginVersion = versionToLexi(lsnToBigInt(beginHex))
+
+      // lexi versions must maintain ordering
+      expect(beginVersion > slotVersion).toBe(true)
+    })
+  })
+
   describe('double-wrap: CopyData(XLogData(message))', () => {
     // this is the exact framing zero-cache expects for every replication message
     it('produces parseable nested structure', () => {

package/src/replication/zero-compat.test.ts

@@ -701,17 +701,22 @@ describe('zero-cache pgoutput compatibility', { timeout: 30000 }, () => {
     const s = await stream()
     const q = s.messages
 
+    // insert sequentially with waits to avoid batching
     await db.exec(`INSERT INTO public.foo (id) VALUES ('t1')`)
     await db.exec(`INSERT INTO public.foo (id) VALUES ('t2')`)
     await db.exec(`INSERT INTO public.foo (id) VALUES ('t3')`)
 
+    // orez may batch changes into fewer transactions, so just verify
+    // all inserts arrive and every begin has a matching commit
     const all: ZcMessage[] = []
     const deadline = Date.now() + 8000
     while (Date.now() < deadline) {
       const m = await q.dequeue(2000).catch(() => null)
       if (!m) break
       if (m.tag !== 'keepalive') all.push(m)
-      if (all.filter((x) => x.tag === 'commit').length >= 3) break
+      const inserts = all.filter((x) => x.tag === 'insert')
+      const commits = all.filter((x) => x.tag === 'commit')
+      if (inserts.length >= 3 && commits.length >= 1) break
     }
 
     const begins = all.filter((m) => m.tag === 'begin')
@@ -941,3 +946,229 @@ describe('zero-cache pgoutput compatibility', { timeout: 30000 }, () => {
     s.close()
   })
 })
+
+/**
+ * postgres.js replication stream test.
+ *
+ * uses the same postgres library and code path that zero-cache uses
+ * in its stream.js subscribe function. validates that orez's CopyData
+ * frames are correctly parsed by postgres.js's wire protocol handler
+ * and that zero-cache's PgoutputParser can consume the payloads.
+ */
+describe('postgres.js replication stream (zero-cache code path)', { timeout: 30000 }, () => {
+  let db: PGlite
+  let server: Server
+  let port: number
+
+  beforeEach(async () => {
+    db = new PGlite()
+    await db.waitReady
+    await db.exec(`
+      CREATE TABLE public.items (
+        id TEXT PRIMARY KEY,
+        val INTEGER,
+        note TEXT
+      )
+    `)
+    await db.exec(`CREATE PUBLICATION zero_data FOR ALL TABLES`)
+    await installChangeTracking(db)
+
+    const config = { ...getConfig(), pgPort: 0 }
+    server = await startPgProxy(db, config)
+    port = (server.address() as AddressInfo).port
+  })
+
+  afterEach(async () => {
+    server?.close()
+    await db?.close()
+  })
+
+  it('postgres.js receives CopyData and parseStreamMessage decodes it', { timeout: 30000 }, async () => {
+    // import postgres (same lib zero-cache uses)
+    const pg = (await import('postgres')).default
+
+    // create a regular connection for queries
+    const regular = pg({
+      host: '127.0.0.1',
+      port,
+      user: 'user',
+      password: 'password',
+      database: 'postgres',
+      max: 1,
+    })
+
+    // create replication connection (same as zero-cache's subscribe)
+    const session = pg({
+      host: '127.0.0.1',
+      port,
+      user: 'user',
+      password: 'password',
+      database: 'postgres',
+      max: 1,
+      fetch_types: false,
+      idle_timeout: null,
+      max_lifetime: null,
+      connection: { replication: 'database' },
+    })
+
+    try {
+      // create slot (same as zero-cache)
+      await session.unsafe(
+        `CREATE_REPLICATION_SLOT "pgjs_test" TEMPORARY LOGICAL pgoutput NOEXPORT_SNAPSHOT`
+      ).simple()
+
+      // start replication stream (same pattern as stream.js)
+      const stream = session.unsafe(
+        `START_REPLICATION SLOT "pgjs_test" LOGICAL 0/0 (proto_version '1', publication_names 'zero_data', messages 'true')`
+      ).execute()
+
+      const [readable, _writable] = await Promise.all([
+        stream.readable(),
+        stream.writable(),
+      ])
+
+      // import zero-cache's actual parser
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { PgoutputParser } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/services/change-source/pg/logical-replication/pgoutput-parser.js')
+      const typeParsers = { getTypeParser: () => String }
+      const parser = new PgoutputParser(typeParsers)
+
+      // parseStreamMessage from zero-cache's stream.js
+      function parseStreamMessage(buffer: Buffer): [bigint, any] | null {
+        if (buffer[0] !== 0x77 && buffer[0] !== 0x6b) return null
+        const lsn = buffer.readBigUInt64BE(1)
+        if (buffer[0] === 0x77) {
+          return [lsn, parser.parse(buffer.subarray(25))]
+        }
+        if (buffer.readInt8(17)) {
+          return [lsn, { tag: 'keepalive' }]
+        }
+        return null // keepalive with shouldRespond=false
+      }
+
+      // collect parsed messages
+      const messages: any[] = []
+      const collectDone = new Promise<void>((resolve) => {
+        readable.on('data', (chunk: Buffer) => {
+          const result = parseStreamMessage(chunk)
+          if (result) {
+            const [_lsn, msg] = result
+            messages.push(msg)
+          }
+        })
+        setTimeout(resolve, 3000)
+      })
+
+      await new Promise((r) => setTimeout(r, 500))
+      await regular.unsafe(`INSERT INTO public.items (id, val, note) VALUES ('pgjs', 42, 'postgres.js test')`)
+
+      await collectDone
+      readable.destroy()
+
+      // filter out keepalives
+      const data = messages.filter((m: any) => m.tag !== 'keepalive')
+
+      // should have: begin, relation, insert, commit
+      const tags = data.map((m: any) => m.tag)
+      expect(tags).toContain('begin')
+      expect(tags).toContain('relation')
+      expect(tags).toContain('insert')
+      expect(tags).toContain('commit')
+
+      // validate BEGIN has commitLsn as string (not BigInt)
+      const begin = data.find((m: any) => m.tag === 'begin')
+      expect(typeof begin.commitLsn).toBe('string')
+      expect(begin.commitLsn).toMatch(/^[0-9A-F]+\/[0-9A-F]+$/)
+
+      // validate RELATION has correct structure
+      const rel = data.find((m: any) => m.tag === 'relation')
+      expect(rel.schema).toBe('public')
+      expect(rel.name).toBe('items')
+      expect(rel.columns.length).toBe(3)
+
+      // validate INSERT has parsed values
+      const ins = data.find((m: any) => m.tag === 'insert')
+      expect(ins.relation.name).toBe('items')
+      expect(ins.new.id).toBe('pgjs')
+      expect(ins.new.val).toBe('42')
+      expect(ins.new.note).toBe('postgres.js test')
+
+      // validate COMMIT has commitLsn and commitEndLsn
+      const commit = data.find((m: any) => m.tag === 'commit')
+      expect(typeof commit.commitLsn).toBe('string')
+      expect(typeof commit.commitEndLsn).toBe('string')
+
+      // validate LSN ordering: commit.commitEndLsn > begin.commitLsn
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { toBigInt: lsnToBigInt } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/services/change-source/pg/lsn.js')
+      expect(lsnToBigInt(commit.commitEndLsn)).toBeGreaterThan(lsnToBigInt(begin.commitLsn))
+
+      // validate lexi version conversion works (storer uses this)
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { versionToLexi } = require('/Users/n8/orez/node_modules/@rocicorp/zero/out/zero-cache/src/types/lexi-version.js')
+      const beginVersion = versionToLexi(lsnToBigInt(begin.commitLsn))
+      const commitVersion = versionToLexi(lsnToBigInt(commit.commitEndLsn))
+      expect(typeof beginVersion).toBe('string')
+      expect(commitVersion > beginVersion).toBe(true)
+
+    } finally {
+      await regular.end()
+      // session.end() can hang because the replication handler keeps polling.
+      // just force-close the underlying connection by destroying the socket.
+      await session.end({ timeout: 2 }).catch(() => {})
+    }
+  })
+
+  it('postgres.js handles concurrent regular + replication connections', { timeout: 30000 }, async () => {
+    const pg = (await import('postgres')).default
+
+    const regular = pg({
+      host: '127.0.0.1', port,
+      user: 'user', password: 'password', database: 'postgres',
+      max: 1,
+    })
+
+    const session = pg({
+      host: '127.0.0.1', port,
+      user: 'user', password: 'password', database: 'postgres',
+      max: 1,
+      fetch_types: false,
+      idle_timeout: null,
+      max_lifetime: null,
+      connection: { replication: 'database' },
+    })
+
+    try {
+      await session.unsafe(
+        `CREATE_REPLICATION_SLOT "conc_test" TEMPORARY LOGICAL pgoutput NOEXPORT_SNAPSHOT`
+      ).simple()
+
+      const stream = session.unsafe(
+        `START_REPLICATION SLOT "conc_test" LOGICAL 0/0 (proto_version '1', publication_names 'zero_data', messages 'true')`
+      ).execute()
+
+      const [readable] = await Promise.all([stream.readable(), stream.writable()])
+
+      const received: Buffer[] = []
+      readable.on('data', (chunk: Buffer) => received.push(chunk))
+
+      await new Promise((r) => setTimeout(r, 300))
+
+      // do 5 inserts via regular connection while replication is active
+      for (let i = 0; i < 5; i++) {
+        await regular.unsafe(`INSERT INTO public.items (id, val) VALUES ('c${i}', ${i})`)
+      }
+
+      await new Promise((r) => setTimeout(r, 2000))
+      readable.destroy()
+
+      // should have received XLogData frames (0x77) from replication
+      const xlogFrames = received.filter((b) => b[0] === 0x77)
+      expect(xlogFrames.length).toBeGreaterThan(0)
+
+    } finally {
+      await regular.end()
+      await session.end({ timeout: 2 }).catch(() => {})
+    }
+  })
+})