@bod.ee/db 0.7.0 → 0.8.0

package/.claude/settings.local.json

@@ -17,7 +17,13 @@
       "Bash(cd:*)",
       "Bash(bod-db:*)",
       "Bash(ls:*)",
-      "Bash(ssh:*)"
+      "Bash(ssh:*)",
+      "Bash(true:*)",
+      "Bash(tail:*)",
+      "Bash(lsof -ti:4400,4401 2>/dev/null | xargs kill -9 2>/dev/null)",
+      "WebFetch(domain:151.145.81.254)",
+      "WebFetch(domain:db-main.bod.ee)",
+      "Bash(md5:*)"
     ]
   }
 }

package/.claude/skills/config-file.md

@@ -41,6 +41,13 @@ export default {
   vectors: { dimensions: 384 },
   mq: { visibilityTimeout: 30, maxDeliveries: 5 },
   compact: { 'events/logs': { maxAge: 86400 } },
+  vfs: { storageRoot: './files' },
+  replication: {
+    role: 'primary',
+    sources: [
+      { url: 'ws://other-db:4400', paths: ['catalog'], localPrefix: 'ext', id: 'my-source' },
+    ],
+  },
 } satisfies Partial<BodDBOptions>;
 ```
 

package/.claude/skills/deploying-bod-db.md

@@ -27,3 +27,37 @@ bun run deploy/deploy.ts <name> deploy
 1. Create `deploy/<name>.yaml` with app.name, app.dir, runtime.port, service.name, https.domain
 2. Create `deploy/prod-<name>.config.ts` with BodDB config
 3. Run `bun run deploy/deploy.ts <name> bootstrap`
+
+## Deploying Replicas
+Add `replication` to the replica's config:
+```typescript
+// deploy/prod-eu-replica.config.ts
+export default {
+  path: './data-replica.db',
+  port: 4401,
+  replication: {
+    role: 'replica',
+    primaryUrl: 'ws://primary-host:4400',
+    replicaId: 'eu-replica-1',
+  },
+};
+```
+Primary config just needs `replication: { role: 'primary' }`. Replicas auto-bootstrap on startup.
+
+## Multi-Source Feed Subscriptions
+Pull specific paths from multiple remote DBs:
+```typescript
+// deploy/prod-aggregator.config.ts
+export default {
+  path: './data-aggregator.db',
+  port: 4402,
+  replication: {
+    role: 'primary',
+    sources: [
+      { url: 'ws://db-a:4400', paths: ['catalog'], localPrefix: 'a', id: 'agg-catalog' },
+      { url: 'ws://db-b:4400', paths: ['alerts'], localPrefix: 'b', id: 'agg-alerts' },
+    ],
+  },
+};
+```
+Set `id` for persistent consumer group offsets across restarts. Sources work with any role.

package/.claude/skills/developing-bod-db.md

@@ -30,7 +30,10 @@ src/server/VectorEngine.ts      — vector similarity search (brute-force cosine
 src/server/StreamEngine.ts      — Kafka-like event streaming: consumer groups, offsets, replay, durable subs
 src/server/MQEngine.ts          — SQS-style message queue: push/fetch/ack/nack, visibility timeout, DLQ
 src/server/FileAdapter.ts       — file system sync, watch, metadata, content read/write-through
-src/client/BodClient.ts         — WS client: CRUD, batch, push, subs, streams, auto-reconnect
+src/server/ReplicationEngine.ts  — primary/replica replication: write hooks, _repl stream, bootstrap, proxy
+src/server/VFSEngine.ts         — virtual file system: backend abstraction, LocalBackend, metadata in DB
+src/client/BodClient.ts         — WS client: CRUD, batch, push, subs, streams, VFS, auto-reconnect
+src/client/CachedClient.ts      — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware
 src/react/hooks.ts              — useValue, useChildren, useQuery, useMutation
 client.ts                       — client entry point
 react.ts                        — React hooks entry point
@@ -80,6 +83,17 @@ Push paths are append-only logs. `StreamEngine` adds consumer group offsets (`_s
 ### MQ (Message Queue)
 `MQEngine` owns all MQ SQL via `storage.db.prepare()` — same pattern as StreamEngine. Columns: `mq_status` (pending/inflight), `mq_inflight_until` (Unix ms), `mq_delivery_count`. `fetch()` uses SQLite transaction with TOCTOU guard (`changes > 0`). Ack = DELETE. Sweep reclaims expired inflight; exhausted messages move to DLQ at `<queue>/_dlq/<key>`. Per-queue options via longest prefix match on `queues` config.
 
