@bod.ee/db 0.12.1 → 0.12.4

package/tests/replication-topology.test.ts

@@ -0,0 +1,835 @@
+import { describe, it, expect, afterEach } from 'bun:test';
+import { BodDB } from '../src/server/BodDB.ts';
+import { BodClient } from '../src/client/BodClient.ts';
+import { PathTopologyRouter, type PathTopology } from '../src/server/ReplicationEngine.ts';
+
+/** Poll until fn() returns true, or timeout (default 3s, poll every 50ms) */
+async function waitFor(fn: () => boolean, timeoutMs = 3000, intervalMs = 50): Promise<void> {
+  const start = Date.now();
+  while (!fn()) {
+    if (Date.now() - start > timeoutMs) throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+}
+
+/** Short delay for setup (connection establishment, subscription registration) */
+const settle = () => new Promise(r => setTimeout(r, 150));
+
+let nextPort = 26400 + Math.floor(Math.random() * 1000);
+
+// --- Unit: PathTopologyRouter ---
+
+describe('PathTopologyRouter', () => {
+  it('string paths default to sync', () => {
+    const router = new PathTopologyRouter(['_vfs', '_auth'], 'primary');
+    expect(router.resolve('_vfs').mode).toBe('sync');
+    expect(router.resolve('_auth').mode).toBe('sync');
+  });
+
+  it('object paths preserve mode', () => {
+    const router = new PathTopologyRouter([{ path: '_vfs', mode: 'primary' }], 'replica');
+    expect(router.resolve('_vfs').mode).toBe('primary');
+    expect(router.resolve('_vfs/file1').mode).toBe('primary');
+  });
+
+  it('longest-prefix match wins', () => {
+    const router = new PathTopologyRouter([
+      { path: '_auth', mode: 'replica' },
+      { path: '_auth/nonces', mode: 'primary' },
+    ], 'primary');
+    expect(router.resolve('_auth/sessions/s1').mode).toBe('replica');
+    expect(router.resolve('_auth/nonces/x').mode).toBe('primary');
+  });
+
+  it('unmatched path falls back to role', () => {
+    const router = new PathTopologyRouter([{ path: '_vfs', mode: 'primary' }], 'replica');
+    expect(router.resolve('users/u1').mode).toBe('replica');
+  });
+
+  it('mixed string + object array', () => {
+    const router = new PathTopologyRouter([
+      'config',
+      { path: '_vfs', mode: 'primary' },
+      { path: 'logs', mode: 'writeonly' },
+    ], 'replica');
+    expect(router.resolve('config').mode).toBe('sync');
+    expect(router.resolve('_vfs').mode).toBe('primary');
+    expect(router.resolve('logs').mode).toBe('writeonly');
+    expect(router.resolve('other').mode).toBe('replica');
+  });
+
+  it('shouldEmit for each mode', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'primary' },
+      { path: 'b', mode: 'replica' },
+      { path: 'c', mode: 'sync' },
+      { path: 'd', mode: 'readonly' },
+      { path: 'e', mode: 'writeonly' },
+    ], 'primary');
+    expect(router.shouldEmit('a/x')).toBe(true);
+    expect(router.shouldEmit('b/x')).toBe(false);
+    expect(router.shouldEmit('c/x')).toBe(true);
+    expect(router.shouldEmit('d/x')).toBe(false);
+    expect(router.shouldEmit('e/x')).toBe(true);
+  });
+
+  it('shouldApply for each mode', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'primary' },
+      { path: 'b', mode: 'replica' },
+      { path: 'c', mode: 'sync' },
+      { path: 'd', mode: 'readonly' },
+      { path: 'e', mode: 'writeonly' },
+    ], 'primary');
+    expect(router.shouldApply('a/x')).toBe(false);
+    expect(router.shouldApply('b/x')).toBe(true);
+    expect(router.shouldApply('c/x')).toBe(true);
+    expect(router.shouldApply('d/x')).toBe(true);
+    expect(router.shouldApply('e/x')).toBe(false);
+  });
+
+  it('shouldProxy/shouldReject for each mode', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'primary' },
+      { path: 'b', mode: 'replica' },
+      { path: 'c', mode: 'sync' },
+      { path: 'd', mode: 'readonly' },
+      { path: 'e', mode: 'writeonly' },
+    ], 'primary');
+    expect(router.shouldProxy('a/x')).toBe(false);
+    expect(router.shouldProxy('b/x')).toBe(true);
+    expect(router.shouldProxy('c/x')).toBe(false);
+    expect(router.shouldProxy('d/x')).toBe(false);
+    expect(router.shouldReject('d/x')).toBe(true);
+    expect(router.shouldProxy('e/x')).toBe(false);
+  });
+
+  it('writeProxy override', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'replica', writeProxy: 'reject' },
+    ], 'primary');
+    expect(router.shouldProxy('a/x')).toBe(false);
+    expect(router.shouldReject('a/x')).toBe(true);
+  });
+
+  it('getBootstrapPaths excludes sync', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'replica' },
+      { path: 'b', mode: 'sync' },
+      { path: 'c', mode: 'readonly' },
+      { path: 'd', mode: 'primary' },
+    ], 'primary');
+    const bootstrap = router.getBootstrapPaths();
+    expect(bootstrap).toContain('a');
+    expect(bootstrap).toContain('c');
+    expect(bootstrap).not.toContain('b');
+    expect(bootstrap).not.toContain('d');
+  });
+
+  it('getReplicaPaths includes sync', () => {
+    const router = new PathTopologyRouter([
+      { path: 'a', mode: 'replica' },
+      { path: 'b', mode: 'sync' },
+      { path: 'c', mode: 'readonly' },
+      { path: 'd', mode: 'primary' },
+    ], 'primary');
+    const pull = router.getReplicaPaths();
+    expect(pull).toContain('a');
+    expect(pull).toContain('b');
+    expect(pull).toContain('c');
+    expect(pull).not.toContain('d');
+  });
+});
+
+// --- Integration: Per-path topology ---
+
+describe('Per-path replication topology', () => {
+  const instances: BodDB[] = [];
+  const clients: BodClient[] = [];
+
+  afterEach(() => {
+    for (const c of clients) c.disconnect();
+    clients.length = 0;
+    for (const db of [...instances].reverse()) db.close();
+    instances.length = 0;
+  });
+
+  function getPort() { return nextPort++; }
+
+  function createNode(opts: { port: number; replication: any; rules?: any }) {
+    const db = new BodDB({ path: ':memory:', sweepInterval: 0, replication: opts.replication, rules: opts.rules });
+    db.serve({ port: opts.port });
+    instances.push(db);
+    return db;
+  }
+
+  // --- Emit filtering ---
+
+  it('primary-mode path emits to _repl', () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'primary',
+        paths: [{ path: '_vfs', mode: 'primary' }],
+      },
+    });
+    instances.push(db);
+    db.replication!.start();
+
+    db.set('_vfs/file1', { data: 'hello' });
+    const repl = db.get('_repl');
+    expect(repl).toBeTruthy();
+    const events = Object.values(repl as Record<string, any>);
+    expect(events.some((e: any) => e.path === '_vfs/file1')).toBe(true);
+  });
+
+  it('non-emitting modes do NOT emit', () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'primary',
+        paths: [
+          { path: 'local', mode: 'primary' },
+          { path: 'telemetry', mode: 'writeonly' },
+        ],
+      },
+    });
+    instances.push(db);
+    db.replication!.start();
+
+    db.set('local/data', { v: 1 });
+    db.set('telemetry/t1', { event: 'click' });
+    db.set('other/data', { v: 2 });
+
+    const repl = db.get('_repl');
+    expect(repl).toBeTruthy();
+    const events = Object.values(repl as Record<string, any>);
+    expect(events.some((e: any) => e.path === 'local/data')).toBe(true);
+    expect(events.some((e: any) => e.path === 'telemetry/t1')).toBe(true);
+    expect(events.some((e: any) => e.path === 'other/data')).toBe(true);
+  });
+
+  it('writeonly path emits', () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'primary',
+        paths: [{ path: 'telemetry', mode: 'writeonly' }],
+      },
+    });
+    instances.push(db);
+    db.replication!.start();
+
+    db.set('telemetry/t1', { event: 'click' });
+    const repl = db.get('_repl');
+    expect(repl).toBeTruthy();
+    const events = Object.values(repl as Record<string, any>);
+    expect(events.some((e: any) => e.path === 'telemetry/t1')).toBe(true);
+  });
+
+  // --- Write interception via WS Transport ---
+
+  it('readonly path rejected via WS (default, no writeProxy)', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'primary',
+        paths: [{ path: 'data', mode: 'readonly' }],
+      },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${port}` });
+    clients.push(client);
+    await client.connect();
+
+    try {
+      await client.set('data/x', 'val');
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('readonly');
+    }
+  });
+
+  it('readonly path rejected via WS (explicit writeProxy: reject)', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'replica',
+        primaryUrl: 'ws://localhost:1',
+        paths: [{ path: 'data', mode: 'readonly', writeProxy: 'reject' }],
+      },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${port}` });
+    clients.push(client);
+    await client.connect();
+
+    try {
+      await client.set('data/x', 'val');
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('readonly');
+    }
+  });
+
+  it('primary path written locally (not proxied)', async () => {
+    const port = getPort();
+    const db = createNode({
+      port,
+      replication: {
+        role: 'replica',
+        primaryUrl: 'ws://localhost:1',
+        paths: [{ path: '_vfs', mode: 'primary' }],
+      },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${port}` });
+    clients.push(client);
+    await client.connect();
+
+    await client.set('_vfs/file1', { data: 'hello' });
+    expect(db.get('_vfs/file1')).toEqual({ data: 'hello' });
+  });
+
+  it('replica path proxied to primary via WS', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [{ path: 'shared', mode: 'replica' }],
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    const client = new BodClient({ url: `ws://localhost:${rPort}` });
+    clients.push(client);
+    await client.connect();
+    await client.set('shared/item1', { v: 1 });
+
+    await waitFor(() => primary.get('shared/item1') != null);
+    expect(primary.get('shared/item1')).toEqual({ v: 1 });
+  });
+
+  // --- Write interception via REST ---
+
+  it('readonly path rejected via REST PUT', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'primary',
+        paths: [{ path: 'data', mode: 'readonly' }],
+      },
+    });
+
+    const res = await fetch(`http://localhost:${port}/db/data/x`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ v: 1 }),
+    });
+    const body = await res.json();
+    expect(body.ok).toBe(false);
+    expect(body.error).toContain('readonly');
+  });
+
+  it('readonly path rejected via REST DELETE', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'primary',
+        paths: [{ path: 'data', mode: 'readonly' }],
+      },
+    });
+
+    const res = await fetch(`http://localhost:${port}/db/data/x`, { method: 'DELETE' });
+    const body = await res.json();
+    expect(body.ok).toBe(false);
+    expect(body.error).toContain('readonly');
+  });
+
+  it('primary path written locally via REST', async () => {
+    const port = getPort();
+    const db = createNode({
+      port,
+      replication: {
+        role: 'replica',
+        primaryUrl: 'ws://localhost:1',
+        paths: [{ path: 'local', mode: 'primary' }],
+      },
+    });
+
+    const res = await fetch(`http://localhost:${port}/db/local/item1`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ v: 42 }),
+    });
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+    expect(db.get('local/item1')).toEqual({ v: 42 });
+  });
+
+  // --- Auth check before proxy (security) ---
+
+  it('rules checked before proxy on WS set', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [{ path: 'protected', mode: 'replica' }],
+      },
+      rules: { 'protected/$any': { write: false } },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${rPort}` });
+    clients.push(client);
+    await client.connect();
+
+    try {
+      await client.set('protected/x', 'val');
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('Permission denied');
+    }
+    expect(primary.get('protected/x')).toBeNull();
+  });
+
+  it('rules checked before proxy on REST PUT', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [{ path: 'protected', mode: 'replica' }],
+      },
+      rules: { 'protected/$any': { write: false } },
+    });
+
+    const res = await fetch(`http://localhost:${rPort}/db/protected/x`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ v: 1 }),
+    });
+    const body = await res.json();
+    expect(body.ok).toBe(false);
+    expect(body.error).toContain('Permission denied');
+    expect(primary.get('protected/x')).toBeNull();
+  });
+
+  // --- Fallback path behavior ---
+
+  it('unconfigured path falls back to role (proxy when connected)', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [
+          { path: 'local', mode: 'primary' },
+          { path: 'shared', mode: 'replica' },
+        ],
+      },
+    });
+    // Need to start replica to connect
+    const replica = instances[instances.length - 1];
+    await replica.replication!.start();
+    await settle();
+
+    const client = new BodClient({ url: `ws://localhost:${rPort}` });
+    clients.push(client);
+    await client.connect();
+
+    await client.set('users/u1', { name: 'Bob' });
+    await waitFor(() => primary.get('users/u1') != null);
+    expect(primary.get('users/u1')).toEqual({ name: 'Bob' });
+  });
+
+  it('unconfigured path rejected when no primary connection', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'replica',
+        paths: [{ path: 'local', mode: 'primary' }],
+      },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${port}` });
+    clients.push(client);
+    await client.connect();
+
+    try {
+      await client.set('users/u1', { name: 'Bob' });
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('readonly');
+    }
+  });
+
+  // --- Mixed-topology batch/update ---
+
+  it('batch with mixed primary+replica paths proxies entire batch (greedy)', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [
+          { path: 'local', mode: 'primary' },
+          { path: 'remote', mode: 'replica' },
+        ],
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    const client = new BodClient({ url: `ws://localhost:${rPort}` });
+    clients.push(client);
+    await client.connect();
+
+    // Batch with one primary path + one replica path → entire batch proxied to primary
+    await client.batch([
+      { op: 'set', path: 'local/a', value: 1 },
+      { op: 'set', path: 'remote/b', value: 2 },
+    ]);
+
+    // Both should end up on primary (greedy proxy)
+    await waitFor(() => primary.get('remote/b') != null);
+    expect(primary.get('remote/b')).toBe(2);
+    // local/a also went to primary via proxy
+    expect(primary.get('local/a')).toBe(1);
+  });
+
+  it('batch with readonly path rejected', async () => {
+    const port = getPort();
+    createNode({
+      port,
+      replication: {
+        role: 'primary',
+        paths: [
+          { path: 'rw', mode: 'primary' },
+          { path: 'ro', mode: 'readonly' },
+        ],
+      },
+    });
+
+    const client = new BodClient({ url: `ws://localhost:${port}` });
+    clients.push(client);
+    await client.connect();
+
+    try {
+      await client.batch([
+        { op: 'set', path: 'rw/a', value: 1 },
+        { op: 'set', path: 'ro/b', value: 2 },
+      ]);
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('readonly');
+    }
+  });
+
+  it('update with mixed paths: proxy when any path is replica', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [
+          { path: 'local', mode: 'primary' },
+          { path: 'remote', mode: 'replica' },
+        ],
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    const client = new BodClient({ url: `ws://localhost:${rPort}` });
+    clients.push(client);
+    await client.connect();
+
+    await client.update({ 'local/x': 10, 'remote/y': 20 });
+    await waitFor(() => primary.get('remote/y') != null);
+    expect(primary.get('remote/y')).toBe(20);
+  });
+
+  // --- Bootstrap per topology ---
+
+  it('replica paths pulled from primary, primary paths NOT pulled', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    primary.set('_auth/accounts/a1', { name: 'Alice' });
+    primary.set('_vfs/file1', { data: 'should-not-pull' });
+    await settle();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [
+          { path: '_auth', mode: 'replica' },
+          { path: '_vfs', mode: 'primary' },
+        ],
+      },
+    });
+    await replica.replication!.start();
+    await waitFor(() => replica.get('_auth/accounts/a1') != null);
+
+    expect(replica.get('_auth/accounts/a1')).toEqual({ name: 'Alice' });
+    expect(replica.get('_vfs/file1')).toBeNull();
+  });
+
+  it('sync paths NOT bootstrapped (avoids overwriting local state)', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    primary.set('config/remote', 'from-primary');
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: ['config'],
+      },
+    });
+    replica.set('config/local', 'from-replica');
+
+    await replica.replication!.start();
+    await settle();
+
+    // Local data preserved — sync doesn't bootstrap
+    expect(replica.get('config/local')).toBe('from-replica');
+  });
+
+  it('ongoing replication per mode', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [
+          { path: 'shared', mode: 'replica' },
+          { path: 'local', mode: 'primary' },
+        ],
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    primary.set('shared/item1', { v: 1 });
+    await waitFor(() => replica.get('shared/item1') != null);
+    expect(replica.get('shared/item1')).toEqual({ v: 1 });
+
+    primary.set('local/item1', { v: 2 });
+    // Give some time for potential (unwanted) replication, then verify it didn't happen
+    await settle();
+    expect(replica.get('local/item1')).toBeNull();
+  });
+
+  // --- Reconnect ---
+
+  it('replica re-subscribes after primary restart', async () => {
+    const pPort = getPort();
+    let primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: [{ path: 'data', mode: 'replica' }],
+        replicaId: 'reconnect-test',
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    // Write before restart
+    primary.set('data/before', { v: 1 });
+    await waitFor(() => replica.get('data/before') != null);
+    expect(replica.get('data/before')).toEqual({ v: 1 });
+
+    // Restart primary (close + create new on same port)
+    primary.close();
+    instances.splice(instances.indexOf(primary), 1);
+
+    primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    // Wait for BodClient auto-reconnect + re-subscribe
+    await waitFor(() => {
+      // Write on new primary and check if replica eventually gets it
+      primary.set('data/after', { v: 2 });
+      return replica.get('data/after') != null;
+    }, 5000, 200);
+    expect(replica.get('data/after')).toEqual({ v: 2 });
+  });
+
+  // --- Config validation ---
+
+  it('start() throws when replica paths exist but no primaryUrl', async () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'replica',
+        paths: [{ path: 'data', mode: 'replica' }],
+      },
+    });
+    instances.push(db);
+
+    try {
+      await db.replication!.start();
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.message).toContain('primaryUrl');
+    }
+  });
+
+  it('start() succeeds with only primary paths and no primaryUrl', async () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'primary',
+        paths: [{ path: '_vfs', mode: 'primary' }, { path: 'logs', mode: 'writeonly' }],
+      },
+    });
+    instances.push(db);
+
+    await db.replication!.start();
+    expect(db.replication!.started).toBe(true);
+  });
+
+  // --- Backward compatibility ---
+
+  it('no paths key = role-based (current behavior)', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+    primary.set('users/u1', { name: 'Eli' });
+    await settle();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        replicaId: `compat-test-${rPort}`,
+      },
+    });
+    await replica.replication!.start();
+    await waitFor(() => replica.get('users/u1') != null);
+
+    expect(replica.get('users/u1')).toEqual({ name: 'Eli' });
+    expect(replica.replication!.isReplica).toBe(true);
+  });
+
+  it('with paths, isReplica returns false, emitsToRepl returns true', () => {
+    const db = new BodDB({
+      path: ':memory:',
+      sweepInterval: 0,
+      replication: {
+        role: 'replica',
+        paths: [{ path: '_auth', mode: 'replica' }],
+      },
+    });
+    instances.push(db);
+    expect(db.replication!.isReplica).toBe(false);
+    expect(db.replication!.emitsToRepl).toBe(true);
+    expect(db.replication!.pullsFromPrimary).toBe(true);
+    expect(db.replication!.router).toBeTruthy();
+  });
+
+  it('sync path written locally AND emitted (end-to-end)', async () => {
+    const pPort = getPort();
+    const primary = createNode({ port: pPort, replication: { role: 'primary' } });
+    primary.replication!.start();
+
+    const rPort = getPort();
+    const replica = createNode({
+      port: rPort,
+      replication: {
+        role: 'replica',
+        primaryUrl: `ws://localhost:${pPort}`,
+        paths: ['config'],
+      },
+    });
+    await replica.replication!.start();
+    await settle();
+
+    replica.set('config/theme', 'dark');
+    expect(replica.get('config/theme')).toBe('dark');
+
+    const repl = replica.get('_repl');
+    expect(repl).toBeTruthy();
+    const events = Object.values(repl as Record<string, any>);
+    expect(events.some((e: any) => e.path === 'config/theme')).toBe(true);
+  });
+
+  it('stable replicaId derived from config', () => {
+    const opts = {
+      role: 'replica' as const,
+      primaryUrl: 'ws://localhost:4400',
+      paths: [{ path: 'data', mode: 'replica' as const }],
+    };
+    const db1 = new BodDB({ path: ':memory:', sweepInterval: 0, replication: opts });
+    const db2 = new BodDB({ path: ':memory:', sweepInterval: 0, replication: opts });
+    instances.push(db1, db2);
+
+    expect(db1.replication!.options.replicaId).toBe(db2.replication!.options.replicaId);
+    expect(db1.replication!.options.replicaId).toMatch(/^replica_/);
+  });
+});