@bod.ee/db 0.10.2 → 0.11.1

package/src/server/SubscriptionEngine.ts

@@ -1,11 +1,27 @@
 import { ancestors } from '../shared/pathUtils.ts';
 
-export type SubscriptionCallback = (snapshot: { path: string; val: () => unknown }) => void;
+export type SubscriptionCallback = (snapshot: { path: string; val: () => unknown; updatedAt?: number }) => void;
 export type ChildCallback = (event: { type: 'added' | 'changed' | 'removed'; key: string; path: string; val: () => unknown }) => void;
 
+export class SubscriptionEngineOptions {
+  /** Maximum total subscriptions (default 50000) */
+  maxSubscriptions: number = 50000;
+  /** Enable async batched notifications (default false) */
+  asyncNotify: boolean = false;
+}
+
 export class SubscriptionEngine {
+  readonly options: SubscriptionEngineOptions;
   private valueSubs = new Map<string, Set<SubscriptionCallback>>();
   private childSubs = new Map<string, Set<ChildCallback>>();
+  private _pendingNotify: Set<string> | null = null;
+  private _pendingGetFn: ((path: string) => unknown) | null = null;
+  private _pendingExisted: Set<string> | null = null;
+  private _flushScheduled = false;
+
+  constructor(options?: Partial<SubscriptionEngineOptions>) {
+    this.options = { ...new SubscriptionEngineOptions(), ...options };
+  }
 
   get hasSubscriptions(): boolean {
     return this.valueSubs.size > 0 || this.childSubs.size > 0;
@@ -31,6 +47,7 @@ export class SubscriptionEngine {
 
   /** Subscribe to value changes at a path (fires for exact + descendant writes) */
   onValue(path: string, cb: SubscriptionCallback): () => void {
+    if (this.size >= this.options.maxSubscriptions) throw new Error('Subscription limit reached');
     if (!this.valueSubs.has(path)) this.valueSubs.set(path, new Set());
     this.valueSubs.get(path)!.add(cb);
     return () => {
@@ -41,6 +58,7 @@ export class SubscriptionEngine {
 
   /** Subscribe to child events at a path */
   onChild(path: string, cb: ChildCallback): () => void {
+    if (this.size >= this.options.maxSubscriptions) throw new Error('Subscription limit reached');
     if (!this.childSubs.has(path)) this.childSubs.set(path, new Set());
     this.childSubs.get(path)!.add(cb);
     return () => {
@@ -49,6 +67,28 @@ export class SubscriptionEngine {
     };
   }
 
+  /** Push a value directly to subscribers of a specific path + its ancestors. No DB involved. */
+  pushValue(path: string, value: unknown): void {
+    const valFn = () => value;
+    const now = Date.now();
+    const subs = this.valueSubs.get(path);
+    if (subs?.size) {
+      const snapshot = { path, val: valFn, updatedAt: now };
+      for (const cb of subs) { try { cb(snapshot); } catch {} }
+    }
+    // Walk ancestors by finding '/' separators (avoids split/slice/join allocations)
+    let idx = path.lastIndexOf('/');
+    while (idx > 0) {
+      const ancestor = path.substring(0, idx);
+      const asubs = this.valueSubs.get(ancestor);
+      if (asubs?.size) {
+        const snap = { path: ancestor, val: valFn, updatedAt: now };
+        for (const cb of asubs) { try { cb(snap); } catch {} }
+      }
+      idx = path.lastIndexOf('/', idx - 1);
+    }
+  }
+
   /**
    * Notify after a write.
    * @param changedPaths - all leaf paths that were written
@@ -56,56 +96,103 @@ export class SubscriptionEngine {
    * @param existedBefore - set of paths that existed before the write (for added/changed detection)
    */
   notify(changedPaths: string[], getFn: (path: string) => unknown, existedBefore?: Set<string>) {
-    const notified = new Set<string>();
+    // Value subscriptions — walk each leaf + ancestors using indexOf (no array alloc)
+    const notified = changedPaths.length > 1 ? new Set<string>() : null;
 
     for (const leafPath of changedPaths) {
-      const pathsToNotify = [leafPath, ...ancestors(leafPath)];
-
-      for (const p of pathsToNotify) {
-        if (notified.has(p)) continue;
-        notified.add(p);
-
-        const subs = this.valueSubs.get(p);
+      // Notify exact path
+      if (!notified || !notified.has(leafPath)) {
+        notified?.add(leafPath);
+        const subs = this.valueSubs.get(leafPath);
+        if (subs?.size) {
+          const snapshot = { path: leafPath, val: () => getFn(leafPath) };
+          for (const cb of subs) { try { cb(snapshot); } catch {} }
+        }
+      }
+      // Walk ancestors via lastIndexOf (no split/slice/join)
+      let idx = leafPath.lastIndexOf('/');
+      while (idx > 0) {
+        const ancestor = leafPath.substring(0, idx);
+        if (notified && notified.has(ancestor)) { idx = leafPath.lastIndexOf('/', idx - 1); continue; }
+        notified?.add(ancestor);
+        const subs = this.valueSubs.get(ancestor);
         if (subs?.size) {
-          const snapshot = { path: p, val: () => getFn(p) };
-          for (const cb of subs) cb(snapshot);
+          const snapshot = { path: ancestor, val: () => getFn(ancestor) };
+          for (const cb of subs) { try { cb(snapshot); } catch {} }
         }
+        idx = leafPath.lastIndexOf('/', idx - 1);
       }
     }
 
-    // Child events
-    const childNotified = new Set<string>();
-    for (const leafPath of changedPaths) {
-      const parts = leafPath.split('/');
-      if (parts.length < 2) continue;
+    // Child events — skip entirely when no child subs
+    if (!this.childSubs.size) return;
 
-      for (let i = 1; i < parts.length; i++) {
-        const parentPath = parts.slice(0, i).join('/');
-        const childKey = parts[i];
+    const childNotified = changedPaths.length > 1 ? new Set<string>() : null;
+    for (const leafPath of changedPaths) {
+      // Walk parent/child pairs via indexOf
+      let start = 0;
+      let slashIdx = leafPath.indexOf('/', start);
+      while (slashIdx !== -1) {
+        const parentPath = leafPath.substring(0, slashIdx);
+        const nextSlash = leafPath.indexOf('/', slashIdx + 1);
+        const childKey = nextSlash === -1 ? leafPath.substring(slashIdx + 1) : leafPath.substring(slashIdx + 1, nextSlash);
         const dedupKey = `${parentPath}/${childKey}`;
 
-        if (childNotified.has(dedupKey)) continue;
-        childNotified.add(dedupKey);
-
-        const subs = this.childSubs.get(parentPath);
-        if (subs?.size) {
-          const childPath = `${parentPath}/${childKey}`;
-          const val = getFn(childPath);
-          let type: 'added' | 'changed' | 'removed';
-          if (val === null) {
-            type = 'removed';
-          } else if (existedBefore && !existedBefore.has(childPath)) {
-            type = 'added';
-          } else {
-            type = 'changed';
+        if (!childNotified || !childNotified.has(dedupKey)) {
+          childNotified?.add(dedupKey);
+          const subs = this.childSubs.get(parentPath);
+          if (subs?.size) {
+            const childPath = dedupKey;
+            const val = getFn(childPath);
+            let type: 'added' | 'changed' | 'removed';
+            if (val === null) {
+              type = 'removed';
+            } else if (existedBefore && !existedBefore.has(childPath)) {
+              type = 'added';
+            } else {
+              type = 'changed';
+            }
+            const event = { type, key: childKey, path: childPath, val: () => val };
+            for (const cb of subs) { try { cb(event); } catch {} }
           }
-          const event = { type, key: childKey, path: childPath, val: () => val };
-          for (const cb of subs) cb(event);
         }
+        start = slashIdx + 1;
+        slashIdx = leafPath.indexOf('/', start);
       }
     }
   }
 
+  /** Queue notifications for async batched delivery. Coalesces multiple writes in same tick. */
+  queueNotify(changedPaths: string[], getFn: (path: string) => unknown, existedBefore?: Set<string>) {
+    if (!this.options.asyncNotify) {
+      return this.notify(changedPaths, getFn, existedBefore);
+    }
+    if (!this._pendingNotify) this._pendingNotify = new Set();
+    for (const p of changedPaths) this._pendingNotify.add(p);
+    this._pendingGetFn = getFn;
+    if (existedBefore) {
+      if (!this._pendingExisted) this._pendingExisted = new Set();
+      for (const p of existedBefore) this._pendingExisted.add(p);
+    }
+    if (!this._flushScheduled) {
+      this._flushScheduled = true;
+      queueMicrotask(() => this._flushNotify());
+    }
+  }
+
+  private _flushNotify() {
+    this._flushScheduled = false;
+    const paths = this._pendingNotify;
+    const getFn = this._pendingGetFn;
+    const existed = this._pendingExisted;
+    this._pendingNotify = null;
+    this._pendingGetFn = null;
+    this._pendingExisted = null;
+    if (paths && getFn) {
+      this.notify([...paths], getFn, existed ?? undefined);
+    }
+  }
+
   get size(): number {
     let count = 0;
     for (const s of this.valueSubs.values()) count += s.size;

package/src/server/Transport.ts

@@ -6,6 +6,7 @@ import { AUTH_PREFIX } from './KeyAuthEngine.ts';
 import type { ClientMessage } from '../shared/protocol.ts';
 import { Errors } from '../shared/errors.ts';
 import { normalizePath, pathKey } from '../shared/pathUtils.ts';
+import type { ComponentLogger } from '../shared/logger.ts';
 import { increment, serverTimestamp, arrayUnion, arrayRemove } from '../shared/transforms.ts';
 
 interface VfsTransfer {
@@ -31,20 +32,81 @@ export class TransportOptions {
   staticRoutes?: Record<string, string>;
   /** Custom REST routes checked before 404. Return null to fall through. */
   extraRoutes?: Record<string, (req: Request, url: URL) => Response | Promise<Response> | null>;
+  /** Maximum concurrent WebSocket connections (default 10000) */
+  maxConnections: number = 10000;
+  /** Maximum incoming WebSocket message size in bytes (default 1MB) */
+  maxMessageSize: number = 1_048_576;
+  /** Maximum subscriptions per WebSocket client (default 500) */
+  maxSubscriptionsPerClient: number = 500;
 }
 
 export class Transport {
   readonly options: TransportOptions;
   private server: Server | null = null;
   private _clients = new Set<ServerWebSocket<WsData>>();
+  /** Broadcast groups: path → Set of WS clients */
+  private _valueGroups = new Map<string, Set<ServerWebSocket<WsData>>>();
+  private _childGroups = new Map<string, Set<ServerWebSocket<WsData>>>();
+  /** DB unsub functions for broadcast groups */
+  private _groupUnsubs = new Map<string, () => void>();
+  private _log: ComponentLogger;
   get clientCount(): number { return this._clients.size; }
 
+  /** Send pre-serialized stats directly to subscribed WS clients, bypassing SubscriptionEngine. */
+  broadcastStats(data: unknown, updatedAt: number): void {
+    // Check both exact path and ancestor subscribers
+    const group = this._valueGroups.get('_admin/stats');
+    const adminGroup = this._valueGroups.get('_admin');
+    if (!group?.size && !adminGroup?.size) return;
+    const payload = JSON.stringify({ type: 'value', path: '_admin/stats', data, updatedAt });
+    if (group) for (const c of group) { try { c.send(payload); } catch {} }
+    if (adminGroup) for (const c of adminGroup) { try { c.send(payload); } catch {} }
+  }
+
   constructor(
     private db: BodDB,
     private rules: RulesEngine | null,
     options?: Partial<TransportOptions>,
   ) {
     this.options = { ...new TransportOptions(), ...options };
+    this._log = db.log.forComponent('transport');
+  }
+
+  /** Add a WS client to a broadcast group. Returns the per-client unsub function. */
+  private _addBroadcastSub(ws: ServerWebSocket<WsData>, path: string, event: 'value' | 'child'): () => void {
+    const groups = event === 'value' ? this._valueGroups : this._childGroups;
+    const unsubKey = `${event}:${path}`;
+
+    if (!groups.has(path)) {
+      groups.set(path, new Set());
+      const dbOff = event === 'value'
+        ? this.db.on(path, (snap) => {
+            const group = groups.get(path);
+            if (!group?.size) return;
+            const data = snap.val();
+            const updatedAt = snap.updatedAt ?? this.db.storage.getWithMeta(snap.path)?.updatedAt;
+            const payload = JSON.stringify({ type: 'value', path: snap.path, data, updatedAt });
+            for (const c of group) { try { c.send(payload); } catch {} }
+          })
+        : this.db.onChild(path, (ev) => {
+            const group = groups.get(path);
+            if (!group?.size) return;
+            const payload = JSON.stringify({ type: 'child', path, key: ev.key, data: ev.val(), event: ev.type });
+            for (const c of group) { try { c.send(payload); } catch {} }
+          });
+      this._groupUnsubs.set(unsubKey, dbOff);
+    }
+    groups.get(path)!.add(ws);
+
+    return () => {
+      const group = groups.get(path);
+      group?.delete(ws);
+      if (group?.size === 0) {
+        groups.delete(path);
+        this._groupUnsubs.get(unsubKey)?.();
+        this._groupUnsubs.delete(unsubKey);
+      }
+    };
   }
 
   private async extractAuth(req: Request): Promise<Record<string, unknown> | null> {
@@ -75,6 +137,8 @@ export class Transport {
       }
     }
 
+    if (this._log.isDebug) this._log.debug(`${req.method} ${url.pathname}`);
+
     // REST: GET /db/<path> → get
     if (req.method === 'GET' && url.pathname.startsWith('/db/')) {
       return (async () => {
@@ -255,7 +319,7 @@ export class Transport {
           return Response.json({ ok: true });
         }
 
-        return new Response('Method not allowed', { status: 405 });
+        return Response.json({ ok: false, error: 'Method not allowed', code: Errors.INTERNAL }, { status: 405 });
       })();
     }
 
@@ -275,16 +339,25 @@ export class Transport {
       }
     }
 
-    return new Response('Not Found', { status: 404 });
+    return Response.json({ ok: false, error: 'Not found', code: Errors.NOT_FOUND }, { status: 404 });
   }
 
   /** WebSocket handler config for Bun.serve() */
   get websocketConfig() {
     const self = this;
     return {
-      open(ws: ServerWebSocket<WsData>) { self._clients.add(ws); },
+      open(ws: ServerWebSocket<WsData>) {
+        if (self._clients.size >= self.options.maxConnections) {
+          ws.close(1008, 'At capacity');
+          self._log.warn(`Connection rejected: at capacity (${self.options.maxConnections})`);
+          return;
+        }
+        self._clients.add(ws);
+        self._log.debug(`Client connected (${self._clients.size} total)`);
+      },
       close(ws: ServerWebSocket<WsData>) {
         self._clients.delete(ws);
+        self._log.debug(`Client disconnected (${self._clients.size} total)`);
         for (const off of ws.data.valueSubs.values()) off();
         for (const off of ws.data.childSubs.values()) off();
         for (const off of ws.data.streamSubs.values()) off();
@@ -293,6 +366,11 @@ export class Transport {
         ws.data.streamSubs.clear();
       },
       async message(ws: ServerWebSocket<WsData>, raw: string | Buffer) {
+        const rawLen = typeof raw === 'string' ? Buffer.byteLength(raw) : raw.byteLength;
+        if (rawLen > self.options.maxMessageSize) {
+          ws.send(JSON.stringify({ id: '?', ok: false, error: 'Message too large', code: Errors.INTERNAL }));
+          return;
+        }
         let msg: ClientMessage;
         try {
           msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
@@ -303,7 +381,10 @@ export class Transport {
 
         const { id } = msg;
         const reply = (data: unknown, extra?: Record<string, unknown>) => ws.send(JSON.stringify({ id, ok: true, data, ...extra }));
-        const error = (err: string, code: string) => ws.send(JSON.stringify({ id, ok: false, error: err, code }));
+        const error = (err: string, code: string) => {
+          self._log.warn(`WS op=${msg.op} path=${(msg as any).path ?? '—'} → ${err}`);
+          ws.send(JSON.stringify({ id, ok: false, error: err, code }));
+        };
         // Block external writes to _auth/ prefix (only KeyAuthEngine may write)
         const guardAuthPrefix = (path: string) => {
           if (self.options.keyAuth && normalizePath(path).startsWith(AUTH_PREFIX)) {
@@ -394,21 +475,16 @@ export class Transport {
               if (self.rules && !self.rules.check('read', msg.path, ws.data.auth)) {
                 return error('Permission denied', Errors.PERMISSION_DENIED);
               }
+              if (ws.data.valueSubs.size + ws.data.childSubs.size >= self.options.maxSubscriptionsPerClient) {
+                return error('Per-client subscription limit reached', Errors.INTERNAL);
+              }
               const subKey = `${msg.event}:${msg.path}`;
               if (msg.event === 'value') {
                 if (ws.data.valueSubs.has(subKey)) return reply(null);
-                const off = self.db.on(msg.path, (snap) => {
-                  const meta = self.db.storage.getWithMeta(snap.path);
-                  ws.send(JSON.stringify({ type: 'value', path: snap.path, data: snap.val(), updatedAt: meta?.updatedAt }));
-                });
-                ws.data.valueSubs.set(subKey, off);
+                ws.data.valueSubs.set(subKey, self._addBroadcastSub(ws, msg.path, 'value'));
               } else if (msg.event === 'child') {
                 if (ws.data.childSubs.has(subKey)) return reply(null);
-                const subPath = msg.path;
-                const off = self.db.onChild(subPath, (event) => {
-                  ws.send(JSON.stringify({ type: 'child', path: subPath, key: event.key, data: event.val(), event: event.type }));
-                });
-                ws.data.childSubs.set(subKey, off);
+                ws.data.childSubs.set(subKey, self._addBroadcastSub(ws, msg.path, 'child'));
               }
               return reply(null);
             }
@@ -708,10 +784,14 @@ export class Transport {
             case 'auth-verify': {
               if (!self.options.keyAuth) return error('KeyAuth not configured', Errors.INTERNAL);
               const result = self.options.keyAuth.verify(msg.publicKey, msg.signature, msg.nonce);
-              if (!result) return error('Authentication failed', Errors.AUTH_REQUIRED);
+              if (!result) {
+                self._log.warn(`Auth failed for key ${msg.publicKey?.slice(0, 16)}…`);
+                return error('Authentication failed', Errors.AUTH_REQUIRED);
+              }
               // Also set ws auth context
               const ctx = self.options.keyAuth.validateToken(result.token);
               if (ctx) ws.data.auth = ctx as unknown as Record<string, unknown>;
+              self._log.info(`Auth succeeded: ${(ctx as any)?.fingerprint?.slice(0, 12) ?? 'unknown'}…`);
               return reply(result);
             }
             case 'auth-link-device': {
@@ -856,6 +936,20 @@ export class Transport {
               return reply(info);
             }
 
+            case 'batch-sub': {
+              let count = 0;
+              for (const sub of msg.subscriptions) {
+                if (self.rules && !self.rules.check('read', sub.path, ws.data.auth)) continue;
+                if (ws.data.valueSubs.size + ws.data.childSubs.size >= self.options.maxSubscriptionsPerClient) break;
+                const bSubKey = `${sub.event}:${sub.path}`;
+                const subsMap = sub.event === 'value' ? ws.data.valueSubs : ws.data.childSubs;
+                if (subsMap.has(bSubKey)) { count++; continue; }
+                subsMap.set(bSubKey, self._addBroadcastSub(ws, sub.path, sub.event as 'value' | 'child'));
+                count++;
+              }
+              return reply({ subscribed: count });
+            }
+
             case 'transform': {
               const { path: tPath, type, value: tVal } = msg as any;
               let sentinel: unknown;
@@ -887,11 +981,19 @@ export class Transport {
               return reply(summary);
             }
 
+            case 'admin-stats-toggle': {
+              const enable = msg.enabled;
+              if (enable) self.db.startStatsPublisher();
+              else self.db.stopStatsPublisher();
+              return reply({ enabled: self.db.statsEnabled });
+            }
+
             default:
               return error('Unknown operation', Errors.INTERNAL);
           }
         } catch (e: unknown) {
           const message = e instanceof Error ? e.message : 'Internal error';
+          self._log.error(`op=${msg.op} path=${msg.path ?? '—'} error: ${message}`);
           return error(message, Errors.INTERNAL);
         }
       },

package/src/shared/keyAuth.ts

@@ -119,10 +119,10 @@ const PBKDF2_ITERATIONS = 100_000;
 const PBKDF2_KEYLEN = 32; // 256 bits
 const PBKDF2_DIGEST = 'sha256';
 
-export function encryptPrivateKey(privateKeyDer: Uint8Array, password: string): { encrypted: string; salt: string; iv: string; authTag: string } {
+export function encryptPrivateKey(privateKeyDer: Uint8Array, password: string, iterations?: number): { encrypted: string; salt: string; iv: string; authTag: string } {
   const salt = randomBytes(16);
   const iv = randomBytes(12); // 96-bit for GCM
-  const derivedKey = pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
+  const derivedKey = pbkdf2Sync(password, salt, iterations ?? PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
   const cipher = createCipheriv('aes-256-gcm', derivedKey, iv);
   const encrypted = Buffer.concat([cipher.update(privateKeyDer), cipher.final()]);
   const authTag = cipher.getAuthTag();
@@ -134,8 +134,8 @@ export function encryptPrivateKey(privateKeyDer: Uint8Array, password: string):
   };
 }
 
-export function decryptPrivateKey(encrypted: string, salt: string, iv: string, authTag: string, password: string): Uint8Array {
-  const derivedKey = pbkdf2Sync(password, Buffer.from(salt, 'base64'), PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
+export function decryptPrivateKey(encrypted: string, salt: string, iv: string, authTag: string, password: string, iterations?: number): Uint8Array {
+  const derivedKey = pbkdf2Sync(password, Buffer.from(salt, 'base64'), iterations ?? PBKDF2_ITERATIONS, PBKDF2_KEYLEN, PBKDF2_DIGEST);
   const decipher = createDecipheriv('aes-256-gcm', derivedKey, Buffer.from(iv, 'base64'));
   decipher.setAuthTag(Buffer.from(authTag, 'base64'));
   const decrypted = Buffer.concat([decipher.update(Buffer.from(encrypted, 'base64')), decipher.final()]);

package/src/shared/logger.ts

@@ -0,0 +1,68 @@
+/**
+ * BodDB internal logger — config-driven, zero-dependency.
+ * Disabled by default. Enable via `log` option in BodDBOptions.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogConfig {
+  /** Enable logging (default: false) */
+  enabled?: boolean;
+  /** Minimum log level (default: 'info') */
+  level?: LogLevel;
+  /** Enable specific components: ['storage', 'transport', 'subs', 'replication', 'stats', 'keyauth'] or '*' for all */
+  components?: string[] | '*';
+}
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+export class Logger {
+  private enabled: boolean;
+  private minLevel: number;
+  private components: Set<string> | '*';
+  private _cache = new Map<string, ComponentLogger>();
+
+  constructor(config?: LogConfig) {
+    this.enabled = config?.enabled ?? false;
+    this.minLevel = LEVELS[config?.level ?? 'info'];
+    this.components = config?.components === '*' ? '*' : new Set(config?.components ?? []);
+  }
+
+  forComponent(name: string): ComponentLogger {
+    let cl = this._cache.get(name);
+    if (!cl) { cl = new ComponentLogger(this, name); this._cache.set(name, cl); }
+    return cl;
+  }
+
+  shouldLog(level: LogLevel, component: string): boolean {
+    if (!this.enabled) return false;
+    if (LEVELS[level] < this.minLevel) return false;
+    if (this.components !== '*' && !this.components.has(component)) return false;
+    return true;
+  }
+
+  log(level: LogLevel, component: string, msg: string, data?: unknown): void {
+    if (!this.shouldLog(level, component)) return;
+    const ts = new Date().toISOString().slice(11, 23);
+    const prefix = `[${ts}] [${level.toUpperCase()}] [${component}]`;
+    if (data !== undefined) {
+      console[level === 'debug' ? 'log' : level](prefix, msg, data);
+    } else {
+      console[level === 'debug' ? 'log' : level](prefix, msg);
+    }
+  }
+}
+
+export class ComponentLogger {
+  readonly isDebug: boolean;
+  constructor(private logger: Logger, private component: string) {
+    this.isDebug = logger.shouldLog('debug', component);
+  }
+  debug(msg: string, data?: unknown) { this.logger.log('debug', this.component, msg, data); }
+  info(msg: string, data?: unknown) { this.logger.log('info', this.component, msg, data); }
+  warn(msg: string, data?: unknown) { this.logger.log('warn', this.component, msg, data); }
+  error(msg: string, data?: unknown) { this.logger.log('error', this.component, msg, data); }
+}
+
+/** Global no-op logger (used when logging disabled) */
+export const noopLogger = new Logger();

package/src/shared/protocol.ts

@@ -65,7 +65,9 @@ export type ClientMessage =
   | { id: string; op: 'transform'; path: string; type: string; value?: unknown }
   | { id: string; op: 'set-ttl'; path: string; value: unknown; ttl: number }
   | { id: string; op: 'sweep' }
-  | { id: string; op: 'get-rules' };
+  | { id: string; op: 'get-rules' }
+  | { id: string; op: 'batch-sub'; subscriptions: Array<{ path: string; event: SubEvent }> }
+  | { id: string; op: 'admin-stats-toggle'; enabled: boolean };
 
 // Server → Client messages
 export type ServerMessage =