+### Replication
+`ReplicationEngine` — primary/replica + multi-source feed subscriptions via `_repl` stream. Primary: `onWrite` hooks emit events to `_repl` stream (updates flattened to per-path sets). Replica: bootstraps via `streamMaterialize`, subscribes for ongoing events, proxies writes to primary. Guards: `_replaying` prevents re-emission, `_emitting` prevents recursion from `db.push('_repl')`. Sweep deletes are replicated. Transport checks `isReplica` and forwards write ops.
+
+**Sources** (`ReplicationSource[]`): independent of role. Each source creates a `BodClient`, bootstraps filtered `_repl` snapshot, subscribes for ongoing events. `matchesSourcePaths()` filters by path prefix. `remapPath()` prepends `localPrefix`. Events applied with `_replaying=true`. Sources connect via `Promise.allSettled` — individual failures logged, others continue. Deterministic `groupId` default: `source_${url}_${paths.join('+')}`.
+
+### VFS (Virtual File System)
+`VFSEngine` — pluggable `VFSBackend` interface (`read/write/delete/exists`). `LocalBackend` stores files at `<storageRoot>/<fileId>` via `Bun.file`/`Bun.write`. fileId = pushId (move/rename = metadata-only). Metadata stored at `_vfs/<path>/__meta` (uses `__meta` key to avoid collision with children in leaf-flattened storage). Gets subscriptions, rules, replication for free. REST transport at `/files/<path>`, WS chunked fallback (base64, 48KB chunks). Client: `VFSClient` via `client.vfs()`.
+
+### CachedClient
+`CachedClient` wraps `BodClient` with two-tier cache: in-memory `Map` (LRU, insertion-ordered eviction) + IndexedDB (`entries` object store, keyPath `path`). `get()` uses stale-while-revalidate: subscribed paths return immediately (sub keeps cache fresh), unsubscribed return stale + background `getSnapshot()`. Writes (`set/update/delete`) invalidate path + all ancestors via `pathUtils.ancestors()`. `init()` opens IDB + sweeps expired. `warmup()` bulk-loads synchronously in single IDB transaction. `close()` cleans up. Protocol: `StorageEngine.getWithMeta()` returns `{ data, updatedAt }`, `ValueSnapshot.updatedAt` carries it to client.
+
 ### FileAdapter
 Scans directory recursively on `start()`. Optional `fs.watch` for live sync. Stores metadata (size, mtime, mime) at `basePath/<relPath>`. Content read/write-through methods.
 
@@ -108,10 +122,14 @@ Path patterns with `$wildcard` capture. Most specific match wins. Supports boole
 - **Phase 5** (DONE): Rules config files, transforms/sentinels, refs, transactions, batch, push, TTL, FileAdapter, FTS5, VectorEngine
 - **Phase 6** (DONE): Event streaming — consumer groups, offset tracking, replay, idempotent push, StreamEngine
 - **Phase 7** (DONE): Message queue — MQEngine, push/fetch/ack/nack, visibility timeout, DLQ, exactly-once claim
+- **Phase 8** (DONE): MCP server — MCPAdapter, stdio + HTTP, BodClient-based, 21 tools
+- **Phase 9** (DONE): Replication — ReplicationEngine, primary + read replicas, write proxy, bootstrap, _repl stream
+- **Phase 10** (DONE): VFS — VFSEngine, LocalBackend, REST + WS transport, VFSClient SDK
+- **Phase 11** (DONE): CachedClient — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol
 
 ## Testing
 
-- `bun test` — 187 tests across 19 files
+- `bun test` — 228 tests across 22 files
 - Each engine/feature gets its own test file in `tests/`
 - Test happy path, edge cases, error cases
 - Use `{ sweepInterval: 0 }` in tests to disable background sweep

package/.claude/skills/using-bod-db.md

