@bod.ee/db 0.7.0 → 0.9.0

package/src/server/BodDB.ts

@@ -7,6 +7,8 @@ import { FTSEngine, type FTSEngineOptions } from './FTSEngine.ts';
 import { VectorEngine, type VectorEngineOptions } from './VectorEngine.ts';
 import { StreamEngine, type CompactOptions } from './StreamEngine.ts';
 import { MQEngine, type MQEngineOptions } from './MQEngine.ts';
+import { ReplicationEngine, type ReplicationOptions, type WriteEvent } from './ReplicationEngine.ts';
+import { VFSEngine, type VFSEngineOptions } from './VFSEngine.ts';
 import { validatePath } from '../shared/pathUtils.ts';
 
 export interface TransactionProxy {
@@ -32,6 +34,10 @@ export class BodDBOptions {
   compact?: Record<string, CompactOptions>;
   /** Message queue config */
   mq?: Partial<MQEngineOptions>;
+  /** Replication config */
+  replication?: Partial<ReplicationOptions>;
+  /** VFS config */
+  vfs?: Partial<VFSEngineOptions>;
   port?: number;
   auth?: TransportOptions['auth'];
   transport?: Partial<TransportOptions>;
@@ -45,10 +51,17 @@ export class BodDB {
   readonly mq: MQEngine;
   readonly fts: FTSEngine | null = null;
   readonly vectors: VectorEngine | null = null;
+  readonly vfs: VFSEngine | null = null;
   readonly options: BodDBOptions;
+  replication: ReplicationEngine | null = null;
+  private _replaying = false;
+  private _onWriteHooks: Array<(ev: WriteEvent) => void> = [];
   private _transport: Transport | null = null;
   get transport(): Transport | null { return this._transport; }
   private sweepTimer: ReturnType<typeof setInterval> | null = null;
+  private _statsInterval: ReturnType<typeof setInterval> | null = null;
+  private _lastCpuUsage = process.cpuUsage();
+  private _lastCpuTime = performance.now();
 
   constructor(options?: Partial<BodDBOptions>) {
     this.options = { ...new BodDBOptions(), ...options };
@@ -89,10 +102,25 @@ export class BodDB {
       this.vectors = new VectorEngine(this.storage.db, this.options.vectors);
     }
 
+    // Initialize VFS if configured
+    if (this.options.vfs) {
+      (this as { vfs: VFSEngine }).vfs = new VFSEngine(this, this.options.vfs);
+    }
+
     // Start TTL sweep
     if (this.options.sweepInterval > 0) {
       this.sweepTimer = setInterval(() => this.sweep(), this.options.sweepInterval);
     }
+
+    // Init replication
+    if (this.options.replication) {
+      this.replication = new ReplicationEngine(this, this.options.replication);
+      // Auto-add _repl compaction for primary
+      if (this.replication.isPrimary) {
+        const compactOpts = this.options.replication.compact ?? { keepKey: 'path', maxCount: 10000 };
+        this.stream.options.compact = { ...this.stream.options.compact, _repl: compactOpts };
+      }
+    }
   }
 
   /** Load rules from a JSON or TS file synchronously */
@@ -137,6 +165,21 @@ export class BodDB {
     throw new Error(`Unsupported config file format: ${filePath}. Use .ts, .js, or .json.`);
   }
 
+  /** Set replaying flag (used by ReplicationEngine to prevent re-emission) */
+  setReplaying(v: boolean): void { this._replaying = v; }
+
+  /** Register a write hook. Returns unsubscribe function. */
+  onWrite(cb: (ev: WriteEvent) => void): () => void {
+    this._onWriteHooks.push(cb);
+    return () => { this._onWriteHooks = this._onWriteHooks.filter(h => h !== cb); };
+  }
+
+  /** Fire write hooks (skipped during replication replay) */
+  private _fireWrite(ev: WriteEvent): void {
+    if (this._replaying) return;
+    for (const cb of this._onWriteHooks) cb(ev);
+  }
+
   get(path: string): unknown {
     return this.storage.get(path);
   }
@@ -155,6 +198,7 @@ export class BodDB {
     if (this.subs.hasSubscriptions) {
       this.subs.notify(changed, (pp) => this.storage.get(pp), existedBefore);
     }
+    this._fireWrite({ op: 'set', path: p, value, ttl: options?.ttl });
   }
 
   /** Manually trigger TTL sweep + stream auto-compact, returns expired paths */
@@ -163,6 +207,10 @@ export class BodDB {
     if (expired.length > 0 && this.subs.hasSubscriptions) {
       this.subs.notify(expired, (p) => this.storage.get(p));
     }
+    // Fire delete events for expired paths (replication)
+    for (const p of expired) {
+      this._fireWrite({ op: 'delete', path: p });
+    }
     this.stream.autoCompact();
     this.mq.sweep();
     return expired;
@@ -180,6 +228,10 @@ export class BodDB {
     if (this.subs.hasSubscriptions) {
       this.subs.notify(changed, (p) => this.storage.get(p), existedBefore);
     }
+    // Emit per-path set events for replication (each path becomes its own repl event)
+    for (const [path, value] of Object.entries(updates)) {
+      this._fireWrite({ op: 'set', path: validatePath(path), value });
+    }
   }
 
   delete(path: string): void {
@@ -189,6 +241,7 @@ export class BodDB {
     if (this.subs.hasSubscriptions) {
       this.subs.notify([p], (pp) => this.storage.get(pp), existedBefore);
     }
+    this._fireWrite({ op: 'delete', path: p });
   }
 
   /** Push a value with auto-generated time-sortable key (stored as single JSON row, not flattened) */
@@ -199,6 +252,9 @@ export class BodDB {
     if (!duplicate && this.subs.hasSubscriptions) {
       this.subs.notify(changedPaths, (pp) => this.storage.get(pp), existedBefore);
     }
+    if (!duplicate) {
+      this._fireWrite({ op: 'push', path: p, value, pushKey: key });
+    }
     return key;
   }
 
@@ -247,6 +303,7 @@ export class BodDB {
   transaction<T>(fn: (tx: TransactionProxy) => T): T {
     const allChanged: string[] = [];
     const allExistedBefore = new Set<string>();
+    const txWriteEvents: WriteEvent[] = [];
     const proxy: TransactionProxy = {
       get: (path: string) => this.storage.get(path),
       set: (path: string, value: unknown) => {
@@ -255,6 +312,7 @@ export class BodDB {
           for (const ep of this.snapshotExisting(p)) allExistedBefore.add(ep);
         }
         allChanged.push(...this.storage.set(path, value));
+        txWriteEvents.push({ op: 'set', path: p, value });
       },
       update: (updates: Record<string, unknown>) => {
         if (this.subs.hasChildSubscriptions) {
@@ -263,6 +321,9 @@ export class BodDB {
           }
         }
         allChanged.push(...this.storage.update(updates));
+        for (const [path, value] of Object.entries(updates)) {
+          txWriteEvents.push({ op: 'set', path: validatePath(path), value });
+        }
       },
       delete: (path: string) => {
         const p = validatePath(path);
@@ -271,6 +332,7 @@ export class BodDB {
         }
         this.storage.delete(path);
         allChanged.push(p);
+        txWriteEvents.push({ op: 'delete', path: p });
       },
     };
 
@@ -280,27 +342,109 @@ export class BodDB {
     if (this.subs.hasSubscriptions && allChanged.length > 0) {
       this.subs.notify(allChanged, (p) => this.storage.get(p), allExistedBefore);
     }
+    for (const ev of txWriteEvents) this._fireWrite(ev);
     return result;
   }
 
-  /** Start WebSocket + REST server */
+  /** Start publishing process/db stats to `_admin/stats` (only when subscribers exist). */
+  private _startStatsPublisher(): void {
+    if (this._statsInterval) return;
+    const { statSync } = require('fs');
+    const { cpus, totalmem } = require('os');
+    let lastOsCpus = cpus();
+
+    this._statsInterval = setInterval(() => {
+      if (!this.subs.subscriberCount('_admin')) return;
+
+      const now = performance.now();
+      const cpu = process.cpuUsage();
+      const elapsedUs = (now - this._lastCpuTime) * 1000;
+      const cpuPercent = +((cpu.user - this._lastCpuUsage.user + cpu.system - this._lastCpuUsage.system) / elapsedUs * 100).toFixed(1);
+      this._lastCpuUsage = cpu;
+      this._lastCpuTime = now;
+
+      const mem = process.memoryUsage();
+      let nodeCount = 0;
+      try { nodeCount = (this.storage.db.query('SELECT COUNT(*) as n FROM nodes WHERE mq_status IS NULL').get() as any).n; } catch {}
+      let dbSizeMb = 0;
+      try { dbSizeMb = +(statSync(this.options.path).size / 1024 / 1024).toFixed(2); } catch {}
+
+      // System CPU
+      const cur = cpus();
+      let idleDelta = 0, totalDelta = 0;
+      for (let i = 0; i < cur.length; i++) {
+        const prev = lastOsCpus[i]?.times ?? cur[i].times;
+        const c = cur[i].times;
+        idleDelta += c.idle - prev.idle;
+        totalDelta += (c.user + c.nice + c.sys + c.irq + c.idle) - (prev.user + prev.nice + prev.sys + prev.irq + prev.idle);
+      }
+      lastOsCpus = cur;
+      const sysCpu = totalDelta > 0 ? +((1 - idleDelta / totalDelta) * 100).toFixed(1) : 0;
+
+      this.set('_admin/stats', {
+        process: { cpuPercent, heapUsedMb: +(mem.heapUsed / 1024 / 1024).toFixed(2), rssMb: +(mem.rss / 1024 / 1024).toFixed(2), uptimeSec: Math.floor(process.uptime()) },
+        db: { nodeCount, sizeMb: dbSizeMb },
+        system: { cpuCores: cur.length, totalMemMb: +(totalmem() / 1024 / 1024).toFixed(0), cpuPercent: sysCpu },
+        subs: this.subs.subscriberCount(),
+        ts: Date.now(),
+      });
+    }, 1000);
+  }
+
+  /** Start standalone WebSocket + REST server on its own port */
   serve(options?: Partial<TransportOptions>) {
     const port = options?.port ?? this.options.port;
     const auth = options?.auth ?? this.options.auth;
     this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, port, auth });
+    this._startStatsPublisher();
     return this._transport.start();
   }
 
+  /**
+   * Get transport handlers for mounting on an external Bun.serve().
+   * Does NOT start a server — caller is responsible for wiring fetch/websocket.
+   *
+   * Usage:
+   * ```ts
+   * const { handleFetch, websocketConfig, newWsData } = db.getHandlers({ auth });
+   * Bun.serve({
+   *   fetch(req, server) {
+   *     if (url.pathname.startsWith('/db') || url.pathname.startsWith('/sse')) {
+   *       return handleFetch(req, server);
+   *     }
+   *     return myAppHandler(req);
+   *   },
+   *   websocket: websocketConfig,
+   * });
+   * ```
+   */
+  getHandlers(options?: Partial<TransportOptions>) {
+    const auth = options?.auth ?? this.options.auth;
+    this._transport = new Transport(this, this.rules, { ...this.options.transport, ...options, auth });
+    this._startStatsPublisher();
+    return {
+      handleFetch: this._transport.handleFetch.bind(this._transport),
+      websocketConfig: this._transport.websocketConfig,
+      newWsData: this._transport.newWsData.bind(this._transport),
+      transport: this._transport,
+    };
+  }
+
   stop() {
     this._transport?.stop();
     this._transport = null;
   }
 
   close(): void {
+    this.replication?.stop();
     if (this.sweepTimer) {
       clearInterval(this.sweepTimer);
       this.sweepTimer = null;
     }
+    if (this._statsInterval) {
+      clearInterval(this._statsInterval);
+      this._statsInterval = null;
+    }
     this.stop();
     this.subs.clear();
     this.storage.close();

package/src/server/ReplicationEngine.ts

@@ -0,0 +1,332 @@
+import type { BodDB } from './BodDB.ts';
+import { BodClient } from '../client/BodClient.ts';
+import type { ClientMessage } from '../shared/protocol.ts';
+import type { CompactOptions } from './StreamEngine.ts';
+
+export interface ReplEvent {
+  op: 'set' | 'delete' | 'push';
+  path: string;
+  value?: unknown;
+  pushKey?: string;
+  ttl?: number;
+  ts: number;
+}
+
+export interface WriteEvent {
+  op: 'set' | 'delete' | 'push';
+  path: string;
+  value?: unknown;
+  pushKey?: string;
+  ttl?: number;
+}
+
+export class ReplicationSource {
+  url: string = '';
+  auth?: () => string | Promise<string>;
+  id?: string;
+  paths: string[] = [];
+  localPrefix?: string;
+  excludePrefixes?: string[];
+}
+
+export class ReplicationOptions {
+  role: 'primary' | 'replica' = 'primary';
+  primaryUrl?: string;
+  primaryAuth?: () => string | Promise<string>;
+  replicaId?: string;
+  excludePrefixes: string[] = ['_repl', '_streams', '_mq', '_admin'];
+  /** Bootstrap replica from primary's full state before applying _repl stream */
+  fullBootstrap: boolean = true;
+  compact?: CompactOptions;
+  sources?: ReplicationSource[];
+}
+
+type ProxyableMessage = Extract<ClientMessage, { op: 'set' | 'delete' | 'update' | 'push' | 'batch' }>;
+
+export class ReplicationEngine {
+  readonly options: ReplicationOptions;
+  private client: BodClient | null = null;
+  private unsubWrite: (() => void) | null = null;
+  private unsubStream: (() => void) | null = null;
+  private sourceConns: Array<{ client: BodClient; unsub: () => void; lastEventTs: number; eventsApplied: number; pending: number }> = [];
+  private _started = false;
+  private _seq = 0;
+  private _emitting = false;
+
+  get isReplica(): boolean { return this.options.role === 'replica'; }
+  get isPrimary(): boolean { return this.options.role === 'primary'; }
+  get started(): boolean { return this._started; }
+  get seq(): number { return this._seq; }
+
+  /** Live stats snapshot for monitoring */
+  stats() {
+    return {
+      role: this.options.role,
+      started: this._started,
+      seq: this._seq,
+      sources: (this.options.sources ?? []).map((s, i) => {
+        const conn = this.sourceConns[i];
+        return {
+          url: s.url,
+          paths: s.paths,
+          localPrefix: s.localPrefix,
+          connected: !!conn?.client?.connected,
+          pending: conn?.pending ?? 0,
+          eventsApplied: conn?.eventsApplied ?? 0,
+        };
+      }),
+    };
+  }
+
+  constructor(
+    private db: BodDB,
+    options?: Partial<ReplicationOptions>,
+  ) {
+    this.options = { ...new ReplicationOptions(), ...options };
+    if (!this.options.replicaId) {
+      this.options.replicaId = `replica_${Math.random().toString(36).slice(2, 10)}`;
+    }
+  }
+
+  /** Start replication — primary listens for writes, replica connects and consumes */
+  async start(): Promise<void> {
+    if (this._started) return;
+    this._started = true;
+
+    if (this.isPrimary) {
+      this.startPrimary();
+    } else {
+      await this.startReplica();
+    }
+
+    if (this.options.sources?.length) {
+      await this.startSources();
+    }
+  }
+
+  /** Stop replication */
+  stop(): void {
+    this._started = false;
+    this.unsubWrite?.();
+    this.unsubWrite = null;
+    this.unsubStream?.();
+    this.unsubStream = null;
+    this.client?.disconnect();
+    this.client = null;
+    for (const sc of this.sourceConns) {
+      sc.unsub();
+      sc.client.disconnect();
+    }
+    this.sourceConns = [];
+  }
+
+  /** Proxy a write operation to the primary (replica mode) */
+  async proxyWrite(msg: ProxyableMessage): Promise<unknown> {
+    if (!this.client) throw new Error('Replica not connected to primary');
+    switch (msg.op) {
+      case 'set':
+        await this.client.set(msg.path, msg.value, msg.ttl ? { ttl: msg.ttl } : undefined);
+        return null;
+      case 'delete':
+        await this.client.delete(msg.path);
+        return null;
+      case 'update':
+        await this.client.update(msg.updates);
+        return null;
+      case 'push':
+        return await this.client.push(msg.path, msg.value, msg.idempotencyKey ? { idempotencyKey: msg.idempotencyKey } : undefined);
+      case 'batch':
+        return await this.client.batch(msg.operations);
+      default:
+        throw new Error(`Cannot proxy op: ${(msg as any).op}`);
+    }
+  }
+
+  // --- Primary mode ---
+
+  private startPrimary(): void {
+    this.unsubWrite = this.db.onWrite((ev: WriteEvent) => {
+      this.emit(ev);
+    });
+  }
+
+  private isExcluded(path: string): boolean {
+    return this.options.excludePrefixes.some(p => path.startsWith(p));
+  }
+
+  private emit(ev: WriteEvent): void {
+    // Guard against recursion (db.push('_repl') triggers _fireWrite → emit)
+    if (this._emitting) return;
+    if (this.isExcluded(ev.path)) return;
+
+    this._emitting = true;
+    try {
+      const replEvent: ReplEvent = { ...ev, ts: Date.now() };
+      const seq = this._seq++;
+      const idempotencyKey = `${replEvent.ts}:${seq}:${ev.path}`;
+      this.db.push('_repl', replEvent, { idempotencyKey });
+    } finally {
+      this._emitting = false;
+    }
+  }
+
+  // --- Replica mode ---
+
+  private async startReplica(): Promise<void> {
+    if (!this.options.primaryUrl) throw new Error('primaryUrl required for replica mode');
+
+    this.client = new BodClient({
+      url: this.options.primaryUrl,
+      auth: this.options.primaryAuth,
+    });
+
+    await this.client.connect();
+    console.log(`  [REPL] Connected to primary ${this.options.primaryUrl}`);
+
+    // Full state bootstrap: fetch all data from primary (catches pre-replication data)
+    if (this.options.fullBootstrap) {
+      await this.bootstrapFullState();
+    }
+
+    // Stream bootstrap: apply _repl events on top (catches recent writes, deduped by idempotent set)
+    const snapshot = await this.client!.streamMaterialize('_repl', { keepKey: 'path' });
+    console.log(`  [REPL] Stream bootstrap: ${snapshot ? Object.keys(snapshot).length + ' events' : 'no events'}`);
+    if (snapshot) {
+      this.db.setReplaying(true);
+      try {
+        for (const [, event] of Object.entries(snapshot)) {
+          const ev = event as ReplEvent;
+          this.applyEvent(ev);
+        }
+      } finally {
+        this.db.setReplaying(false);
+      }
+    }
+
+    // Subscribe to ongoing events
+    const groupId = this.options.replicaId!;
+    console.log(`  [REPL] Subscribing to stream as '${groupId}'`);
+    this.unsubStream = this.client.stream('_repl', groupId).on((events) => {
+      console.log(`  [REPL] Received ${events.length} events`);
+      this.db.setReplaying(true);
+      try {
+        for (const e of events) {
+          const ev = e.val() as ReplEvent;
+          this.applyEvent(ev);
+          // Ack after applying
+          this.client!.stream('_repl', groupId).ack(e.key).catch(() => {});
+        }
+      } finally {
+        this.db.setReplaying(false);
+      }
+    });
+  }
+
+  /** Fetch full DB state from primary and apply locally */
+  private async bootstrapFullState(): Promise<void> {
+    const topLevel = await this.client!.getShallow();
+    const keys = topLevel
+      .map(e => e.key)
+      .filter(k => !this.isExcluded(k));
+    console.log(`  [REPL] Full bootstrap: ${keys.length} top-level keys [${keys.join(', ')}]`);
+    if (keys.length === 0) return;
+
+    this.db.setReplaying(true);
+    try {
+      for (const key of keys) {
+        const value = await this.client!.get(key);
+        if (value != null) {
+          this.db.set(key, value);
+        }
+      }
+    } finally {
+      this.db.setReplaying(false);
+    }
+  }
+
+  // --- Source feed subscriptions ---
+
+  private async startSources(): Promise<void> {
+    const results = await Promise.allSettled(
+      this.options.sources!.map(source => this.startSource(source)),
+    );
+    for (let i = 0; i < results.length; i++) {
+      if (results[i].status === 'rejected') {
+        const src = this.options.sources![i];
+        console.error(`[REPL] source ${src.url} paths=[${src.paths}] failed:`, (results[i] as PromiseRejectedResult).reason);
+      }
+    }
+  }
+
+  private async startSource(source: ReplicationSource): Promise<void> {
+    const client = new BodClient({ url: source.url, auth: source.auth });
+    await client.connect();
+
+    // Bootstrap: materialize _repl, filter by source paths
+    const snapshot = await client.streamMaterialize('_repl', { keepKey: 'path' });
+    if (snapshot) {
+      this.db.setReplaying(true);
+      try {
+        for (const [, event] of Object.entries(snapshot)) {
+          const ev = event as ReplEvent;
+          if (this.matchesSourcePaths(ev.path, source)) {
+            this.applyEvent(ev, source);
+          }
+        }
+      } finally {
+        this.db.setReplaying(false);
+      }
+    }
+
+    // Subscribe to ongoing events
+    const groupId = source.id || `source_${source.url}_${source.paths.sort().join('+')}`;
+    const connState = { client, unsub: () => {}, lastEventTs: Date.now(), eventsApplied: 0, pending: 0 };
+    const unsub = client.stream('_repl', groupId).on((events) => {
+      connState.pending += events.length;
+      this.db.setReplaying(true);
+      try {
+        for (const e of events) {
+          const ev = e.val() as ReplEvent;
+          connState.lastEventTs = ev.ts || Date.now();
+          if (this.matchesSourcePaths(ev.path, source)) {
+            this.applyEvent(ev, source);
+            connState.eventsApplied++;
+          }
+          connState.pending--;
+          client.stream('_repl', groupId).ack(e.key).catch(() => {});
+        }
+      } finally {
+        this.db.setReplaying(false);
+      }
+    });
+    connState.unsub = unsub;
+
+    this.sourceConns.push(connState);
+  }
+
+  private matchesSourcePaths(path: string, source: ReplicationSource): boolean {
+    if (source.excludePrefixes?.some(p => path.startsWith(p))) return false;
+    return source.paths.some(p => path === p || path.startsWith(p + '/'));
+  }
+
+  private remapPath(path: string, source: ReplicationSource): string {
+    return source.localPrefix ? `${source.localPrefix}/${path}` : path;
+  }
+
+  private applyEvent(ev: ReplEvent, source?: ReplicationSource): void {
+    const path = source ? this.remapPath(ev.path, source) : ev.path;
+    switch (ev.op) {
+      case 'set':
+        this.db.set(path, ev.value, ev.ttl ? { ttl: ev.ttl } : undefined);
+        break;
+      case 'delete':
+        this.db.delete(path);
+        break;
+      case 'push':
+        if (ev.pushKey) {
+          this.db.set(`${path}/${ev.pushKey}`, ev.value);
+        }
+        break;
+    }
+  }
+}

package/src/server/StorageEngine.ts

@@ -24,6 +24,8 @@ export class StorageEngine {
   private stmtPushIdempotent!: ReturnType<Database['prepare']>;
   private stmtGetByIdempotencyKey!: ReturnType<Database['prepare']>;
   private stmtQueryAfterKey!: ReturnType<Database['prepare']>;
+  private stmtGetWithMeta!: ReturnType<Database['prepare']>;
+  private stmtPrefixMaxUpdated!: ReturnType<Database['prepare']>;
 
   constructor(options?: Partial<StorageEngineOptions>) {
     this.options = { ...new StorageEngineOptions(), ...options };
@@ -71,6 +73,8 @@ export class StorageEngine {
     this.stmtPushIdempotent = this.db.prepare('INSERT OR IGNORE INTO nodes (path, value, updated_at, idempotency_key) VALUES (?, ?, ?, ?)');
     this.stmtGetByIdempotencyKey = this.db.prepare('SELECT path FROM nodes WHERE idempotency_key = ?');
     this.stmtQueryAfterKey = this.db.prepare('SELECT path, value FROM nodes WHERE path > ? AND path < ? AND mq_status IS NULL ORDER BY path ASC LIMIT ?');
+    this.stmtGetWithMeta = this.db.prepare('SELECT path, value, updated_at FROM nodes WHERE path = ? AND mq_status IS NULL');
+    this.stmtPrefixMaxUpdated = this.db.prepare('SELECT MAX(updated_at) as max_ua FROM nodes WHERE path >= ? AND path < ? AND mq_status IS NULL');
   }
 
   /** Check if a path has any data (exact or subtree) */
@@ -82,6 +86,21 @@ export class StorageEngine {
     return !!this.stmtExistsPrefix.get(prefix, prefixEnd(prefix));
   }
 
+  /** Get value at path with metadata (updated_at) */
+  getWithMeta(path: string): { data: unknown; updatedAt: number } | null {
+    path = validatePath(path);
+    const exact = this.stmtGetWithMeta.get(path) as { path: string; value: string; updated_at: number } | null;
+    if (exact) {
+      return { data: JSON.parse(exact.value), updatedAt: exact.updated_at };
+    }
+    // Try prefix (subtree) — use max updated_at across all leaves
+    const prefix = path + '/';
+    const rows = this.stmtPrefix.all(prefix, prefixEnd(prefix)) as Array<{ path: string; value: string }>;
+    if (rows.length === 0) return null;
+    const maxUpdated = this.stmtPrefixMaxUpdated.get(prefix, prefixEnd(prefix)) as { max_ua: number } | null;
+    return { data: reconstruct(path, rows), updatedAt: maxUpdated?.max_ua ?? 0 };
+  }
+
   /** Get value at path (reconstructs subtree if needed) */
   get(path: string, options?: { resolve?: boolean | string[] }): unknown {
     path = validatePath(path);