orez 0.1.36 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "PGlite-powered zero-sync development backend. No Docker required.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,65 @@
     "./vite": {
       "types": "./dist/vite-plugin.d.ts",
       "import": "./dist/vite-plugin.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "import": "./dist/worker/index.js"
+    },
+    "./worker/cf-embed": {
+      "types": "./dist/worker/zero-cache-embed-cf.d.ts",
+      "import": "./dist/worker/zero-cache-embed-cf.js",
+      "default": "./dist/worker/zero-cache-embed-cf.js"
+    },
+    "./worker/cf-patches": {
+      "types": "./dist/worker/cf-patches.d.ts",
+      "import": "./dist/worker/cf-patches.js",
+      "default": "./dist/worker/cf-patches.js"
+    },
+    "./worker/shims/postgres": {
+      "types": "./dist/worker/shims/postgres.d.ts",
+      "import": "./dist/worker/shims/postgres.js",
+      "default": "./dist/worker/shims/postgres.js"
+    },
+    "./worker/shims/sqlite": {
+      "types": "./dist/worker/shims/sqlite.d.ts",
+      "import": "./dist/worker/shims/sqlite.js",
+      "default": "./dist/worker/shims/sqlite.js"
+    },
+    "./worker/shims/fastify": {
+      "types": "./dist/worker/shims/fastify.d.ts",
+      "import": "./dist/worker/shims/fastify.js",
+      "default": "./dist/worker/shims/fastify.js"
+    },
+    "./worker/shims/ws": {
+      "types": "./dist/worker/shims/ws.d.ts",
+      "import": "./dist/worker/shims/ws.js",
+      "default": "./dist/worker/shims/ws.js"
+    },
+    "./worker/shims/sqlite-browser": {
+      "types": "./dist/worker/shims/sqlite-browser.d.ts",
+      "import": "./dist/worker/shims/sqlite-browser.js",
+      "default": "./dist/worker/shims/sqlite-browser.js"
+    },
+    "./worker/shims/ws-browser": {
+      "types": "./dist/worker/shims/ws-browser.d.ts",
+      "import": "./dist/worker/shims/ws-browser.js",
+      "default": "./dist/worker/shims/ws-browser.js"
+    },
+    "./worker/shims/node-stub": {
+      "types": "./dist/worker/shims/node-stub.d.ts",
+      "import": "./dist/worker/shims/node-stub.js",
+      "default": "./dist/worker/shims/node-stub.js"
+    },
+    "./worker/browser-embed": {
+      "types": "./dist/worker/browser-embed.d.ts",
+      "import": "./dist/worker/browser-embed.js",
+      "default": "./dist/worker/browser-embed.js"
+    },
+    "./worker/browser-build-config": {
+      "types": "./dist/worker/browser-build-config.d.ts",
+      "import": "./dist/worker/browser-build-config.js",
+      "default": "./dist/worker/browser-build-config.js"
     }
   },
   "bin": {
@@ -28,7 +87,7 @@
     "src"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/cli-entry.js",
     "dev": "tsc --watch",
     "test": "vitest run --exclude 'src/integration/' --exclude 'src/wasm-sqlite.test.ts'",
     "test:integration": "vitest run src/integration/",
@@ -52,7 +111,7 @@
   "dependencies": {
     "@electric-sql/pglite": "0.4.1",
     "@electric-sql/pglite-tools": "^0.3.1",
-    "bedrock-sqlite": "0.1.36",
+    "bedrock-sqlite": "0.1.38",
     "citty": "^0.2.0",
     "pg-gateway": "0.3.0-beta.4",
     "pgsql-parser": "^17.9.11",

package/src/cli.ts

@@ -621,7 +621,7 @@ async function tryWireRestore(opts: {
     )
 
     // clear zero replication state (in _orez schema)
-    await sql.unsafe('TRUNCATE _orez._zero_changes').catch(() => {})
+    await sql.unsafe('TRUNCATE _orez.changes').catch(() => {})
     await sql.unsafe('TRUNCATE _orez._zero_replication_slots').catch(() => {})
     log.orez('cleared zero replication state')
 
@@ -949,6 +949,12 @@ const main = defineCommand({
       description: 'run pglite in-process instead of worker threads',
       default: false,
     },
+    'single-db': {
+      type: 'boolean',
+      description:
+        'use a single pglite instance for all databases (lighter for constrained environments)',
+      default: false,
+    },
     'on-db-ready': {
       type: 'string',
       description: 'command to run after db+proxy are ready, before zero-cache starts',
@@ -1000,6 +1006,7 @@ const main = defineCommand({
       disableWasmSqlite: args['disable-wasm-sqlite'],
       forceWasmSqlite: args['force-wasm-sqlite'],
       useWorkerThreads: !args['no-worker-threads'],
+      singleDb: args['single-db'],
       logLevel: (args['log-level'] as 'error' | 'warn' | 'info' | 'debug') || undefined,
       onDbReady: args['on-db-ready'] || undefined,
       onHealthy: args['on-healthy'] || undefined,

package/src/config.ts

@@ -18,6 +18,7 @@ export interface ZeroLiteConfig {
   disableWasmSqlite: boolean
   forceWasmSqlite: boolean
   useWorkerThreads: boolean
+  singleDb: boolean
   logLevel: LogLevel
   pgliteOptions: Partial<PGliteOptions>
   // lifecycle hooks
@@ -39,6 +40,7 @@ export function getConfig(overrides: Partial<ZeroLiteConfig> = {}): ZeroLiteConf
     disableWasmSqlite: overrides.disableWasmSqlite ?? false,
     forceWasmSqlite: overrides.forceWasmSqlite ?? false,
     useWorkerThreads: overrides.useWorkerThreads ?? true,
+    singleDb: overrides.singleDb ?? false,
     logLevel: overrides.logLevel || (process.env.OREZ_LOG_LEVEL as LogLevel) || 'warn',
     pgliteOptions: overrides.pgliteOptions || {},
     onDbReady: overrides.onDbReady,

package/src/index.ts

@@ -22,6 +22,8 @@ import { startPgProxy } from './pg-proxy.js'
 import {
   createPGliteInstances,
   createPGliteWorkerInstances,
+  createSinglePGliteInstance,
+  createSinglePGliteWorkerInstance,
   createPGliteWorker,
   runMigrations,
 } from './pglite-manager.js'
@@ -243,12 +245,17 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
     writeFileSync(adminFile, String(adminPort))
   }
 
-  // start pglite (separate instances for postgres, zero_cvr, zero_cdb)
-  // worker threads give each instance its own event loop so PGlite WASM
-  // execution doesn't block the proxy or replication handler
-  const instances = config.useWorkerThreads
-    ? await createPGliteWorkerInstances(config)
-    : await createPGliteInstances(config)
+  // start pglite instance(s).
+  // single-db mode uses one instance for all databases (lighter for constrained envs).
+  // otherwise, separate instances for postgres, zero_cvr, zero_cdb with optional
+  // worker threads for non-blocking WASM execution.
+  const instances = config.singleDb
+    ? config.useWorkerThreads
+      ? await createSinglePGliteWorkerInstance(config)
+      : await createSinglePGliteInstance(config)
+    : config.useWorkerThreads
+      ? await createPGliteWorkerInstances(config)
+      : await createPGliteInstances(config)
   const db = instances.postgres
   const managedPub = getManagedPublicationConfig()
   if (managedPub.managedByOrez) {
@@ -533,11 +540,9 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
 
         // clear upstream replication tracking so zero-cache starts from a
         // clean change stream baseline after full reset.
-        await db.exec(`TRUNCATE _orez._zero_changes`).catch(() => {})
+        await db.exec(`TRUNCATE _orez.changes`).catch(() => {})
         await db.exec(`TRUNCATE _orez._zero_replication_slots`).catch(() => {})
-        await db
-          .exec(`ALTER SEQUENCE _orez._zero_watermark RESTART WITH 1`)
-          .catch(() => {})
+        await db.exec(`ALTER SEQUENCE _orez.watermark RESTART WITH 1`).catch(() => {})
         log.orez('cleared upstream replication tracking state')
       }
 

package/src/integration/integration.test.ts

@@ -198,7 +198,7 @@ describe('orez integration', { timeout: 120000 }, () => {
     const deadline = Date.now() + timeoutMs
     while (Date.now() < deadline) {
       const result = await pglite.query<{ count: string }>(
-        `SELECT count(*)::text as count FROM _orez._zero_changes`
+        `SELECT count(*)::text as count FROM _orez.changes`
       )
       if (Number(result.rows[0]?.count) === 0) return
       await new Promise((r) => setTimeout(r, 100))

package/src/integration/restore-live-stress.test.ts

@@ -419,11 +419,11 @@ describe('live restore stress with connected frontend', { timeout: 360_000 }, ()
     ])
     const tracked = await db.query<{ count: string }>(
       `SELECT count(*)::text as count
-       FROM _orez._zero_changes
+       FROM _orez.changes
        WHERE table_name = 'public.restore_live_probe'`
     )
     if (Number(tracked.rows[0]?.count || '0') === 0) {
-      throw new Error('post-reset write was not captured in _orez._zero_changes')
+      throw new Error('post-reset write was not captured in _orez.changes')
     }
 
     await waitForPokeWithValue(downstreamAfterReset, marker, 30_000)

package/src/pg-proxy.ts

@@ -515,11 +515,16 @@ export async function startPgProxy(
       ? (dbInput as PGliteInstances)
       : { postgres: dbInput as PGlite, cvr: dbInput as PGlite, cdb: dbInput as PGlite }
 
-  // per-instance mutexes for serializing pglite access
+  // 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.
+  const sharedInstance =
+    instances.postgres === instances.cvr && instances.postgres === instances.cdb
+  const pgMutex = new Mutex()
   const mutexes = {
-    postgres: new Mutex(),
-    cvr: new Mutex(),
-    cdb: new Mutex(),
+    postgres: pgMutex,
+    cvr: sharedInstance ? pgMutex : new Mutex(),
+    cdb: sharedInstance ? pgMutex : new Mutex(),
   }
 
   // per-instance transaction state: tracks which socket owns the current transaction

package/src/pglite-manager.ts

@@ -292,6 +292,117 @@ export async function createPGliteWorkerInstances(
   }
 }
 
+/**
+ * create a single pglite instance shared across all databases.
+ *
+ * uses one instance for postgres, cvr, and cdb — much lighter than three
+ * separate instances. intended for constrained environments like cloudflare
+ * workers where running 3 pglite instances is too expensive.
+ */
+export async function createSinglePGliteInstance(
+  config: ZeroLiteConfig
+): Promise<PGliteInstances> {
+  // migrate from old single-instance layout (pgdata → pgdata-postgres)
+  const pgliteDataDir = (config.pgliteOptions as Record<string, any>)?.dataDir
+  if (!pgliteDataDir || !String(pgliteDataDir).startsWith('memory://')) {
+    const oldDataPath = resolve(config.dataDir, 'pgdata')
+    const newDataPath = resolve(config.dataDir, 'pgdata-postgres')
+    if (existsSync(oldDataPath) && !existsSync(newDataPath)) {
+      renameSync(oldDataPath, newDataPath)
+      log.debug.pglite('migrated pgdata → pgdata-postgres')
+    }
+  }
+
+  log.pglite('starting single shared pglite instance')
+
+  const db = await createInstance(config, 'postgres', true)
+
+  // postgres-specific setup
+  await db.exec('CREATE EXTENSION IF NOT EXISTS plpgsql')
+
+  // create publication only when explicitly configured
+  const pubName = process.env.ZERO_APP_PUBLICATIONS?.trim()
+  if (pubName) {
+    const pubs = await db.query<{ count: string }>(
+      `SELECT count(*) as count FROM pg_publication WHERE pubname = $1`,
+      [pubName]
+    )
+    if (Number(pubs.rows[0].count) === 0) {
+      const quoted = '"' + pubName.replace(/"/g, '""') + '"'
+      await db.exec(`CREATE PUBLICATION ${quoted}`)
+    }
+  }
+
+  // same instance for all three — pg-proxy detects this and shares a mutex
+  return { postgres: db, cvr: db, cdb: db }
+}
+
+/**
+ * create a single worker-backed pglite instance shared across all databases.
+ */
+export async function createSinglePGliteWorkerInstance(
+  config: ZeroLiteConfig
+): Promise<PGliteInstances> {
+  // migrate from old single-instance layout (pgdata → pgdata-postgres)
+  const pgliteDataDir = (config.pgliteOptions as Record<string, any>)?.dataDir
+  if (!pgliteDataDir || !String(pgliteDataDir).startsWith('memory://')) {
+    const oldDataPath = resolve(config.dataDir, 'pgdata')
+    const newDataPath = resolve(config.dataDir, 'pgdata-postgres')
+    if (existsSync(oldDataPath) && !existsSync(newDataPath)) {
+      renameSync(oldDataPath, newDataPath)
+      log.debug.pglite('migrated pgdata → pgdata-postgres')
+    }
+  }
+
+  const useMemory =
+    typeof pgliteDataDir === 'string' && pgliteDataDir.startsWith('memory://')
+  const {
+    dataDir: _ud,
+    debug: _dbg,
+    ...userOpts
+  } = config.pgliteOptions as Record<string, any>
+
+  const dataPath = useMemory ? 'memory://' : resolve(config.dataDir, 'pgdata-postgres')
+  if (!useMemory) {
+    mkdirSync(dataPath, { recursive: true })
+    if (cleanStaleLocks(dataPath)) {
+      log.debug.pglite('cleaned stale locks in postgres')
+    }
+  }
+
+  log.pglite('starting single shared pglite worker thread')
+
+  const proxy = new PGliteWorkerProxy({
+    dataDir: dataPath,
+    name: 'postgres',
+    withExtensions: true,
+    debug: config.logLevel === 'debug' ? 1 : 0,
+    pgliteOptions: userOpts,
+  })
+
+  await proxy.waitReady
+  log.pglite('single worker thread ready')
+
+  // postgres-specific setup
+  await proxy.exec('CREATE EXTENSION IF NOT EXISTS plpgsql')
+
+  // create publication only when explicitly configured
+  const pubName = process.env.ZERO_APP_PUBLICATIONS?.trim()
+  if (pubName) {
+    const pubs = await proxy.query<{ count: string }>(
+      `SELECT count(*) as count FROM pg_publication WHERE pubname = $1`,
+      [pubName]
+    )
+    if (Number(pubs.rows[0].count) === 0) {
+      const quoted = '"' + pubName.replace(/"/g, '""') + '"'
+      await proxy.exec(`CREATE PUBLICATION ${quoted}`)
+    }
+  }
+
+  const db = proxy as unknown as PGlite
+  return { postgres: db, cvr: db, cdb: db }
+}
+
 /** create a single worker-backed PGlite instance (for CVR/CDB recreation during reset) */
 export function createPGliteWorker(dataDir: string, name: string): PGliteWorkerProxy {
   return new PGliteWorkerProxy({

package/src/recovery.ts

@@ -100,9 +100,9 @@ export async function recoverFromCdcCorruption(ctx: RecoveryContext): Promise<vo
 
   // clear upstream replication tracking
   const db = instances.postgres
-  await db.exec(`TRUNCATE _orez._zero_changes`).catch(() => {})
+  await db.exec(`TRUNCATE _orez.changes`).catch(() => {})
   await db.exec(`TRUNCATE _orez._zero_replication_slots`).catch(() => {})
-  await db.exec(`ALTER SEQUENCE _orez._zero_watermark RESTART WITH 1`).catch(() => {})
+  await db.exec(`ALTER SEQUENCE _orez.watermark RESTART WITH 1`).catch(() => {})
 
   // drop stale shard schemas
   const shardSchemas = await db.query<{ schemaname: string }>(

package/src/replication/change-tracker.test.ts

@@ -151,7 +151,7 @@ describe('change-tracker', () => {
     try {
       await db.exec(`CREATE PUBLICATION "zero_scope"`)
       await installChangeTracking(db) // reinstall picks up publication scope
-      await db.exec(`TRUNCATE _orez._zero_changes`)
+      await db.exec(`TRUNCATE _orez.changes`)
 
       await db.exec(`INSERT INTO public.items (name, value) VALUES ('x', 1)`)
       const changes = await getChangesSince(db, 0)

package/src/replication/change-tracker.ts

@@ -17,10 +17,10 @@ export async function installChangeTracking(db: PGlite): Promise<void> {
   // create changes table and watermark sequence
   // watermark is the primary key - monotonically increasing, no separate id needed
   await db.exec(`
-    CREATE SEQUENCE IF NOT EXISTS _orez._zero_watermark;
+    CREATE SEQUENCE IF NOT EXISTS _orez.watermark;
 
-    CREATE TABLE IF NOT EXISTS _orez._zero_changes (
-      watermark BIGINT NOT NULL DEFAULT nextval('_orez._zero_watermark') PRIMARY KEY,
+    CREATE TABLE IF NOT EXISTS _orez.changes (
+      watermark BIGINT NOT NULL DEFAULT nextval('_orez.watermark') PRIMARY KEY,
       table_name TEXT NOT NULL,
       op TEXT NOT NULL CHECK (op IN ('INSERT', 'UPDATE', 'DELETE')),
       row_data JSONB,
@@ -47,7 +47,7 @@ export async function installChangeTracking(db: PGlite): Promise<void> {
     CREATE OR REPLACE FUNCTION public._zero_track_change() RETURNS TRIGGER AS $$
     BEGIN
       IF TG_OP = 'DELETE' THEN
-        INSERT INTO _orez._zero_changes (table_name, op, old_data)
+        INSERT INTO _orez.changes (table_name, op, old_data)
         VALUES (TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME, 'DELETE', to_jsonb(OLD));
         RETURN OLD;
       ELSIF TG_OP = 'UPDATE' THEN
@@ -55,11 +55,11 @@ export async function installChangeTracking(db: PGlite): Promise<void> {
         IF to_jsonb(NEW) = to_jsonb(OLD) THEN
           RETURN NEW;
         END IF;
-        INSERT INTO _orez._zero_changes (table_name, op, row_data, old_data)
+        INSERT INTO _orez.changes (table_name, op, row_data, old_data)
         VALUES (TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME, 'UPDATE', to_jsonb(NEW), to_jsonb(OLD));
         RETURN NEW;
       ELSE
-        INSERT INTO _orez._zero_changes (table_name, op, row_data)
+        INSERT INTO _orez.changes (table_name, op, row_data)
         VALUES (TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME, 'INSERT', to_jsonb(NEW));
         RETURN NEW;
       END IF;
@@ -228,7 +228,7 @@ export async function getChangesSince(
   limit = 50000
 ): Promise<ChangeRecord[]> {
   const result = await db.query<ChangeRecord>(
-    'SELECT watermark, table_name, op, row_data, old_data FROM _orez._zero_changes WHERE watermark > $1 ORDER BY watermark LIMIT $2',
+    'SELECT watermark, table_name, op, row_data, old_data FROM _orez.changes WHERE watermark > $1 ORDER BY watermark LIMIT $2',
     [watermark, limit]
   )
   return result.rows
@@ -239,14 +239,14 @@ export async function purgeConsumedChanges(
   watermark: number
 ): Promise<number> {
   const result = await db.exec(
-    `DELETE FROM _orez._zero_changes WHERE watermark <= ${Number(watermark)}`
+    `DELETE FROM _orez.changes WHERE watermark <= ${Number(watermark)}`
   )
   return result[0]?.affectedRows ?? 0
 }
 
 export async function getCurrentWatermark(db: PGlite): Promise<number> {
   const result = await db.query<{ last_value: string; is_called: boolean }>(
-    'SELECT last_value, is_called FROM _orez._zero_watermark'
+    'SELECT last_value, is_called FROM _orez.watermark'
   )
   const { last_value, is_called } = result.rows[0]
   if (!is_called) return 0

package/src/replication/handler.test.ts

@@ -367,3 +367,40 @@ describe('handleStartReplication', () => {
     expect(begins).toBeGreaterThanOrEqual(1)
   }, 10_000)
 })
+
+describe('InProcessWriter', () => {
+  it('routes data to callback', async () => {
+    const { InProcessWriter } = await import('./handler')
+    const received: Uint8Array[] = []
+    const writer = new InProcessWriter((data) => received.push(data))
+
+    const msg = new Uint8Array([1, 2, 3])
+    writer.write(msg)
+    expect(received).toHaveLength(1)
+    expect(received[0]).toEqual(msg)
+    expect(writer.closed).toBe(false)
+  })
+
+  it('stops delivering after close', async () => {
+    const { InProcessWriter } = await import('./handler')
+    const received: Uint8Array[] = []
+    const writer = new InProcessWriter((data) => received.push(data))
+
+    writer.write(new Uint8Array([1]))
+    writer.close()
+    writer.write(new Uint8Array([2]))
+
+    expect(received).toHaveLength(1)
+    expect(writer.closed).toBe(true)
+  })
+
+  it('implements ReplicationWriter interface', async () => {
+    const { InProcessWriter } = await import('./handler')
+    const writer = new InProcessWriter(() => {})
+
+    // type check: can assign to ReplicationWriter
+    const rw: ReplicationWriter = writer
+    expect(rw.write).toBeDefined()
+    expect(rw.closed).toBe(false)
+  })
+})

package/src/replication/handler.ts

@@ -37,6 +37,34 @@ export interface ReplicationWriter {
   readonly closed?: boolean
 }
 
+/**
+ * in-process replication writer. routes pgoutput data via callback
+ * instead of a TCP socket. used in CF Workers / embedded mode where
+ * there's no network between orez and zero-cache.
+ */
+export class InProcessWriter implements ReplicationWriter {
+  #onData: (data: Uint8Array) => void
+  #closed = false
+
+  constructor(onData: (data: Uint8Array) => void) {
+    this.#onData = onData
+  }
+
+  write(data: Uint8Array): void {
+    if (!this.#closed) {
+      this.#onData(data)
+    }
+  }
+
+  get closed(): boolean {
+    return this.#closed
+  }
+
+  close(): void {
+    this.#closed = true
+  }
+}
+
 // current lsn counter
 let currentLsn = 0x1000000n
 // persistent watermark across handler restarts so new handlers
@@ -303,7 +331,7 @@ export async function handleStartReplication(
   db: PGlite,
   mutex: Mutex
 ): Promise<void> {
-  log.repl('entering streaming mode')
+  log.debug.repl('entering streaming mode')
 
   // send CopyBothResponse to enter streaming mode
   const copyBoth = new Uint8Array(1 + 4 + 1 + 2)
@@ -365,7 +393,7 @@ export async function handleStartReplication(
         const all = await db.query<{ tablename: string }>(
           `SELECT tablename FROM pg_tables
            WHERE schemaname = 'public'
-             AND tablename NOT IN ('migrations', '_zero_changes')
+             AND tablename NOT IN ('migrations', 'changes')
              AND tablename NOT LIKE '_zero_%'`
         )
         tables = all.rows
@@ -375,7 +403,7 @@ export async function handleStartReplication(
       const ddlParts: string[] = [
         `CREATE OR REPLACE FUNCTION public._zero_notify_change() RETURNS TRIGGER AS $$
         BEGIN
-          PERFORM pg_notify('_zero_changes', TG_TABLE_NAME);
+          PERFORM pg_notify('changes', TG_TABLE_NAME);
           RETURN NULL;
         END;
         $$ LANGUAGE plpgsql;`,
@@ -577,11 +605,15 @@ export async function handleStartReplication(
   // register direct wakeup so the proxy can signal us immediately
   _replicationWakeup = wakeup
 
+  // expose on globalThis so external code (e.g. pglite-pool) can signal
+  // without importing from this module (works across separate bundles)
+  ;(globalThis as any).__orez_signal_replication = wakeup
+
   // also set up LISTEN as secondary signal
   let unsubscribe: (() => Promise<void>) | null = null
   try {
-    unsubscribe = await db.listen('_zero_changes', wakeup)
-    log.debug.proxy('replication: listening for _zero_changes notifications')
+    unsubscribe = await db.listen('changes', wakeup)
+    log.debug.proxy('replication: listening for changes notifications')
   } catch {
     log.debug.proxy('replication: LISTEN not available')
   }
@@ -605,6 +637,9 @@ export async function handleStartReplication(
         if (!queryPending) {
           // check if a signal arrived while we were processing
           if (!signalPending) {
+            log.debug.repl(
+              `waiting for signal (lastWm=${lastWatermark}, streamed=${hasStreamedOnce})`
+            )
             const wasSignaled = await waitForWakeup(pollIntervalIdle)
             if (writer.closed || db.closed) {
               running = false
@@ -658,6 +693,9 @@ export async function handleStartReplication(
         // try to acquire mutex without blocking proxy connections.
         // post-sync: short backoff since writes signal us directly.
         // pre-sync: yield more generously so zero-cache initial copy can finish.
+        log.debug.repl(
+          `pre-query: tryAcquire mutex (streamed=${hasStreamedOnce}, fails=${tryAcquireFailures})`
+        )
         if (!mutex.tryAcquire()) {
           if (hasStreamedOnce) {
             // post-sync: block immediately. change query is fast (~0.5ms),
@@ -739,6 +777,7 @@ export async function handleStartReplication(
             continue
           }
 
+          log.debug.repl(`streaming ${changes.length} changes to writer`)
           await streamChanges(
             changes,
             writer,
@@ -750,6 +789,7 @@ export async function handleStartReplication(
           )
           lastWatermark = batchEnd
           lastStreamedWatermark = batchEnd
+          log.debug.repl(`streamed ok, watermark=${batchEnd}`)
           hasStreamedOnce = true
 
           // purge consumed changes periodically to free wasm memory
@@ -793,7 +833,7 @@ export async function handleStartReplication(
     }
   }
 
-  log.repl(`starting poll (lastWatermark=${lastWatermark})`)
+  log.debug.repl(`starting poll (lastWatermark=${lastWatermark})`)
   try {
     await poll()
   } finally {

package/src/wasm-sqlite.test.ts

@@ -19,7 +19,8 @@ import { resolve } from 'node:path'
 
 // import bedrock-sqlite directly (our wasm build)
 // @ts-expect-error - CJS module
-import { Database } from 'bedrock-sqlite'
+import bedrockSqlite from 'bedrock-sqlite'
+const { Database } = bedrockSqlite
 import { describe, test, expect, beforeEach, afterEach } from 'vitest'
 
 // helper: temp db file