@@ -205,6 +205,55 @@ await client.batch([
 const key = await client.push('logs', { msg: 'hello' });
 
 // Query, subscribe, disconnect — same as before
+
+// getSnapshot — includes updatedAt metadata
+const snap = await client.getSnapshot('users/u1');
+snap.val();       // { name: 'Alice' }
+snap.updatedAt;   // 1708900000000 (ms timestamp from server)
+```
+
+## CachedClient (Browser Cache)
+
+Two-tier cache wrapper around BodClient: in-memory Map (LRU) + IndexedDB persistence.
+Stale-while-revalidate: subscribed paths always fresh, unsubscribed return stale + background refetch.
+
+```typescript
+import { BodClient, CachedClient } from 'bod-db/client';
+
+const client = new BodClient({ url: 'ws://localhost:4400' });
+await client.connect();
+
+const cached = new CachedClient(client, {
+  maxAge: 7 * 24 * 60 * 60 * 1000, // IDB entry TTL (7 days)
+  maxMemoryEntries: 500,             // LRU eviction cap
+  dbName: 'boddb-cache',             // IndexedDB database name
+  enabled: true,                     // false = pure passthrough
+});
+await cached.init(); // opens IDB, sweeps expired entries
+
+// Stale-while-revalidate get
+const val = await cached.get('users/u1'); // network on first call, cache thereafter
+
+// Subscriptions keep cache fresh
+const off = cached.on('users/u1', (snap) => {
+  // snap.val() is always fresh, cache updated automatically
+});
+off();
+
+// Writes invalidate cache (path + ancestors)
+await cached.set('users/u1/name', 'Bob');
+await cached.update({ 'users/u1/role': 'admin' });
+await cached.delete('users/u1');
+
+// Warmup — bulk-load from IDB into memory on page load
+await cached.warmup(['users/u1', 'users/u2', 'config/app']);
+
+// Passthrough for non-cached ops
+cached.client.push('logs', { msg: 'hello' });
+cached.client.batch([...]);
+cached.client.mq('queue').push({ ... });
+
+cached.close(); // cleanup IDB + memory
 ```
 
 ## Wire Protocol
@@ -388,6 +437,121 @@ await client.streamCompact('events/orders', { maxAge: 86400 });
 await client.streamReset('events/orders');
 ```
 
+## Replication (Primary + Read Replicas)
+
+```typescript
+// Primary — emits write events to _repl stream
+const primary = new BodDB({
+  path: './data.db',
+  replication: { role: 'primary' },
+});
+primary.serve({ port: 4400 });
+await primary.replication!.start();
+
+// Replica — connects to primary, bootstraps, proxies writes
+const replica = new BodDB({
+  path: ':memory:',
+  replication: {
+    role: 'replica',
+    primaryUrl: 'ws://primary-host:4400',
+    replicaId: 'eu-replica-1',
+  },
+});
+replica.serve({ port: 4401 });
+await replica.replication!.start();
+
+// Clients connect to nearest replica for reads (<5ms)
+// Writes are proxied to primary automatically
+```
+
+- Star topology: single primary, N replicas
+- Reads served locally on replica, writes forwarded to primary
+- Replicas bootstrap full state on first connect, then consume live events
+- Push keys preserved across replicas (deterministic)
+- Auto-compaction on `_repl` stream (keepKey: 'path', maxCount: 10000)
+- Excluded prefixes: `_repl`, `_streams`, `_mq` (internal data not replicated)
+
+### Multi-Source Feed Subscriptions
+
+Subscribe to specific paths from multiple remote BodDB instances — like RSS feeds for database paths.
+
+```typescript
+// Local DB pulls catalog from DB-A, alerts from DB-B
+const db = new BodDB({
+  path: './local.db',
+  replication: {
+    role: 'primary',  // can also be own primary AND consume sources
+    sources: [
+      { url: 'ws://db-a:4400', paths: ['catalog', 'config'], localPrefix: 'db-a' },
+      { url: 'ws://db-b:4400', paths: ['alerts'], localPrefix: 'db-b' },
+    ],
+  },
+});
+await db.replication!.start();
+// Remote catalog/widgets → local db-a/catalog/widgets
+// Remote alerts/sys-1   → local db-b/alerts/sys-1
+```
+
+- Sources are independent of role — a DB can be primary + consume sources
+- Each source is a one-way pull (read-only subscription)
+- Path filtering at receive time: only matching paths are applied locally
+- `localPrefix` remaps paths to avoid collisions between sources
+- `excludePrefixes` per source for fine-grained filtering
+- `id` sets a deterministic consumer group ID (persistent offset across restarts)
+- Sources connect in parallel; individual failures don't block others
+
+## Virtual File System (VFS)
+
+Files stored on disk, metadata in BodDB (gets subscriptions, rules, replication for free).
+
+```typescript
+// Server — enable VFS
+const db = new BodDB({ vfs: { storageRoot: './files' } });
+db.serve();
+
+// Server-side direct access
+db.vfs!.write('docs/readme.txt', new TextEncoder().encode('Hello'));
+const data = db.vfs!.read('docs/readme.txt');    // Uint8Array
+const stat = db.vfs!.stat('docs/readme.txt');     // FileStat
+const list = db.vfs!.list('docs');                 // FileStat[]
+db.vfs!.mkdir('docs/drafts');
+db.vfs!.move('docs/readme.txt', 'archive/readme.txt');
+db.vfs!.remove('archive/readme.txt');
+```
+
+### Client SDK
+
+```typescript
+const vfs = client.vfs();
+
+// REST (preferred for binary data)
+await vfs.upload('docs/report.pdf', pdfBytes);
+const bytes = await vfs.download('docs/report.pdf');  // Uint8Array
+
+// WS chunked fallback (base64, for environments without HTTP)
+await vfs.uploadWS('docs/report.pdf', pdfBytes);
+const bytes2 = await vfs.downloadWS('docs/report.pdf');
+
+// Metadata ops
+const stat = await vfs.stat('docs/report.pdf');   // FileStat
+const list = await vfs.list('docs');               // FileStat[]
+await vfs.mkdir('docs/drafts');
+await vfs.move('docs/report.pdf', 'archive/report.pdf');
+await vfs.delete('archive/report.pdf');
+```
+
+### REST API
+
+```
+POST   /files/<path>           — upload (raw binary body)
+GET    /files/<path>           — download
+GET    /files/<path>?stat=1    — metadata JSON
+GET    /files/<path>?list=1    — list directory JSON
+POST   /files/<path>?mkdir=1   — create directory
+PUT    /files/<path>?move=dst  — move/rename
+DELETE /files/<path>           — delete
+```
+
 ## Best Practices
 
 1. **Paths are your schema** — design upfront (`users/$uid/settings/theme`)
@@ -401,3 +565,4 @@ await client.streamReset('events/orders');
 9. **`port: 0` in tests** — random available port
 10. **Streams for event processing** — consumer groups with offset tracking, replay on reconnect
 11. **Idempotent push** — dedup with `idempotencyKey` to prevent duplicate events
+12. **CachedClient for browsers** — wrap BodClient for instant reads + cross-reload persistence via IndexedDB

package/.github/workflows/test-and-publish.yml

@@ -0,0 +1,111 @@
+name: Test and Publish
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v1
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+      - name: Run tests
+        env:
+          # Add your API keys as GitHub secrets
+          a: "1"
+        run: bun test
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: build/test_reports/
+
+  publish-npm:
+    needs: test # Ensures tests must pass before publishing
+    # Only run on push to main (not on PRs)
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip-ci]') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Needed to checkout the repository AND push the version commit/tag
+      # id-token: write # Uncomment if using OIDC for provenance
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Fetch all history and tags for version bumping
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v1
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "actions@github.com"
+
+      - name: Build
+        run: bun run build
+
+      - name: Generate models docs
+        run: bun run gen:models
+
+      - name: Bump version and commit changes
+        run: |
+          # Stage all changes including build artifacts
+          git add .
+          # Create version bump commit with all changes
+          npm version patch --no-git-tag-version
+          git add package.json bun.lock
+          git commit -m "chore(release): v$(node -p "require('./package.json').version") [skip ci]"
+
+      - name: Publish package to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # Uncomment for provenance:
+          # NPM_CONFIG_PROVENANCE: "true"
+
+      - name: Create and push tag
+        run: |
+          git tag "v$(node -p "require('./package.json').version")"
+          git push --follow-tags
+
+permissions:
+  contents: write
+

package/CLAUDE.md

@@ -22,7 +22,10 @@ src/server/StreamEngine.ts — Kafka-like event streaming: consumer groups, offs
 src/server/MQEngine.ts     — SQS-style message queue: push/fetch/ack/nack, visibility timeout, DLQ, exactly-once claim
 src/server/FileAdapter.ts  — file system sync: scan, watch, metadata, content read/write-through
 src/server/MCPAdapter.ts   — MCP (Model Context Protocol) server: JSON-RPC dispatch, tool registry, stdio + HTTP transports
+src/server/VFSEngine.ts     — virtual file system: VFSBackend interface, LocalBackend (disk), metadata in DB
+src/server/ReplicationEngine.ts — replication: primary/replica + multi-source feed subscriptions, write proxy
 src/client/BodClient.ts    — WS client: connect, auth, CRUD, batch, push, subscriptions, auto-reconnect
+src/client/CachedClient.ts — two-tier cache (memory + IndexedDB): stale-while-revalidate, sub-aware, write invalidation
 src/react/hooks.ts         — useValue, useChildren, useQuery, useMutation
 client.ts                  — client entry point (import from 'bod-db/client')
 react.ts                   — React hooks entry point (import from 'bod-db/react')
@@ -54,8 +57,11 @@ config.ts                  — demo instance config (open rules, indexes, fts, v
 - **SSE fallback**: `GET /sse/<path>?event=value|child` returns `text/event-stream`. Initial `: ok` comment flushes the stream connection.
 - **Perf**: `snapshotExisting` and `notify` are skipped when no subscriptions are active. `exists()` uses `LIMIT 1`.
 - **Transport**: WS messages follow `protocol.ts` types. REST at `/db/<path>`. Auth via `op:'auth'` message. Subs cleaned up on disconnect.
-- **BodClient**: id-correlated request/response over WS. Auto-reconnect with exponential backoff. Re-subscribes all active subs on reconnect. `ValueSnapshot` with `.val()`, `.key`, `.path`, `.exists()`.
+- **BodClient**: id-correlated request/response over WS. Auto-reconnect with exponential backoff. Re-subscribes all active subs on reconnect. `ValueSnapshot` with `.val()`, `.key`, `.path`, `.exists()`, `.updatedAt`. `getSnapshot(path)` returns ValueSnapshot with `updatedAt` from server.
+- **CachedClient**: two-tier cache wrapper around BodClient. Memory (Map, LRU eviction) + IndexedDB persistence. Stale-while-revalidate: subscribed paths always fresh, unsubscribed return stale + background refetch. Writes (`set/update/delete`) invalidate path + ancestors. `init()` opens IDB + sweeps expired. `warmup(paths[])` bulk-loads from IDB. Passthrough for `push/batch/query/search/mq/stream/vfs` via `cachedClient.client`.
 - **MCP**: `MCPAdapter` wraps a `BodClient` as a JSON-RPC MCP server (stdio + HTTP). Connects to a running BodDB instance over WebSocket — no embedded DB. Entry point: `mcp.ts`. Tools: CRUD (6), FTS (2), vectors (2), streams (4), MQ (7) = 21 tools. Use `--stdio` for Claude Code/Desktop, `--http` for remote agents.
+- **VFS (Virtual File System)**: `VFSEngine` — files stored outside SQLite via pluggable `VFSBackend` interface. `LocalBackend` stores at `<storageRoot>/<fileId>` using `Bun.file`/`Bun.write`. Metadata at `_vfs/<virtualPath>/` (size, mime, mtime, fileId, isDir) — gets subs/rules/replication for free. `fileId = pushId` so move/rename is metadata-only. REST: `POST/GET/DELETE /files/<path>`, `?stat=1`, `?list=1`, `?mkdir=1`, `PUT ?move=<dst>`. WS chunked fallback: base64-encoded `vfs-upload-init/chunk/done`, `vfs-download-init` → `vfs-download-chunk` push messages. Client: `VFSClient` via `client.vfs()` — `upload/download` (REST) + `uploadWS/downloadWS` (WS) + `stat/list/mkdir/delete/move`.
+- **Replication**: `ReplicationEngine` — single primary + N read replicas + multi-source feed subscriptions. Star topology. Primary emits write events to `_repl` stream via `onWrite` hooks. Replicas bootstrap via `streamMaterialize('_repl', { keepKey: 'path' })`, then subscribe for ongoing events. Write proxy: replica forwards writes to primary via BodClient, primary applies + emits, replica consumes. `_replaying` flag prevents re-emission loops. `_emitting` guard prevents recursion from `db.push('_repl')`. Updates flattened to per-path set events for correct compaction keying. Sweep delete events replicated. Excluded prefixes: `_repl`, `_streams`, `_mq`. **Sources**: `ReplicationSource[]` — subscribe to specific paths from multiple remote DBs. Each source is an independent BodClient that filters `_repl` events by path prefix, with optional `localPrefix` remapping (e.g. remote `users/u1` → local `db-a/users/u1`). Sources connect in parallel; individual failures don't block others. Sources are independent of role — a DB can be primary AND consume sources.
 
 ## MCP Server
 
@@ -108,3 +114,6 @@ bun test tests/storage.test.ts  # single file
 - [x] Phase 6: Event streaming (consumer groups, offset tracking, replay, idempotent push, StreamEngine)
 - [x] Phase 7: Message queue (MQEngine — push/fetch/ack/nack, visibility timeout, DLQ, exactly-once claim)
 - [x] Phase 8: MCP server (MCPAdapter — stdio + HTTP, BodClient-based, 21 tools)
+- [x] Phase 9: Replication (ReplicationEngine — primary + read replicas, write proxy, bootstrap, _repl stream, multi-source feed subscriptions)
+- [x] Phase 10: VFS — Virtual File System (VFSEngine, LocalBackend, REST + WS transport, VFSClient)
+- [x] Phase 11: CachedClient — two-tier cache (memory + IndexedDB), stale-while-revalidate, updatedAt protocol

package/README.md

@@ -2,7 +2,7 @@
 
 
 ----
-187 tests passing · ~200k ops/sec · Zero dependencies · Full docs + examples
+228 tests passing · ~200k ops/sec · Zero dependencies · Full docs + examples
 ----
 
 
@@ -120,6 +120,33 @@ client.onChild('users', (e) => console.log(e.type, e.key));
 client.disconnect();
 ```
 
+## CachedClient (Browser Cache)
+
+```typescript
+import { BodClient, CachedClient } from 'bod-db/client';
+
+const client = new BodClient({ url: 'ws://localhost:4400' });
+await client.connect();
+
+const cached = new CachedClient(client, {
+  maxMemoryEntries: 500,  // LRU eviction cap
+  maxAge: 7 * 24 * 3600000, // IDB TTL (7 days)
+});
+await cached.init();
+
+// Stale-while-revalidate: instant cache hit, background refetch
+const val = await cached.get('users/u1');
+
+// Subscriptions keep cache fresh automatically
+const off = cached.on('users/u1', (snap) => console.log(snap.val()));
+
+// Writes invalidate cache (path + ancestors)
+await cached.set('users/u1/name', 'Bob');
+
+// Warmup on page load
+await cached.warmup(['users/u1', 'config/app']);
+```
+
 ## Streams (Kafka-like)
 
 ```typescript
@@ -161,6 +188,34 @@ const msgs = await q.fetch(5);
 await q.ack(msgs[0].key);
 ```
 
+## Replication
+
+```typescript
+// Primary — emits writes to _repl stream
+const primary = new BodDB({ replication: { role: 'primary' } });
+primary.serve({ port: 4400 });
+await primary.replication!.start();
+
+// Replica — reads local, writes proxied to primary
+const replica = new BodDB({
+  replication: { role: 'replica', primaryUrl: 'ws://primary:4400', replicaId: 'r1' },
+});
+await replica.replication!.start();
+
+// Multi-source — pull specific paths from multiple remote DBs
+const aggregator = new BodDB({
+  replication: {
+    role: 'primary',
+    sources: [
+      { url: 'ws://db-a:4400', paths: ['catalog'], localPrefix: 'a', id: 'src-a' },
+      { url: 'ws://db-b:4400', paths: ['alerts'], localPrefix: 'b', id: 'src-b' },
+    ],
+  },
+});
+await aggregator.replication!.start();
+// Remote catalog/item → local a/catalog/item
+```
+
 ## Rules
 
 Function-based, expression strings, or JSON config files:
@@ -248,5 +303,5 @@ bun run tests/bench.ts
 ## Test
 
 ```bash
-bun test         # 187 tests
+bun test         # 228 tests
 ```

package/admin/proxy.ts

@@ -0,0 +1,79 @@
+// Admin UI proxy — serves ui.html locally, relays all WS traffic to a remote BodDB server.
+// Usage: bun run admin/proxy.ts <remote-url> [--port <local-port>]
+// Example: bun run admin/proxy.ts wss://db-main.bod.ee --port 4401
+
+import { join } from 'path';
+import type { ServerWebSocket } from 'bun';
+
+const args = process.argv.slice(2);
+const remoteUrl = args.find(a => !a.startsWith('--'));
+if (!remoteUrl) { console.error('Usage: bun run admin/proxy.ts <remote-ws-url> [--port <port>]'); process.exit(1); }
+
+const portIdx = args.indexOf('--port');
+const PORT = portIdx >= 0 ? Number(args[portIdx + 1]) : 4401;
+const UI_PATH = join(import.meta.dir, 'ui.html');
+
+interface ProxyWsData {
+  remote: WebSocket | null;
+  queue: string[]; // buffered messages while remote connects
+}
+
+const server = Bun.serve({
+  port: PORT,
+  fetch(req, server) {
+    const url = new URL(req.url);
+    if (req.headers.get('upgrade') === 'websocket') {
+      if (server.upgrade(req, { data: { remote: null, queue: [] } as ProxyWsData })) return;
+      return new Response('WS upgrade failed', { status: 400 });
+    }
+    if (url.pathname === '/' || url.pathname === '/ui.html') {
+      return new Response(Bun.file(UI_PATH));
+    }
+    // Proxy REST to remote via fetch
+    if (url.pathname.startsWith('/db/') || url.pathname === '/rules' ||
+        url.pathname === '/transform' || url.pathname === '/set-ttl' ||
+        url.pathname === '/sweep' || url.pathname.startsWith('/fts/') ||
+        url.pathname.startsWith('/vectors/')) {
+      const remoteHttp = remoteUrl.replace(/^ws/, 'http');
+      const target = new URL(url.pathname + url.search, remoteHttp);
+      return fetch(target.toString(), {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+      });
+    }
+    return new Response('Not found', { status: 404 });
+  },
+  websocket: {
+    open(ws: ServerWebSocket<ProxyWsData>) {
+      const remote = new WebSocket(remoteUrl);
+      ws.data.remote = remote;
+
+      remote.onopen = () => {
+        // Flush queued messages
+        for (const msg of ws.data.queue) remote.send(msg);
+        ws.data.queue = [];
+      };
+      remote.onmessage = (e) => {
+        ws.send(typeof e.data === 'string' ? e.data : e.data.toString());
+      };
+      remote.onclose = () => ws.close();
+      remote.onerror = () => ws.close();
+    },
+    message(ws: ServerWebSocket<ProxyWsData>, raw: string | Buffer) {
+      const msg = typeof raw === 'string' ? raw : raw.toString();
+      const remote = ws.data.remote;
+      if (remote?.readyState === WebSocket.OPEN) {
+        remote.send(msg);
+      } else {
+        ws.data.queue.push(msg);
+      }
+    },
+    close(ws: ServerWebSocket<ProxyWsData>) {
+      ws.data.remote?.close();
+    },
+  },
+});
+
+console.log(`BodDB Admin Proxy → http://localhost:${server.port}`);
+console.log(`Remote: ${remoteUrl}`);

package/admin/rules.ts

@@ -6,7 +6,7 @@ import type { PathRule } from '../src/server/RulesEngine.ts';
  * Context: { auth, path, params, data, newData }
  */
 export const rules: Record<string, PathRule> = {
-  '_admin/$any':   { read: false, write: false },
+  '_admin/$any':   { read: true, write: false },
   'users/$uid':    { write: ({ auth, params }) => auth?.role === 'admin' || ['alice', 'bob'].includes(params.uid) },
   'settings/$key': { write: ({ auth }) => !!auth },
 };