@bod.ee/db 0.7.0

package/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun test:*)",
+      "Bash(grep:*)",
+      "Bash(grep error::*)",
+      "Skill(git-commit)",
+      "Bash(bun run:*)",
+      "Bash(cat:*)",
+      "Bash(bun:*)",
+      "Bash(timeout 3 PORT=4401 bun run:*)",
+      "Bash(timeout 3 env PORT=4401:*)",
+      "Bash(timeout 3 env PORT=4402:*)",
+      "Bash(timeout 3 env PORT=4405:*)",
+      "Bash(git status:*)",
+      "Bash(git add:*)",
+      "Bash(cd:*)",
+      "Bash(bod-db:*)",
+      "Bash(ls:*)",
+      "Bash(ssh:*)"
+    ]
+  }
+}

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

@@ -0,0 +1,54 @@
+---
+name: config-file
+description: BodDB CLI and config files. Use when starting a server, creating configs, or customizing the CLI.
+---
+
+# CLI & Config File
+
+## CLI Usage
+
+```bash
+bod-db                         # defaults (memory, port 4400)
+bod-db config.ts               # start with config file
+bod-db --port 3000             # override port
+bod-db config.ts --port 5000   # config + override
+bod-db --memory                # force in-memory
+bod-db --path ./my.db          # override db path
+bod-db --init                  # generate bod.config.ts
+bod-db -h                      # help
+bod-db -v                      # version
+```
+
+## npm scripts
+
+```bash
+bun run serve                  # start with defaults
+bun run start                  # start with config.ts
+```
+
+## Config File Format
+
+```typescript
+import type { BodDBOptions } from 'bod-db';
+
+export default {
+  path: './.tmp/bod.db',
+  port: 4400,
+  sweepInterval: 60000,
+  rules: { '': { read: true, write: true } },
+  indexes: { 'users': ['role', 'createdAt'] },
+  fts: {},
+  vectors: { dimensions: 384 },
+  mq: { visibilityTimeout: 30, maxDeliveries: 5 },
+  compact: { 'events/logs': { maxAge: 86400 } },
+} satisfies Partial<BodDBOptions>;
+```
+
+Supports `.ts`, `.js`, `.json`. CLI flags override config values.
+
+## Programmatic
+
+```typescript
+const db = await BodDB.create('./config.ts');
+const db2 = await BodDB.create({ path: ':memory:' });
+```

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

@@ -0,0 +1,29 @@
+@skill deploying-bod-db
+@description Deploy BodDB instances to production VM via vmdrop with base+override yaml config pattern
+@returns Running BodDB service on remote VM with HTTPS
+
+## Usage
+```bash
+bun run deploy              # deploy boddb instance
+bun run deploy:bootstrap    # first-time setup (provision + deploy)
+bun run deploy:logs         # tail service logs
+bun run deploy:ssh          # SSH into VM
+```
+
+## Multi-Instance
+Create `deploy/<name>.yaml` with overrides, then:
+```bash
+bun run deploy/deploy.ts <name> bootstrap
+bun run deploy/deploy.ts <name> deploy
+```
+
+## Config Structure
+- `deploy/base.yaml` — shared defaults (host, user, HTTPS, excludes)
+- `deploy/<instance>.yaml` — instance-specific (name, port, domain, execStart)
+- `deploy/prod.config.ts` — BodDB runtime config (rules, indexes, sweep)
+- `deploy/.env.example` — secret references (SSH key path)
+
+## Adding a New Instance
+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`

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

@@ -0,0 +1,127 @@
+---
+name: developing-bod-db
+description: Guide for implementing BodDB features — storage, subscriptions, queries, transport, rules, transforms, FTS, vectors. Use when adding new capabilities, fixing bugs, or extending internals.
+---
+
+# Developing BodDB
+
+## When to Use
+- Implementing new features or engines
+- Adding features to existing engines
+- Fixing bugs or extending the test suite
+- Refactoring internals
+
+## Architecture
+
+```
+src/shared/pathUtils.ts         — path validation, flatten/reconstruct, ancestors, prefixEnd
+src/shared/protocol.ts          — wire message types (ClientMessage, ServerMessage, BatchOp)
+src/shared/errors.ts            — BodError class, error codes
+src/shared/transforms.ts        — sentinel classes, factory fns, resolveTransforms
+src/server/StorageEngine.ts     — SQLite CRUD, leaf flattening, prefix queries, transforms, TTL, push
+src/server/SubscriptionEngine.ts — value + child subs, ancestor walk, added/changed/removed
+src/server/QueryEngine.ts       — fluent builder delegating to StorageEngine.query
+src/server/BodDB.ts             — main facade: storage + subs + rules + transport + FTS + vectors + TTL
+src/server/RulesEngine.ts       — path-based permissions with $wildcard capture
+src/server/ExpressionRules.ts   — safe AST-based expression parser
+src/server/Transport.ts         — Bun.serve WS + REST + SSE, batch/push ops
+src/server/FTSEngine.ts         — SQLite FTS5 full-text search
+src/server/VectorEngine.ts      — vector similarity search (brute-force cosine/euclidean)
+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/react/hooks.ts              — useValue, useChildren, useQuery, useMutation
+client.ts                       — client entry point
+react.ts                        — React hooks entry point
+index.ts                        — server entry point (all exports)
+```
+
+## Key Patterns
+
+### Leaf flattening
+Nested objects → flat rows keyed by full path. `set('users/u1', {name:'Alice'})` → row at `users/u1/name`. Push rows are stored as single JSON (not flattened).
+
+### Prefix queries
+`WHERE path >= 'prefix/' AND path < 'prefix/\uffff'` — leverages SQLite B-tree on PK.
+
+### Transforms
+Sentinel values (`increment`, `serverTimestamp`, `arrayUnion`, `arrayRemove`, `ref`) detected via Symbol marker. Resolved against current data in `set()` and `merge()` before flattening.
+
+### Refs
+`ref(path)` stores `{ _ref: path }`. Resolved at read time via `storage.get(path, { resolve: true })`. Walks value tree, batch-fetches referenced paths.
+
+### Push IDs
+Time-sortable: 8-char base62 timestamp + 4-char random. Guaranteed unique even within same millisecond (incrementing random suffix). Stored as single JSON row.
+
+### TTL
+`expires_at INTEGER` column on nodes table. `setExpiry()` sets on all leaf rows. `sweep()` deletes expired + returns paths for subscription notifications.
+
+### Subscription notify flow
+1. Snapshot existing paths before write (`snapshotExisting`)
+2. Perform write → get `changedPaths` (leaf paths written)
+3. `notify(changedPaths, getFn, existedBefore)` → value subs on exact + ancestors, child subs with added/changed/removed
+
+### Transactions
+`db.transaction(fn)` wraps fn in `storage.db.transaction()`. Collects all changed paths + existedBefore, fires notifications after commit. Rollback on throw.
+
+### Batch protocol
+`{ op: 'batch', operations: [...] }` in Transport. Wraps all ops in `db.transaction()`. Returns array of results for push ops.
+
+### FTS5
+Separate virtual table `fts(path, content)`. Manual indexing via `db.index()`. Search via `fts MATCH` with optional path prefix filter.
+
+### Vectors
+Separate `_vectors(path, embedding)` table. Float32Array serialized as BLOB. Brute-force cosine similarity search. In-memory cache for hot vectors.
+
+### Streams (Kafka-like)
+Push paths are append-only logs. `StreamEngine` adds consumer group offsets (`_streams/<topic>/groups/<groupId>/offset`), stored via direct `storage.set/get` (bypasses rules). `subscribe()` uses subscribe-then-backfill: attach child sub first, replay from offset, drain buffer with dedup, then live. `queryAfterKey()` on StorageEngine does SQL-level `WHERE path > ? LIMIT ?` for efficient replay. Idempotent push via `idempotency_key` column + unique index — check-first approach.
+
+### 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.
+
+### 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.
+
+### Transport security
+All WS ops enforce rules checks (read/write) before executing. REST/SSE extract auth from `Authorization: Bearer <token>` header. Stream ops: `stream-read`/`stream-sub` = read, `stream-ack` = write, `stream-unsub` = skip (cleanup). Client `set()` supports `{ ttl }`. Protocol covers FTS (`fts-search`, `fts-index`), vectors (`vector-search`, `vector-store`), and stream management (`stream-snapshot`, `stream-materialize`, `stream-compact`, `stream-reset`).
+
+### Options pattern
+```typescript
+export class XOptions { field: type = default; }
+export class X {
+  constructor(options?: Partial<XOptions>) {
+    this.options = { ...new XOptions(), ...options };
+  }
+}
+```
+
+### Rules
+Path patterns with `$wildcard` capture. Most specific match wins. Supports booleans, functions, expression strings, JSON/TS config files. `BodDB.create()` for async .ts loading.
+
+## Implementation Phases
+
+- **Phase 1** (DONE): Core — StorageEngine, SubscriptionEngine, QueryEngine, BodDB facade
+- **Phase 2** (DONE): Transport (WS + REST) + RulesEngine (function-based V1)
+- **Phase 3** (DONE): Client SDK (BodClient — CRUD, queries, subscriptions, auto-reconnect)
+- **Phase 4** (DONE): Expression rules V2, SSE fallback, React hooks, benchmarks, examples
+- **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
+
+## Testing
+
+- `bun test` — 187 tests across 19 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
+- Use `forceExpire()` helper for TTL tests (avoids real-time waits)
+
+## Rules for Development
+
+- Zero external dependencies — only `bun:sqlite`
+- `readonly` on public engine fields
+- Sanitize SQL inputs — use `validatePath()` + regex for field names
+- Update CLAUDE.md, README.md, skills when completing features
+- Update `index.ts` exports for new modules
+- Provide workspace examples in `.tmp/workspace/`

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

@@ -0,0 +1,403 @@
+---
+name: using-bod-db
+description: Guide for integrating BodDB into applications — embedded reactive SQLite database. Use when setting up a BodDB instance, performing CRUD, transforms, transactions, push, TTL, search, or connecting via WebSocket/REST.
+---
+
+# Using BodDB
+
+## When to Use
+- Adding BodDB to a project as an embedded database
+- Performing CRUD operations on path-based data
+- Using transforms (increment, serverTimestamp, arrayUnion, arrayRemove, ref)
+- Running transactions or batch operations
+- Push/append-only collections with time-sortable keys
+- Setting TTL / auto-expiry on data
+- Full-text search (FTS5) or vector similarity search
+- Syncing files to the database (FileAdapter)
+- Setting up real-time subscriptions (value or child events)
+- Querying with filters, ordering, and pagination
+- Configuring permission rules and authentication
+- Connecting remote clients via WebSocket or REST
+
+## Server Setup
+
+```typescript
+import { BodDB, increment, serverTimestamp, arrayUnion, arrayRemove, ref } from 'bod-db';
+
+const db = new BodDB({
+  path: './data.db',       // SQLite file (default: ':memory:')
+  port: 4400,              // optional — only needed if calling db.serve()
+  rules: {                 // inline rules, or path to .json/.ts file
+    'users/$uid': {
+      read: true,
+      write: "auth.uid === $uid",
+    },
+  },
+  indexes: { 'users': ['role', 'createdAt'] }, // auto-create SQLite indexes
+  sweepInterval: 60000,    // TTL sweep interval in ms (0 = disabled)
+  fts: {},                 // enable FTS5 full-text search
+  vectors: { dimensions: 384 }, // enable vector search
+  auth: (token) => verifyToken(token),
+});
+
+// From config file (covers all options)
+const db2 = await BodDB.create('./config.ts');
+
+// Or inline with .ts rules file
+const db3 = await BodDB.create({ rules: './rules.ts' });
+
+// Start network server (optional — BodDB works fully in-process)
+db.serve();
+
+// CLI: bod-db config.ts --port 5000 (see config-file skill)
+```
+
+### CLI Quick Start
+
+```bash
+bod-db --init              # generate bod.config.ts
+bod-db bod.config.ts       # start server
+bun run serve              # same, via npm script
+```
+
+## CRUD
+
+```typescript
+db.set('users/u1', { name: 'Alice', role: 'admin' });
+db.get('users/u1');           // { name: 'Alice', role: 'admin' }
+db.get('users/u1/name');      // 'Alice'
+db.update({ 'users/u1/name': 'Bob', 'counters/visits': 42 });
+db.delete('users/u1');
+```
+
+## Transforms
+
+```typescript
+db.set('counters/likes', increment(5));          // atomic increment
+db.set('posts/p1/updatedAt', serverTimestamp());  // current timestamp
+db.set('posts/p1/tags', arrayUnion('new', 'hot')); // add unique items
+db.set('posts/p1/tags', arrayRemove('old'));       // remove items
+db.set('posts/p1/author', ref('users/u1'));        // store reference
+
+// Resolve refs at read time
+const resolved = db.storage.get('posts/p1', { resolve: true });
+// Or resolve specific fields only
+const partial = db.storage.get('posts/p1', { resolve: ['author'] });
+```
+
+## Push (Append-Only)
+
+```typescript
+const key = db.push('logs', { level: 'info', msg: 'started', ts: Date.now() });
+// key is time-sortable (8-char timestamp + 4-char random)
+// Stored as single JSON row (NOT flattened) for performance
+```
+
+## TTL / Auto-Expiry
+
+```typescript
+db.set('sessions/temp', { token: 'abc' }, { ttl: 3600 }); // expires in 1h
+db.sweep(); // manual sweep (also runs on interval if sweepInterval > 0)
+```
+
+## Transactions
+
+```typescript
+db.transaction((tx) => {
+  const user = tx.get('users/u1');
+  tx.set('users/u1/lastLogin', Date.now());
+  tx.update({ 'stats/logins': { total: 1 } });
+  tx.delete('temp/data');
+});
+// All ops in single SQLite transaction, notifications fire after commit
+```
+
+## Full-Text Search (FTS5)
+
+```typescript
+// Requires: fts: {} in options
+db.index('posts/p1', 'Hello world tutorial');
+db.index('posts/p1', ['title', 'body']); // index specific fields
+
+db.search({ text: 'hello', path: 'posts', limit: 10 });
+// Returns: [{ path, data, rank }]
+```
+
+## Vector Search
+
+```typescript
+// Requires: vectors: { dimensions: N } in options
+db.vectors!.store('docs/d1', [0.1, 0.2, ...]);
+db.vectorSearch({ query: [0.1, 0.2, ...], path: 'docs', limit: 5, threshold: 0.7 });
+// Returns: [{ path, data, score }]
+```
+
+## File Adapter
+
+```typescript
+import { FileAdapter } from 'bod-db';
+
+const adapter = new FileAdapter(db, {
+  root: './uploads',
+  basePath: 'files',
+  watch: true,       // fs.watch for changes
+  metadata: true,    // store size, mtime, mime
+  indexContent: false,
+});
+await adapter.start();
+// Read/write through:
+await adapter.readContent('doc.txt');
+await adapter.writeContent('doc.txt', 'new content');
+```
+
+## Subscriptions
+
+```typescript
+const off = db.on('users/u1', (snap) => {
+  snap.val(); snap.path;
+});
+db.onChild('users', (event) => {
+  event.type; event.key; event.path; event.val();
+});
+off();
+```
+
+## Queries
+
+```typescript
+db.query('users')
+  .where('role', '==', 'admin')
+  .where('age', '>=', 18)
+  .order('name', 'asc')
+  .limit(10)
+  .offset(0)
+  .get();
+```
+
+## Client SDK (BodClient)
+
+```typescript
+import { BodClient } from 'bod-db/client';
+
+const client = new BodClient({
+  url: 'ws://localhost:4400',
+  auth: () => 'my-token',
+  reconnect: true,
+});
+
+await client.connect();
+
+// CRUD (all async)
+await client.set('users/u1', { name: 'Alice' });
+await client.set('sessions/s1', { token: 'x' }, { ttl: 3600 }); // TTL support
+await client.get('users/u1');
+await client.update({ 'users/u1/name': 'Bob' });
+await client.delete('users/u1');
+
+// Batch (atomic multi-op)
+await client.batch([
+  { op: 'set', path: 'a', value: 1 },
+  { op: 'delete', path: 'b' },
+  { op: 'push', path: 'logs', value: { msg: 'hi' } },
+]);
+
+// Push
+const key = await client.push('logs', { msg: 'hello' });
+
+// Query, subscribe, disconnect — same as before
+```
+
+## Wire Protocol
+
+```typescript
+// Batch
+ws.send(JSON.stringify({ id: '1', op: 'batch', operations: [
+  { op: 'set', path: 'a', value: 1 },
+  { op: 'delete', path: 'b' },
+]}));
+// Push (with optional idempotencyKey)
+ws.send(JSON.stringify({ id: '2', op: 'push', path: 'logs', value: { msg: 'hi' }, idempotencyKey: 'k1' }));
+// Stream ops
+ws.send(JSON.stringify({ id: '3', op: 'stream-read', path: 'events/orders', groupId: 'billing', limit: 100 }));
+ws.send(JSON.stringify({ id: '4', op: 'stream-ack', path: 'events/orders', groupId: 'billing', key: 'abc123' }));
+ws.send(JSON.stringify({ id: '5', op: 'stream-sub', path: 'events/orders', groupId: 'billing' }));
+// Server pushes: { type: 'stream', path, groupId, events: [{key, data}] }
+ws.send(JSON.stringify({ id: '6', op: 'stream-unsub', path: 'events/orders', groupId: 'billing' }));
+
+// MQ ops (SQS-style work queue)
+ws.send(JSON.stringify({ id: '7', op: 'mq-push', path: 'queues/jobs', value: { type: 'email' } }));
+ws.send(JSON.stringify({ id: '8', op: 'mq-fetch', path: 'queues/jobs', count: 5 }));
+ws.send(JSON.stringify({ id: '9', op: 'mq-ack', path: 'queues/jobs', key: 'abc123' }));
+ws.send(JSON.stringify({ id: '10', op: 'mq-nack', path: 'queues/jobs', key: 'abc123' }));
+ws.send(JSON.stringify({ id: '11', op: 'mq-peek', path: 'queues/jobs', count: 10 }));
+ws.send(JSON.stringify({ id: '12', op: 'mq-dlq', path: 'queues/jobs' }));
+ws.send(JSON.stringify({ id: '13', op: 'mq-purge', path: 'queues/jobs' }));           // pending only
+ws.send(JSON.stringify({ id: '14', op: 'mq-purge', path: 'queues/jobs', all: true })); // all statuses
+
+// FTS + Vector ops
+ws.send(JSON.stringify({ id: '15', op: 'fts-search', text: 'hello', path: 'posts', limit: 10 }));
+ws.send(JSON.stringify({ id: '16', op: 'fts-index', path: 'posts/p1', content: 'Hello world' }));
+ws.send(JSON.stringify({ id: '17', op: 'fts-index', path: 'posts/p1', fields: ['title', 'body'] }));
+ws.send(JSON.stringify({ id: '18', op: 'vector-search', query: [0.1, 0.2], path: 'docs', limit: 5 }));
+ws.send(JSON.stringify({ id: '19', op: 'vector-store', path: 'docs/d1', embedding: [0.1, 0.2] }));
+
+// Stream extended ops
+ws.send(JSON.stringify({ id: '20', op: 'stream-snapshot', path: 'events/orders' }));
+ws.send(JSON.stringify({ id: '21', op: 'stream-materialize', path: 'events/orders', keepKey: 'orderId' }));
+ws.send(JSON.stringify({ id: '22', op: 'stream-compact', path: 'events/orders', maxAge: 86400 }));
+ws.send(JSON.stringify({ id: '23', op: 'stream-reset', path: 'events/orders' }));
+```
+
+## Message Queue
+
+SQS-style work queue — each message claimed by exactly one worker, visibility timeout, dead letter queue.
+
+```typescript
+// Server-side
+const db = new BodDB({ mq: { visibilityTimeout: 30, maxDeliveries: 5 } });
+db.mq.push('queues/jobs', { type: 'email', to: 'alice@example.com' });
+const jobs = db.mq.fetch('queues/jobs', 5);  // claim up to 5
+db.mq.ack('queues/jobs', jobs[0].key);        // delete on success
+db.mq.nack('queues/jobs', jobs[0].key);       // release back to pending
+db.mq.peek('queues/jobs');                     // view without claiming
+db.mq.dlq('queues/jobs');                      // view dead letters
+db.mq.purge('queues/jobs');                    // delete all pending
+db.mq.purge('queues/jobs', { all: true });     // delete all (pending + inflight + DLQ)
+db.mq.sweep();                                 // reclaim expired, move to DLQ
+
+// Per-queue options
+const db2 = new BodDB({ mq: { queues: { 'queues/critical': { visibilityTimeout: 60, maxDeliveries: 10 } } } });
+
+// Client-side
+const q = client.mq('queues/jobs');
+await q.push({ type: 'email' });
+const msgs = await q.fetch(5);
+await q.ack(msgs[0].key);
+await q.nack(msgs[0].key);
+const peeked = await q.peek(10);
+const dead = await q.dlq();
+await q.purge();                  // delete pending
+await q.purge({ all: true });     // delete all (pending + inflight + DLQ)
+```
+
+## Rules
+
+Rules: path patterns with `$wildcard` capture, most-specific match wins. Supports booleans, functions, expression strings, JSON config files, and TS config files.
+
+```typescript
+// Expression syntax: auth.*, $wildcard, data/newData, ==, !=, >=, <, &&, ||, !, parens, null
+rules: {
+  'users/$uid': { read: true, write: "auth.uid === $uid" },
+  'admin': { write: (ctx) => ctx.auth?.role === 'admin' },
+}
+```
+
+## Event Streaming (Kafka-like)
+
+```typescript
+// Server-side: push events to a topic
+const key = db.push('events/orders', { orderId: 'o1', amount: 42 });
+
+// Idempotent push (dedup by key)
+db.push('events/orders', { orderId: 'o1' }, { idempotencyKey: 'order-o1' });
+
+// Read unprocessed events for a consumer group
+const events = db.stream.read('events/orders', 'billing', 100);
+// Acknowledge processing
+db.stream.ack('events/orders', 'billing', events[events.length - 1].key);
+
+// Subscribe with replay (no event loss on reconnect)
+const unsub = db.stream.subscribe('events/orders', 'billing', (events) => {
+  for (const e of events) {
+    processOrder(e.data);
+  }
+});
+unsub();
+```
+
+### Stream Compaction (Snapshot Model)
+
+Compaction folds events into a **snapshot** (base state), then deletes them.
+Live events always layer on top of the snapshot. New consumers bootstrap from snapshot + events.
+
+```typescript
+// Manual compaction — folds events into snapshot
+db.stream.compact('events/orders', { maxAge: 86400 });   // fold events older than 24h
+db.stream.compact('events/orders', { maxCount: 1000 });   // keep last 1000 live, fold rest
+db.stream.compact('events/orders', { keepKey: 'orderId' }); // kafka-style: snapshot keyed by orderId
+db.stream.compact('events/orders', { maxAge: 3600, maxCount: 500 }); // combine
+
+// Auto-compact on sweep (runs on sweepInterval timer)
+const db = new BodDB({
+  compact: {
+    'events/orders': { maxCount: 10000 },
+    'events/logs': { maxAge: 86400 },
+  },
+  sweepInterval: 60000,
+});
+
+// Read snapshot (base state)
+const snap = db.stream.snapshot('events/orders');
+// snap.key = last folded event key, snap.data = merged state
+
+// Materialize: snapshot + live events merged into one view
+const view = db.stream.materialize('events/orders', { keepKey: 'orderId' });
+// view = { o1: {orderId:'o1', status:'completed'}, o2: {...}, ... }
+
+// Safety: compaction never folds events beyond the minimum consumer group offset
+```
+
+### Client-side Streaming
+
+```typescript
+import { BodClient } from 'bod-db/client';
+
+const client = new BodClient({ url: 'ws://localhost:4400' });
+await client.connect();
+
+const reader = client.stream('events/orders', 'billing');
+
+// Manual read + ack
+const events = await reader.read(50);
+await reader.ack(events[events.length - 1].key);
+
+// Live subscription (replays from last offset, then live)
+const unsub = reader.on((events) => {
+  for (const e of events) {
+    console.log(e.key, e.val());
+  }
+});
+unsub();
+
+// Idempotent push
+await client.push('events/orders', { orderId: 'o1' }, { idempotencyKey: 'order-o1' });
+
+// FTS search + index
+await client.index('posts/p1', 'Hello world tutorial');
+await client.index('posts/p1', ['title', 'body']);
+const results = await client.search({ text: 'hello', path: 'posts', limit: 10 });
+
+// Vector search + store
+await client.vectorStore('docs/d1', [0.1, 0.2, 0.3]);
+const similar = await client.vectorSearch({ query: [0.1, 0.2, 0.3], path: 'docs', limit: 5 });
+
+// Stream snapshot, materialize, compact, reset
+const snap = await client.streamSnapshot('events/orders');
+const view = await client.streamMaterialize('events/orders', { keepKey: 'orderId' });
+await client.streamCompact('events/orders', { maxAge: 86400 });
+await client.streamReset('events/orders');
+```
+
+## Best Practices
+
+1. **Paths are your schema** — design upfront (`users/$uid/settings/theme`)
+2. **Flat is fast** — deeply nested objects create many rows
+3. **Use `push()` for append-only** — logs, events, messages
+4. **Use transforms** — `increment()` is atomic, no read-modify-write
+5. **TTL for sessions** — auto-cleanup with sweep
+6. **Transactions for consistency** — multiple ops, single commit
+7. **`batch()` over network** — single round-trip for multiple ops
+8. **`:memory:` for tests** — fast, no cleanup
+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