threadforge 0.1.1 → 0.2.1

package/src/plugins/index.js

@@ -1,1756 +0,0 @@
-/**
- * ThreadForge Built-in Plugins
- *
- *   import { redis, postgres, s3, cors, cron, realtime } from 'threadforge/plugins';
- */
-
-// ─── Redis ─────────────────────────────────────────────────
-
-export function redis(options = {}) {
-  const url = options.url ?? `redis://${options.host ?? "127.0.0.1"}:${options.port ?? 6379}/${options.db ?? 0}`;
-  const poolSize = Math.max(1, Math.min(options.poolSize ?? 2, 8));
-
-  return {
-    name: "redis",
-    version: "1.0.0",
-    inject: "redis",
-    validate() {
-      try {
-        new URL(url);
-      } catch {
-        throw new Error(`Invalid Redis URL: ${url}`);
-      }
-    },
-    env() {
-      // REL-C2: Sanitize URL before propagating to env — strip credentials
-      // to prevent exposure via /proc/<pid>/environ. The connect() function
-      // uses the original `url` variable from closure scope.
-      try {
-        const parsed = new URL(url);
-        parsed.username = '';
-        parsed.password = '';
-        return { FORGE_REDIS_URL: parsed.toString() };
-      } catch {
-        return { FORGE_REDIS_URL: url };
-      }
-    },
-
-    async connect(ctx) {
-      let RedisClient;
-      try {
-        RedisClient = (await import("ioredis")).default;
-      } catch {
-        // P16: Pool built-in Redis connections to avoid head-of-line blocking
-        if (poolSize <= 1) {
-          return _mkRedis(url, ctx);
-        }
-        return _mkRedisPool(url, ctx, poolSize);
-      }
-      // ioredis is available — connection errors should propagate
-      const c = new RedisClient(url, { keyPrefix: options.keyPrefix ?? "", maxRetriesPerRequest: 3, lazyConnect: true });
-      await c.connect();
-      return c;
-    },
-
-    async healthCheck(c) {
-      try {
-        return { status: (await c.ping()) === "PONG" ? "ok" : "degraded" };
-      } catch (e) {
-        return { status: "error", error: e.message };
-      }
-    },
-    async disconnect(c) {
-      await c.quit?.();
-    },
-    metrics(c) {
-      return { connected: c.status === "ready" ? 1 : 0 };
-    },
-    nginx() {
-      return options.commanderUI
-        ? {
-            locations: [
-              { path: "/admin/redis", config: "proxy_pass http://127.0.0.1:8081;\nproxy_set_header Host $host;" },
-            ],
-          }
-        : {};
-    },
-  };
-}
-
-/**
- * Convert a RESP value to a string if it's a Buffer.
- * Returns null unchanged. For ioredis API compatibility.
- * @internal
- */
-function _bufToStr(v) {
-  if (v === null || v === undefined) return v;
-  if (Buffer.isBuffer(v)) return v.toString('utf8');
-  return v;
-}
-
-/** @internal Exported for testing only */
-export async function _mkRedis(url, ctx) {
-  const net = await import("node:net");
-  const p = new URL(url);
-  const host = p.hostname || "127.0.0.1";
-  const port = parseInt(p.port || "6379", 10);
-  const MAX_REDIS_BUFFER = 16 * 1024 * 1024; // 16 MB
-  let socket,
-    connected = false,
-    rq = [],
-    bufChunks = [],
-    bufTotalLen = 0;
-
-  const CRLF = Buffer.from("\r\n");
-
-  // Reconnection state
-  let intentionalClose = false;
-  let reconnectAttempts = 0;
-  let reconnectTimer = null;
-  let subReconnectAttempts = 0;
-  let subReconnectTimer = null;
-  let subConnecting = null;
-  const MAX_RECONNECT_RETRIES = 10;
-  const BASE_RECONNECT_DELAY = 1000;
-  const MAX_RECONNECT_DELAY = 30000;
-
-  // C-PLUGIN-5: Helper to cleanly destroy socket and prevent leaks
-  function destroySocket() {
-    if (socket) {
-      socket.removeAllListeners();
-      socket.destroy();
-      socket = null;
-    }
-  }
-
-  function conn() {
-    return new Promise((ok, no) => {
-      // C-PLUGIN-5: Destroy previous socket before creating new one
-      destroySocket();
-      socket = net.connect({ host, port });
-      socket.on("connect", () => {
-        connected = true;
-        reconnectAttempts = 0;
-        ok();
-      });
-      socket.on("error", (err) => {
-        if (!connected) return no(err);
-        ctx.logger.warn(`Redis socket error: ${err.message}`);
-      });
-      socket.on("data", (d) => {
-        if (bufTotalLen + d.length > MAX_REDIS_BUFFER) {
-          socket.destroy(new Error('Redis response buffer overflow'));
-          return;
-        }
-        // P-7: Accumulate chunks in array, concat only when parsing needs contiguous buffer
-        bufChunks.push(d);
-        bufTotalLen += d.length;
-        flush();
-      });
-      socket.on("close", () => {
-        connected = false;
-        clientRef.status = "disconnected";
-        // Reject pending requests
-        const pending = rq.splice(0);
-        for (const r of pending) r.no(new Error("Redis connection closed"));
-        bufChunks = [];
-        bufTotalLen = 0;
-
-        if (intentionalClose) return;
-        scheduleReconnect();
-      });
-    });
-  }
-
-  function scheduleReconnect() {
-    if (reconnectTimer !== null) return; // Already reconnecting
-    if (reconnectAttempts >= MAX_RECONNECT_RETRIES) {
-      ctx.logger.error(`Redis reconnect failed after ${MAX_RECONNECT_RETRIES} attempts, giving up`);
-      clientRef.status = 'disconnected';
-      // M-PLUGIN-4: Reject all pending requests on reconnect exhaustion
-      const pending = rq.splice(0);
-      for (const r of pending) r.no(new Error('Redis reconnect failed'));
-      // C-PLUGIN-5: Clean up socket
-      destroySocket();
-      return;
-    }
-    const delay = Math.min(BASE_RECONNECT_DELAY * 2 ** reconnectAttempts, MAX_RECONNECT_DELAY);
-    reconnectAttempts++;
-    ctx.logger.warn(`Redis reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_RETRIES})`);
-    reconnectTimer = setTimeout(async () => {
-      reconnectTimer = null;
-      try {
-        await conn();
-        // Re-authenticate and select DB after reconnect
-        if (p.password) await cmd("AUTH", p.password);
-        const db = parseInt(p.pathname?.slice(1) || "0", 10);
-        if (db > 0) await cmd("SELECT", String(db));
-        clientRef.status = "ready";
-        ctx.logger.info("Redis reconnected (built-in client)", { host, port });
-      } catch (err) {
-        ctx.logger.warn(`Redis reconnect attempt ${reconnectAttempts} failed: ${err.message}`);
-        scheduleReconnect();
-      }
-    }, delay);
-  }
-
-  const MAX_NEST_DEPTH = 32;
-  const MAX_RESP_ARRAY = 10_000;
-  const MAX_RESP_BULK = 16 * 1024 * 1024; // 16MB
-
-  function flush() {
-    // P-7: Concat accumulated chunks into a single buffer for parsing
-    if (bufChunks.length === 0 || rq.length === 0) return;
-    let buf = bufChunks.length === 1 ? bufChunks[0] : Buffer.concat(bufChunks, bufTotalLen);
-    bufChunks = [];
-    bufTotalLen = 0;
-    while (buf.length && rq.length) {
-      let r;
-      try {
-        r = parse(buf, 0);
-      } catch (err) {
-        // Unknown RESP type or parse error — reject current request and reset buffer
-        rq.shift().no(err);
-        return;
-      }
-      if (!r) break;
-      buf = r.rem;
-      rq.shift().ok(r.val);
-    }
-    // Keep remaining unparsed data for next flush
-    if (buf.length > 0) {
-      bufChunks.push(buf);
-      bufTotalLen = buf.length;
-    }
-  }
-  function parse(d, depth) {
-    if (!d.length) return null;
-    if (depth > MAX_NEST_DEPTH) {
-      throw new Error('RESP array nesting too deep');
-    }
-    const t = d[0]; // byte value: '+' = 43, '-' = 45, ':' = 58, '$' = 36, '*' = 42
-    const nl = d.indexOf(CRLF[0]); // find \r
-    if (nl === -1 || nl + 1 >= d.length || d[nl + 1] !== CRLF[1]) return null;
-    const line = d.slice(1, nl).toString("utf8");
-    const afterCrlf = d.slice(nl + 2);
-    // Simple string
-    if (t === 0x2b) return { val: line, rem: afterCrlf };
-    // Error
-    if (t === 0x2d) return { val: new Error(line), rem: afterCrlf };
-    // Integer
-    if (t === 0x3a) return { val: parseInt(line, 10), rem: afterCrlf };
-    // Bulk string — payload is raw Buffer
-    if (t === 0x24) {
-      const len = parseInt(line, 10);
-      if (len < -1 || len > MAX_RESP_BULK) {
-        throw new Error(`RESP bulk string length out of bounds: ${len}`);
-      }
-      if (len === -1) return { val: null, rem: afterCrlf };
-      // Need len bytes + \r\n after the data
-      if (afterCrlf.length < len + 2) return null;
-      const val = Buffer.from(afterCrlf.subarray(0, len));
-      return { val, rem: afterCrlf.subarray(len + 2) };
-    }
-    // Array
-    if (t === 0x2a) {
-      const cnt = parseInt(line, 10);
-      if (cnt < -1 || cnt > MAX_RESP_ARRAY) {
-        throw new Error(`RESP array count out of bounds: ${cnt}`);
-      }
-      if (cnt === -1) return { val: null, rem: afterCrlf };
-      let rm = afterCrlf;
-      const a = [];
-      let totalArraySize = 0;
-      for (let i = 0; i < cnt; i++) {
-        const it = parse(rm, depth + 1);
-        if (!it) return null;
-        // Track total array element sizes
-        if (Buffer.isBuffer(it.val)) {
-          totalArraySize += it.val.length;
-          if (totalArraySize > MAX_RESP_BULK) {
-            throw new Error(`RESP array total size exceeds limit: ${totalArraySize}`);
-          }
-        }
-        a.push(it.val);
-        rm = it.rem;
-      }
-      return { val: a, rem: rm };
-    }
-    const err = new Error(`Unknown RESP type: '${String.fromCharCode(t)}' (0x${t.toString(16)})`);
-    err.code = 'RESP_PARSE_ERROR';
-    throw err;
-  }
-  function cmd(...args) {
-    return new Promise((ok, no) => {
-      if (!connected) return no(new Error("Redis not connected"));
-      // H-PLUGIN-4: Reject arguments containing CR/LF (command injection)
-      for (const a of args) {
-        if (!Buffer.isBuffer(a) && typeof a === 'string' && (/\r|\n/).test(a)) {
-          return no(new Error('Redis command argument contains invalid characters (CR/LF)'));
-        }
-      }
-      const header = `*${args.length}\r\n`;
-      const parts = [header];
-      for (const a of args) {
-        if (Buffer.isBuffer(a)) {
-          parts.push(`$${a.length}\r\n`);
-          parts.push(a);
-          parts.push('\r\n');
-        } else {
-          const s = String(a);
-          parts.push(`$${Buffer.byteLength(s)}\r\n${s}\r\n`);
-        }
-      }
-      rq.push({ ok, no });
-      socket.cork();
-      for (const part of parts) {
-        socket.write(part);
-      }
-      socket.uncork();
-    });
-  }
-
-  await conn();
-  if (p.password) await cmd("AUTH", p.password);
-  const db = parseInt(p.pathname?.slice(1) || "0", 10);
-  if (db > 0) await cmd("SELECT", String(db));
-  ctx.logger.info("Redis connected (built-in client)", { host, port });
-
-  const clientRef = {
-    status: "ready",
-    get: async (k) => _bufToStr(await cmd("GET", k)),
-    set: (...a) => cmd("SET", ...a),
-    del: (...k) => cmd("DEL", ...k),
-    hget: async (k, f) => _bufToStr(await cmd("HGET", k, f)),
-    hset: (k, f, v) => cmd("HSET", k, f, v),
-    hgetall: async (k) => {
-      const a = await cmd("HGETALL", k);
-      if (!Array.isArray(a)) return {};
-      const o = {};
-      for (let i = 0; i < a.length; i += 2) o[_bufToStr(a[i])] = _bufToStr(a[i + 1]);
-      return o;
-    },
-    keys: async (pat) => {
-      const a = await cmd("KEYS", pat);
-      return Array.isArray(a) ? a.map(_bufToStr) : a;
-    },
-    expire: (k, s) => cmd("EXPIRE", k, s),
-    ttl: (k) => cmd("TTL", k),
-    ping: () => cmd("PING"),
-    incr: (k) => cmd("INCR", k),
-    decr: (k) => cmd("DECR", k),
-    lpush: (k, ...v) => cmd("LPUSH", k, ...v),
-    rpush: (k, ...v) => cmd("RPUSH", k, ...v),
-    lrange: async (k, s, e) => {
-      const a = await cmd("LRANGE", k, String(s), String(e));
-      return Array.isArray(a) ? a.map(_bufToStr) : a;
-    },
-    sadd: (k, ...m) => cmd("SADD", k, ...m),
-    smembers: async (k) => {
-      const a = await cmd("SMEMBERS", k);
-      return Array.isArray(a) ? a.map(_bufToStr) : a;
-    },
-    publish: (ch, m) => cmd("PUBLISH", ch, m),
-
-    // ─── Subscription support (lazy separate connection) ───
-    _subSocket: null,
-    _subConnected: false,
-    _subBufChunks: [],
-    _subBufTotalLen: 0,
-    _subCallbacks: new Map(),    // channel → Set<callback>
-    _psubCallbacks: new Map(),   // pattern → Set<callback>
-    _subSubscribedChannels: new Set(),
-    _subSubscribedPatterns: new Set(),
-    _subRq: [],
-
-    async _ensureSubConnection() {
-      if (this._subConnected) return;
-      if (subConnecting) return subConnecting;
-      const self = this;
-      const subNet = await import("node:net");
-      subConnecting = new Promise((ok, no) => {
-        self._subSocket = subNet.connect({ host, port });
-        self._subSocket.on("connect", () => {
-          self._subConnected = true;
-          subReconnectAttempts = 0;
-          self._subSubscribedChannels.clear();
-          self._subSubscribedPatterns.clear();
-          ok();
-        });
-        self._subSocket.on("error", (err) => {
-          if (!self._subConnected) return no(err);
-          ctx.logger.warn(`Redis sub socket error: ${err.message}`);
-        });
-        self._subSocket.on("data", (d) => {
-          // REL-C1: Guard against unbounded sub buffer growth (same limit as main connection)
-          if (self._subBufTotalLen + d.length > MAX_REDIS_BUFFER) {
-            self._subSocket.destroy(new Error('Redis sub response buffer overflow'));
-            return;
-          }
-          // P-8: Chunk-list pattern to avoid O(n^2) Buffer.concat
-          self._subBufChunks.push(d);
-          self._subBufTotalLen += d.length;
-          self._flushSub();
-        });
-        self._subSocket.on("close", () => {
-          self._subConnected = false;
-          self._subSubscribedChannels.clear();
-          self._subSubscribedPatterns.clear();
-          const pending = self._subRq.splice(0);
-          for (const r of pending) r.no(new Error("Redis sub connection closed"));
-          self._subBufChunks = [];
-          self._subBufTotalLen = 0;
-          self._scheduleSubReconnect();
-        });
-      });
-      let connectError = null;
-      try {
-        await subConnecting;
-        // Auth and DB select on sub connection
-        if (p.password) {
-          await self._subCmd("AUTH", p.password);
-        }
-        const subDb = parseInt(p.pathname?.slice(1) || "0", 10);
-        if (subDb > 0) {
-          await self._subCmd("SELECT", String(subDb));
-        }
-        // Re-subscribe desired channels/patterns after reconnect.
-        for (const channel of self._subCallbacks.keys()) {
-          if (self._subSubscribedChannels.has(channel)) continue;
-          await self._subCmd("SUBSCRIBE", channel);
-          self._subSubscribedChannels.add(channel);
-        }
-        for (const pattern of self._psubCallbacks.keys()) {
-          if (self._subSubscribedPatterns.has(pattern)) continue;
-          await self._subCmd("PSUBSCRIBE", pattern);
-          self._subSubscribedPatterns.add(pattern);
-        }
-      } catch (err) {
-        connectError = err;
-      } finally {
-        subConnecting = null;
-      }
-      if (connectError) {
-        this._scheduleSubReconnect();
-        throw connectError;
-      }
-    },
-
-    _scheduleSubReconnect() {
-      if (intentionalClose) return;
-      if (subReconnectTimer !== null || this._subConnected || subConnecting) return;
-      if (subReconnectAttempts >= MAX_RECONNECT_RETRIES) {
-        ctx.logger.error(`Redis sub reconnect failed after ${MAX_RECONNECT_RETRIES} attempts, giving up`);
-        return;
-      }
-      const delay = Math.min(BASE_RECONNECT_DELAY * 2 ** subReconnectAttempts, MAX_RECONNECT_DELAY);
-      subReconnectAttempts++;
-      ctx.logger.warn(
-        `Redis sub reconnecting in ${delay}ms (attempt ${subReconnectAttempts}/${MAX_RECONNECT_RETRIES})`,
-      );
-      subReconnectTimer = setTimeout(async () => {
-        subReconnectTimer = null;
-        try {
-          await this._ensureSubConnection();
-          ctx.logger.info("Redis sub reconnected (built-in client)", { host, port });
-        } catch (err) {
-          ctx.logger.warn(`Redis sub reconnect attempt ${subReconnectAttempts} failed: ${err.message}`);
-          this._scheduleSubReconnect();
-        }
-      }, delay);
-      subReconnectTimer.unref?.();
-    },
-
-    _subCmd(...args) {
-      return new Promise((ok, no) => {
-        if (!this._subConnected) return no(new Error("Redis sub not connected"));
-        const header = `*${args.length}\r\n`;
-        const parts = [header];
-        for (const a of args) {
-          const s = String(a);
-          parts.push(`$${Buffer.byteLength(s)}\r\n${s}\r\n`);
-        }
-        this._subRq.push({ ok, no });
-        this._subSocket.cork();
-        for (const part of parts) this._subSocket.write(part);
-        this._subSocket.uncork();
-      });
-    },
-
-    _flushSub() {
-      // P-8: Concat accumulated chunks for parsing
-      if (this._subBufChunks.length === 0) return;
-      let buf = this._subBufChunks.length === 1 ? this._subBufChunks[0] : Buffer.concat(this._subBufChunks, this._subBufTotalLen);
-      this._subBufChunks = [];
-      this._subBufTotalLen = 0;
-      while (buf.length) {
-        let r;
-        try {
-          r = parse(buf, 0);
-        } catch {
-          return;
-        }
-        if (!r) break;
-        buf = r.rem;
-        const val = r.val;
-        // Messages are arrays: ["message", channel, data] or ["pmessage", pattern, channel, data]
-        if (Array.isArray(val)) {
-          const type = _bufToStr(val[0]);
-          if (type === 'message') {
-            const ch = _bufToStr(val[1]);
-            const data = _bufToStr(val[2]);
-            const cbs = this._subCallbacks.get(ch);
-            if (cbs) for (const cb of cbs) cb(data, ch);
-            continue;
-          }
-          if (type === 'pmessage') {
-            const pat = _bufToStr(val[1]);
-            const ch = _bufToStr(val[2]);
-            const data = _bufToStr(val[3]);
-            const cbs = this._psubCallbacks.get(pat);
-            if (cbs) for (const cb of cbs) cb(data, ch, pat);
-            continue;
-          }
-          // subscribe/psubscribe confirmations resolve pending _subRq
-          if (type === 'subscribe' || type === 'psubscribe') {
-            if (this._subRq.length) this._subRq.shift().ok(val);
-            continue;
-          }
-          // unsubscribe/punsubscribe
-          if (type === 'unsubscribe' || type === 'punsubscribe') {
-            if (this._subRq.length) this._subRq.shift().ok(val);
-            continue;
-          }
-        }
-        // Other responses (OK from AUTH/SELECT)
-        if (this._subRq.length) this._subRq.shift().ok(val);
-      }
-      // Keep remaining unparsed data for next flush
-      if (buf.length > 0) {
-        this._subBufChunks.push(buf);
-        this._subBufTotalLen = buf.length;
-      }
-    },
-
-    async subscribe(channel, callback) {
-      if (!this._subCallbacks.has(channel)) {
-        this._subCallbacks.set(channel, new Set());
-      }
-      this._subCallbacks.get(channel).add(callback);
-      await this._ensureSubConnection();
-      if (!this._subSubscribedChannels.has(channel)) {
-        await this._subCmd("SUBSCRIBE", channel);
-        this._subSubscribedChannels.add(channel);
-      }
-    },
-
-    async psubscribe(pattern, callback) {
-      if (!this._psubCallbacks.has(pattern)) {
-        this._psubCallbacks.set(pattern, new Set());
-      }
-      this._psubCallbacks.get(pattern).add(callback);
-      await this._ensureSubConnection();
-      if (!this._subSubscribedPatterns.has(pattern)) {
-        await this._subCmd("PSUBSCRIBE", pattern);
-        this._subSubscribedPatterns.add(pattern);
-      }
-    },
-
-    quit: () => {
-      if (intentionalClose) return Promise.resolve(); // Guard against double-call
-      // Clean up subscription connection
-      if (clientRef._subSocket) {
-        clientRef._subSocket.removeAllListeners();
-        clientRef._subSocket.destroy();
-        clientRef._subSocket = null;
-        clientRef._subConnected = false;
-        clientRef._subCallbacks.clear();
-        clientRef._psubCallbacks.clear();
-        clientRef._subSubscribedChannels.clear();
-        clientRef._subSubscribedPatterns.clear();
-        clientRef._subBufChunks = [];
-        clientRef._subBufTotalLen = 0;
-        clientRef._subRq.length = 0;
-      }
-      return new Promise((resolve) => {
-        intentionalClose = true;
-        if (reconnectTimer) {
-          clearTimeout(reconnectTimer);
-          reconnectTimer = null;
-        }
-        if (subReconnectTimer) {
-          clearTimeout(subReconnectTimer);
-          subReconnectTimer = null;
-        }
-        if (rq.length === 0) {
-          connected = false;
-          // C-PLUGIN-5: Clean socket shutdown on intentional close
-          destroySocket();
-          resolve();
-          return;
-        }
-        // Event-based drain: resolve when response queue empties
-        const origFlush = flush;
-        flush = function drainFlush() {
-          origFlush();
-          if (rq.length === 0) {
-            flush = origFlush;
-            connected = false;
-            destroySocket();
-            resolve();
-          }
-        };
-        // Safety timeout in case drain never completes
-        setTimeout(() => {
-          flush = origFlush;
-          // Reject all pending requests
-          const pending = rq.splice(0);
-          for (const r of pending) {
-            r.no(new Error('Redis quit timeout - connection forcibly closed'));
-          }
-          connected = false;
-          destroySocket();
-          resolve();
-        }, 5000).unref();
-      });
-    },
-    disconnect: () => {
-      intentionalClose = true;
-      connected = false;
-      if (reconnectTimer) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
-      if (subReconnectTimer) {
-        clearTimeout(subReconnectTimer);
-        subReconnectTimer = null;
-      }
-      // C-PLUGIN-5: Use destroySocket helper
-      destroySocket();
-    },
-  };
-  return clientRef;
-}
-
-/**
- * P16: Redis connection pool for the built-in RESP client.
- * Maintains multiple connections and round-robins commands across them
- * to avoid head-of-line blocking on a single connection.
- * @internal
- */
-async function _mkRedisPool(url, ctx, size) {
-  const connections = [];
-  for (let i = 0; i < size; i++) {
-    connections.push(await _mkRedis(url, ctx));
-  }
-  let rrIndex = 0;
-
-  function nextConn() {
-    const conn = connections[rrIndex % connections.length];
-    rrIndex = (rrIndex + 1) % 1_000_000_000;
-    return conn;
-  }
-
-  // Build a pooled client that delegates to underlying connections round-robin
-  const pooled = {
-    status: "ready",
-    get _poolConnections() { return connections; },
-    get: (k) => nextConn().get(k),
-    set: (...a) => nextConn().set(...a),
-    del: (...k) => nextConn().del(...k),
-    hget: (k, f) => nextConn().hget(k, f),
-    hset: (k, f, v) => nextConn().hset(k, f, v),
-    hgetall: (k) => nextConn().hgetall(k),
-    keys: (pat) => nextConn().keys(pat),
-    expire: (k, s) => nextConn().expire(k, s),
-    ttl: (k) => nextConn().ttl(k),
-    ping: () => nextConn().ping(),
-    incr: (k) => nextConn().incr(k),
-    decr: (k) => nextConn().decr(k),
-    lpush: (k, ...v) => nextConn().lpush(k, ...v),
-    rpush: (k, ...v) => nextConn().rpush(k, ...v),
-    lrange: (k, s, e) => nextConn().lrange(k, s, e),
-    sadd: (k, ...m) => nextConn().sadd(k, ...m),
-    smembers: (k) => nextConn().smembers(k),
-    publish: (ch, m) => nextConn().publish(ch, m),
-    // Subscriptions use the first connection's sub support
-    subscribe: (ch, cb) => connections[0].subscribe(ch, cb),
-    psubscribe: (pat, cb) => connections[0].psubscribe(pat, cb),
-    quit: async () => {
-      pooled.status = "disconnected";
-      await Promise.all(connections.map(c => c.quit()));
-    },
-    disconnect: () => {
-      pooled.status = "disconnected";
-      for (const c of connections) c.disconnect();
-    },
-  };
-  ctx.logger.info(`Redis pool created (${size} connections)`, { host: new URL(url).hostname });
-  return pooled;
-}
-
-// ─── PostgreSQL ────────────────────────────────────────────
-
-export function postgres(options = {}) {
-  const url = options.url ?? process.env.DATABASE_URL;
-  return {
-    name: "postgres",
-    version: "1.0.0",
-    inject: "pg",
-    validate() {
-      if (!url && !process.env.DATABASE_URL) throw new Error("PostgreSQL plugin requires url or DATABASE_URL");
-    },
-    env() {
-      return url ? { FORGE_PG_URL: url } : {};
-    },
-    async connect(ctx) {
-      const pg = await import("pg");
-      const Pool = pg.default?.Pool ?? pg.Pool;
-      const poolMax = options.poolSize ?? 10;
-      const pool = new Pool({
-        connectionString: url ?? process.env.FORGE_PG_URL,
-        max: poolMax,
-        idleTimeoutMillis: options.idleTimeout ?? 30000,
-        connectionTimeoutMillis: 10000,
-        statement_timeout: 30000,
-      });
-      const c = await pool.connect();
-      c.release();
-      ctx.logger.info("PostgreSQL connected", { pool: poolMax });
-
-      // H-PLUGIN-1: Pool saturation logging (max once per 60s)
-      let _lastSaturationWarn = 0;
-      const origQuery = pool.query.bind(pool);
-      pool.query = function (...args) {
-        const now = Date.now();
-        if (now - _lastSaturationWarn > 60000) {
-          if (pool.waitingCount > 0 || pool.idleCount < poolMax * 0.2) {
-            _lastSaturationWarn = now;
-            ctx.logger.warn('PostgreSQL pool saturation warning', {
-              waiting: pool.waitingCount,
-              idle: pool.idleCount,
-              total: pool.totalCount,
-              max: poolMax,
-            });
-          }
-        }
-        return origQuery(...args);
-      };
-
-      return pool;
-    },
-    async healthCheck(pool) {
-      try {
-        await pool.query("SELECT 1");
-        return { status: "ok", total: pool.totalCount, idle: pool.idleCount };
-      } catch (e) {
-        return { status: "error", error: e.message };
-      }
-    },
-    async disconnect(pool) {
-      await pool.end();
-    },
-    metrics(pool) {
-      return { pool_total: pool.totalCount ?? 0, pool_idle: pool.idleCount ?? 0, pool_waiting: pool.waitingCount ?? 0 };
-    },
-    nginx() {
-      return options.pgAdminUI
-        ? {
-            locations: [
-              {
-                path: "/admin/pgadmin",
-                config: `proxy_pass http://127.0.0.1:${options.pgAdminPort ?? 5050};\nproxy_set_header Host $host;`,
-              },
-            ],
-          }
-        : {};
-    },
-  };
-}
-
-// ─── S3 ────────────────────────────────────────────────────
-
-// H-PLUGIN-8: S3 key validation helper
-function validateS3Key(key) {
-  if (typeof key !== 'string') throw new Error('S3 key must be a string');
-  if (key.length < 1 || key.length > 1024) throw new Error(`S3 key length out of bounds: ${key.length}`);
-  if (key.includes('..')) throw new Error('S3 key must not contain ".."');
-  if (key.startsWith('/')) throw new Error('S3 key must not start with "/"');
-  if (/[\x00-\x1F\x7F]/.test(key)) throw new Error('S3 key must not contain control characters');
-}
-
-const MAX_STUB_SIZE = 100 * 1024 * 1024; // 100MB total
-const MAX_FILE_SIZE = 10 * 1024 * 1024;  // 10MB per file
-
-export function s3(options = {}) {
-  return {
-    name: "s3",
-    version: "1.0.0",
-    inject: "storage",
-    validate() {
-      if (!options.bucket) throw new Error("S3 plugin requires bucket");
-    },
-    env() {
-      const e = {};
-      if (options.endpoint) e.FORGE_S3_ENDPOINT = options.endpoint;
-      if (options.region) e.AWS_REGION = options.region;
-      return e;
-    },
-    async connect(ctx) {
-      try {
-        const { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, HeadBucketCommand } = await import(
-          "@aws-sdk/client-s3"
-        );
-        const cfg = { region: options.region ?? "us-east-1" };
-        if (options.endpoint) {
-          cfg.endpoint = options.endpoint;
-          cfg.forcePathStyle = true;
-        }
-        const raw = new S3Client(cfg);
-        const bucket = options.bucket;
-        ctx.logger.info("S3 connected", { bucket, region: cfg.region });
-        return {
-          _isStub: false,
-          _raw: raw,
-          _HeadBucketCommand: HeadBucketCommand,
-          put: (k, b, ct) => { validateS3Key(k); return raw.send(new PutObjectCommand({ Bucket: bucket, Key: k, Body: b, ContentType: ct })); },
-          get: async (k) => { validateS3Key(k); return (await raw.send(new GetObjectCommand({ Bucket: bucket, Key: k }))).Body; },
-          del: (k) => { validateS3Key(k); return raw.send(new DeleteObjectCommand({ Bucket: bucket, Key: k })); },
-          url: (k) => {
-            validateS3Key(k);
-            return options.endpoint
-              ? `${options.endpoint}/${bucket}/${k}`
-              : `https://${bucket}.s3.${cfg.region}.amazonaws.com/${k}`;
-          },
-          bucket,
-        };
-      } catch {
-        const store = new Map();
-        let totalSize = 0;
-        ctx.logger.warn("S3 stub active (install @aws-sdk/client-s3)");
-        return {
-          _isStub: true,
-          put: async (k, b) => {
-            validateS3Key(k);
-            const size = Buffer.isBuffer(b) ? b.length : (typeof b === 'string' ? Buffer.byteLength(b) : 0);
-            if (size > MAX_FILE_SIZE) throw new Error(`S3 stub: file size ${size} exceeds limit of ${MAX_FILE_SIZE}`);
-            // Subtract old value size if overwriting
-            const old = store.get(k);
-            if (old !== undefined) {
-              const oldSize = Buffer.isBuffer(old) ? old.length : (typeof old === 'string' ? Buffer.byteLength(old) : 0);
-              totalSize -= oldSize;
-            }
-            if (totalSize + size > MAX_STUB_SIZE) throw new Error(`S3 stub: total size would exceed limit of ${MAX_STUB_SIZE}`);
-            totalSize += size;
-            store.set(k, b);
-          },
-          get: async (k) => { validateS3Key(k); return store.get(k) ?? null; },
-          del: async (k) => {
-            validateS3Key(k);
-            const old = store.get(k);
-            if (old !== undefined) {
-              const oldSize = Buffer.isBuffer(old) ? old.length : (typeof old === 'string' ? Buffer.byteLength(old) : 0);
-              totalSize -= oldSize;
-            }
-            store.delete(k);
-          },
-          url: (k) => { validateS3Key(k); return `mem://${options.bucket}/${k}`; },
-          bucket: options.bucket,
-        };
-      }
-    },
-    async healthCheck(s) {
-      if (s._isStub === true) return { status: "ok", bucket: s.bucket, note: "in-memory stub" };
-      if (s._isStub === false && s._raw && s._HeadBucketCommand) {
-        try {
-          await s._raw.send(new s._HeadBucketCommand({ Bucket: s.bucket }));
-          return { status: "ok", bucket: s.bucket };
-        } catch (err) {
-          return { status: "error", bucket: s.bucket, error: err.message };
-        }
-      }
-      // Fallback for clients not created by connect() (e.g., in tests)
-      return { status: "ok", bucket: s.bucket };
-    },
-    async disconnect() {},
-  };
-}
-
-// ─── CORS ──────────────────────────────────────────────────
-
-export function cors(options = {}) {
-  const origins = options.origins ?? ["*"];
-  const methods = options.methods ?? ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
-  const headers = options.headers ?? ["Content-Type", "Authorization", "X-Correlation-ID"];
-  const creds = options.credentials ?? false;
-  const maxAge = options.maxAge ?? 86400;
-
-  if (origins.includes("*") && creds) {
-    throw new Error(
-      'CORS misconfiguration: credentials: true is incompatible with origins: ["*"]. ' +
-      "Specify explicit origins or disable credentials."
-    );
-  }
-
-  return {
-    name: "cors",
-    version: "1.0.0",
-    inject: "_cors",
-    async connect() {
-      return { origins, methods, headers };
-    },
-    middleware() {
-      return function corsMiddleware(req, res, next) {
-        const origin = req.headers.origin;
-        let matched = false;
-
-        if (origins.includes("*") && !creds) {
-          res.setHeader("Access-Control-Allow-Origin", "*");
-          matched = true;
-        } else if (origin) {
-          // Check exact match first
-          if (origins.includes(origin)) {
-            matched = true;
-          } else {
-            // Check wildcard subdomain patterns (e.g., *.example.com)
-            for (const allowed of origins) {
-              if (allowed.startsWith("*.")) {
-                const suffix = allowed.slice(1); // e.g., ".example.com"
-                try {
-                  const originHost = new URL(origin).hostname.toLowerCase();
-                  // REL-C3: *.example.com should NOT match bare example.com — wildcard
-                  // requires at least one subdomain level. This is the standard interpretation
-                  // per RFC 6125 and browser SAN matching.
-                  if (originHost.endsWith(suffix)) {
-                    // Verify the part before suffix is a valid non-empty subdomain segment
-                    const beforeSuffix = originHost.slice(0, -suffix.length);
-                    if (beforeSuffix && /^[a-z0-9]([a-z0-9-]*\.)*$/.test(beforeSuffix)) {
-                      matched = true;
-                      break;
-                    }
-                  }
-                } catch {
-                  // Invalid origin URL, skip
-                }
-              }
-            }
-          }
-          if (matched) {
-            res.setHeader("Access-Control-Allow-Origin", origin);
-            if (creds) res.setHeader("Access-Control-Allow-Credentials", "true");
-          }
-        }
-
-        if (matched) {
-          res.setHeader("Access-Control-Allow-Methods", methods.join(", "));
-          res.setHeader("Access-Control-Allow-Headers", headers.join(", "));
-          // M-PLUGIN-3: Expose correlation and custom response headers to frontend JS
-          res.setHeader("Access-Control-Expose-Headers", "X-Correlation-ID, X-Request-ID, X-Trace-ID");
-          res.setHeader("Access-Control-Max-Age", String(maxAge));
-          res.setHeader("Vary", "Origin");
-        }
-
-        if (req.method === "OPTIONS") {
-          if (!matched) {
-            res.writeHead(403);
-            res.end();
-            return;
-          }
-          res.writeHead(204);
-          res.end();
-          return;
-        }
-        next();
-      };
-    },
-    async disconnect() {},
-  };
-}
-
-// ─── Realtime (WebSocket Utilities) ────────────────────────
-
-const REALTIME_CHANNEL_RE = /^[a-zA-Z0-9:_-]{1,128}$/;
-const REALTIME_BACKPRESSURE_STRATEGIES = new Set(["drop", "close"]);
-
-function _assertRealtimeChannel(channel, allowedChannels) {
-  if (typeof channel !== "string" || channel.trim() === "") {
-    throw new Error("Realtime channel must be a non-empty string");
-  }
-  if (!REALTIME_CHANNEL_RE.test(channel)) {
-    throw new Error(`Invalid realtime channel "${channel}". Use [a-zA-Z0-9:_-] (max 128 chars)`);
-  }
-  if (allowedChannels && allowedChannels.size > 0 && !allowedChannels.has(channel)) {
-    throw new Error(`Realtime channel "${channel}" is not in allowedChannels`);
-  }
-}
-
-function _encodeRealtimeEnvelope(channel, payload, senderId, maxPayloadBytes) {
-  let type = "text";
-  let body = "";
-
-  if (Buffer.isBuffer(payload)) {
-    type = "base64";
-    body = payload.toString("base64");
-  } else if (typeof payload === "string") {
-    type = "text";
-    body = payload;
-  } else {
-    type = "json";
-    body = JSON.stringify(payload);
-  }
-
-  const size = Buffer.byteLength(body);
-  if (size > maxPayloadBytes) {
-    throw new Error(`Realtime payload exceeds maxPayloadBytes (${maxPayloadBytes})`);
-  }
-
-  return {
-    v: 1,
-    senderId,
-    channel,
-    type,
-    body,
-    ts: Date.now(),
-  };
-}
-
-function _decodeRealtimeEnvelope(envelope) {
-  if (envelope.type === "base64") {
-    return Buffer.from(envelope.body, "base64");
-  }
-  if (envelope.type === "json") {
-    return JSON.parse(envelope.body);
-  }
-  return envelope.body;
-}
-
-function _sendRealtimePayload(ws, payload) {
-  if (!ws || ws._closed) return false;
-  if (Buffer.isBuffer(payload)) {
-    ws.sendBinary(payload);
-  } else if (typeof payload === "string") {
-    ws.send(payload);
-  } else {
-    ws.send(JSON.stringify(payload));
-  }
-  return true;
-}
-
-function _normalizeRealtimeDecision(decision, fallback = {}) {
-  if (decision === undefined || decision === null || decision === true) {
-    return { allow: true, ...fallback };
-  }
-  if (decision === false) {
-    return { allow: false, ...fallback };
-  }
-  if (typeof decision === "object") {
-    return {
-      ...fallback,
-      ...decision,
-      allow: decision.allow !== false,
-    };
-  }
-  return { allow: Boolean(decision), ...fallback };
-}
-
-function _socketBufferedBytes(ws) {
-  const sock = ws?.socket;
-  if (!sock) return 0;
-  const bytes = sock.writableLength ?? sock.bufferSize ?? 0;
-  return Number.isFinite(bytes) ? bytes : 0;
-}
-
-export function realtime(options = {}) {
-  const adapter = options.adapter ?? (options.redisUrl ? "redis" : "memory");
-  const busChannel = options.busChannel ?? "forge:realtime";
-  const maxPayloadBytes = options.maxPayloadBytes ?? 256 * 1024;
-  const maxConnections = options.maxConnections ?? 10_000;
-  const maxSocketBufferBytes = options.maxSocketBufferBytes ?? 512 * 1024;
-  const backpressureStrategy = options.backpressureStrategy ?? "drop";
-  const redisSubHealthcheckMs = options.redisSubHealthcheckMs ?? 2000;
-  const strictBusPublish = options.strictBusPublish ?? false;
-  const authorize = options.authorize;
-  const authorizeUpgrade = options.authorizeUpgrade;
-  const authorizeConnect = options.authorizeConnect;
-  const allowedChannels = options.allowedChannels ? new Set(options.allowedChannels) : null;
-
-  return {
-    name: "realtime",
-    version: "1.0.0",
-    inject: "realtime",
-
-    validate() {
-      if (!["memory", "redis"].includes(adapter)) {
-        throw new Error(`Realtime adapter must be "memory" or "redis", got "${adapter}"`);
-      }
-      if (!REALTIME_CHANNEL_RE.test(busChannel)) {
-        throw new Error(`Invalid realtime busChannel "${busChannel}"`);
-      }
-      if (!Number.isInteger(maxPayloadBytes) || maxPayloadBytes <= 0) {
-        throw new Error(`Realtime maxPayloadBytes must be a positive integer, got ${maxPayloadBytes}`);
-      }
-      if (!Number.isInteger(maxConnections) || maxConnections <= 0) {
-        throw new Error(`Realtime maxConnections must be a positive integer, got ${maxConnections}`);
-      }
-      if (!Number.isInteger(maxSocketBufferBytes) || maxSocketBufferBytes <= 0) {
-        throw new Error(
-          `Realtime maxSocketBufferBytes must be a positive integer, got ${maxSocketBufferBytes}`,
-        );
-      }
-      if (!REALTIME_BACKPRESSURE_STRATEGIES.has(backpressureStrategy)) {
-        throw new Error(
-          `Realtime backpressureStrategy must be "drop" or "close", got "${backpressureStrategy}"`,
-        );
-      }
-      if (!Number.isInteger(redisSubHealthcheckMs) || redisSubHealthcheckMs <= 0) {
-        throw new Error(
-          `Realtime redisSubHealthcheckMs must be a positive integer, got ${redisSubHealthcheckMs}`,
-        );
-      }
-      if (authorize !== undefined && typeof authorize !== "function") {
-        throw new Error(`Realtime authorize must be a function`);
-      }
-      if (authorizeUpgrade !== undefined && typeof authorizeUpgrade !== "function") {
-        throw new Error(`Realtime authorizeUpgrade must be a function`);
-      }
-      if (authorizeConnect !== undefined && typeof authorizeConnect !== "function") {
-        throw new Error(`Realtime authorizeConnect must be a function`);
-      }
-      if (allowedChannels) {
-        for (const ch of allowedChannels) _assertRealtimeChannel(ch, null);
-      }
-      if (adapter === "redis") {
-        const url = options.redisUrl ?? process.env.FORGE_REALTIME_REDIS_URL ?? process.env.FORGE_REDIS_URL;
-        if (!url) {
-          throw new Error('Realtime adapter "redis" requires redisUrl or FORGE_REALTIME_REDIS_URL/FORGE_REDIS_URL');
-        }
-      }
-    },
-
-    env() {
-      if (adapter !== "redis") return {};
-      const url = options.redisUrl ?? process.env.FORGE_REALTIME_REDIS_URL ?? process.env.FORGE_REDIS_URL;
-      return url ? { FORGE_REALTIME_REDIS_URL: url } : {};
-    },
-
-    async connect(ctx) {
-      const connections = new Set();
-      const socketsByChannel = new Map(); // channel -> Set<ws>
-      const channelsBySocket = new Map(); // ws -> Set<channel>
-      const socketMeta = new WeakMap(); // ws -> { req, meta }
-      const senderId = `${ctx.serviceName}:${ctx.workerId}:${process.pid}`;
-      const metrics = {
-        published: 0,
-        delivered: 0,
-        dropped: 0,
-        backpressureDropped: 0,
-        busPublishErrors: 0,
-        redisReconnects: 0,
-      };
-
-      let redisPub = null;
-      let redisSub = null;
-      let usingIoRedis = false;
-      let builtInSubWatchdog = null;
-      let builtInSubProbeRunning = false;
-      let lastBackpressureLogAt = 0;
-
-      const shouldLogBackpressure = () => {
-        const now = Date.now();
-        if (now - lastBackpressureLogAt < 30_000) return false;
-        lastBackpressureLogAt = now;
-        return true;
-      };
-
-      const runAuthorizeHook = async (stage, payload) => {
-        const defaultDenied = stage === "upgrade"
-          ? { statusCode: 403, reason: "Forbidden" }
-          : { closeCode: 1008, closeReason: "Policy violation" };
-        const stageHook = stage === "upgrade" ? authorizeUpgrade : stage === "connect" ? authorizeConnect : null;
-        if (typeof stageHook === "function") {
-          const result = await stageHook({ stage, ...payload });
-          return _normalizeRealtimeDecision(result, defaultDenied);
-        }
-        if (typeof authorize === "function") {
-          const result = await authorize({ stage, ...payload });
-          return _normalizeRealtimeDecision(result, defaultDenied);
-        }
-        return { allow: true };
-      };
-
-      const ensureSocketTracked = (ws, req = null, meta = null) => {
-        if (!connections.has(ws)) {
-          connections.add(ws);
-          channelsBySocket.set(ws, new Set());
-        }
-        const prev = socketMeta.get(ws) ?? {};
-        socketMeta.set(ws, {
-          req: req ?? prev.req ?? null,
-          meta: meta ?? prev.meta ?? null,
-        });
-      };
-
-      const cleanupSocket = (ws) => {
-        const socketChannels = channelsBySocket.get(ws);
-        if (socketChannels) {
-          for (const channel of socketChannels) {
-            const members = socketsByChannel.get(channel);
-            if (members) {
-              members.delete(ws);
-              if (members.size === 0) socketsByChannel.delete(channel);
-            }
-          }
-        }
-        channelsBySocket.delete(ws);
-        connections.delete(ws);
-        socketMeta.delete(ws);
-      };
-
-      const handleBackpressure = (ws, channel) => {
-        metrics.backpressureDropped++;
-        metrics.dropped++;
-        if (backpressureStrategy === "close") {
-          try {
-            ws.close?.(1013, "Backpressure");
-          } catch {}
-          cleanupSocket(ws);
-        }
-        if (shouldLogBackpressure()) {
-          ctx.logger.warn("Realtime dropping message due to socket backpressure", {
-            channel,
-            strategy: backpressureStrategy,
-            maxSocketBufferBytes,
-          });
-        }
-      };
-
-      const deliverEnvelope = (envelope, { excludeWs = null } = {}) => {
-        const members = socketsByChannel.get(envelope.channel);
-        if (!members || members.size === 0) return 0;
-        let delivered = 0;
-        let payload;
-        try {
-          payload = _decodeRealtimeEnvelope(envelope);
-        } catch (err) {
-          ctx.logger.warn(`Realtime decode failed`, { error: err.message, channel: envelope.channel });
-          return 0;
-        }
-
-        for (const ws of members) {
-          if (excludeWs && ws === excludeWs) continue;
-          if (_socketBufferedBytes(ws) > maxSocketBufferBytes) {
-            handleBackpressure(ws, envelope.channel);
-            continue;
-          }
-          try {
-            if (_sendRealtimePayload(ws, payload)) {
-              delivered++;
-            } else {
-              metrics.dropped++;
-            }
-          } catch {
-            metrics.dropped++;
-          }
-        }
-        metrics.delivered += delivered;
-        return delivered;
-      };
-
-      const handleBusMessage = (raw) => {
-        try {
-          const envelope = JSON.parse(raw);
-          if (!envelope || envelope.v !== 1 || typeof envelope.channel !== "string") return;
-          if (envelope.senderId === senderId) return; // already delivered locally
-          deliverEnvelope(envelope);
-        } catch (err) {
-          ctx.logger.warn(`Realtime bus message parse failed`, { error: err.message });
-        }
-      };
-
-      const publishToBus = async (envelope) => {
-        if (adapter !== "redis") return { ok: true, skipped: true };
-        if (!redisPub) return { ok: false, skipped: true, error: new Error("Redis publisher unavailable") };
-        try {
-          await redisPub.publish(busChannel, JSON.stringify(envelope));
-          return { ok: true };
-        } catch (err) {
-          metrics.busPublishErrors++;
-          ctx.logger.warn("Realtime publish to bus failed", { error: err.message, busChannel });
-          return { ok: false, error: err };
-        }
-      };
-
-      if (adapter === "redis") {
-        const redisUrl = options.redisUrl ?? process.env.FORGE_REALTIME_REDIS_URL ?? process.env.FORGE_REDIS_URL;
-        try {
-          const Redis = (await import("ioredis")).default;
-          const retryStrategy = (times) => Math.min(100 * 2 ** Math.min(times, 8), 5000);
-          redisPub = new Redis(redisUrl, {
-            lazyConnect: true,
-            maxRetriesPerRequest: null,
-            retryStrategy,
-          });
-          redisSub = new Redis(redisUrl, {
-            lazyConnect: true,
-            maxRetriesPerRequest: null,
-            autoResubscribe: true,
-            retryStrategy,
-          });
-          await redisPub.connect();
-          await redisSub.connect();
-          await redisSub.subscribe(busChannel);
-          redisSub.on("reconnecting", () => {
-            metrics.redisReconnects++;
-          });
-          redisSub.on("message", (_channel, message) => {
-            handleBusMessage(message);
-          });
-          redisPub.on("error", (err) => {
-            ctx.logger.warn("Realtime redis publisher error", { error: err.message });
-          });
-          redisSub.on("error", (err) => {
-            ctx.logger.warn("Realtime redis subscriber error", { error: err.message });
-          });
-          usingIoRedis = true;
-          ctx.logger.info("Realtime connected (redis adapter)", { busChannel });
-        } catch {
-          redisPub = await _mkRedis(redisUrl, ctx);
-          redisSub = await _mkRedis(redisUrl, ctx);
-          await redisSub.subscribe(busChannel, (message) => handleBusMessage(message));
-          // Built-in client doesn't expose reconnect events; monitor sub connection health.
-          builtInSubWatchdog = setInterval(async () => {
-            if (builtInSubProbeRunning) return;
-            if (!redisSub || redisSub._subConnected !== false) return;
-            builtInSubProbeRunning = true;
-            try {
-              metrics.redisReconnects++;
-              await redisSub._ensureSubConnection?.();
-            } catch (err) {
-              ctx.logger.warn("Realtime built-in redis subscriber reconnect failed", {
-                error: err.message,
-              });
-            } finally {
-              builtInSubProbeRunning = false;
-            }
-          }, redisSubHealthcheckMs);
-          builtInSubWatchdog.unref?.();
-          ctx.logger.info("Realtime connected (redis adapter, built-in client)", { busChannel });
-        }
-      } else {
-        ctx.logger.info("Realtime connected (memory adapter)");
-      }
-
-      const client = {
-        adapter,
-        busChannel,
-
-        join(ws, channel) {
-          _assertRealtimeChannel(channel, allowedChannels);
-          ensureSocketTracked(ws);
-          const socketChannels = channelsBySocket.get(ws);
-          socketChannels.add(channel);
-          if (!socketsByChannel.has(channel)) socketsByChannel.set(channel, new Set());
-          socketsByChannel.get(channel).add(ws);
-          return true;
-        },
-
-        leave(ws, channel) {
-          const socketChannels = channelsBySocket.get(ws);
-          if (!socketChannels) return false;
-          socketChannels.delete(channel);
-          const members = socketsByChannel.get(channel);
-          if (members) {
-            members.delete(ws);
-            if (members.size === 0) socketsByChannel.delete(channel);
-          }
-          return true;
-        },
-
-        async publish(channel, payload, opts = {}) {
-          _assertRealtimeChannel(channel, allowedChannels);
-          const envelope = _encodeRealtimeEnvelope(channel, payload, senderId, maxPayloadBytes);
-          const localDelivered = deliverEnvelope(envelope, { excludeWs: opts.excludeWs ?? null });
-          metrics.published++;
-          const busResult = await publishToBus(envelope);
-          if (!busResult.ok && strictBusPublish) {
-            throw new Error(`Realtime bus publish failed: ${busResult.error?.message ?? "unknown error"}`);
-          }
-          return {
-            delivered: localDelivered,
-            busPublished: busResult.ok === true || busResult.skipped === true,
-          };
-        },
-
-        broadcast(payload, opts = {}) {
-          const envelope = _encodeRealtimeEnvelope("__broadcast__", payload, senderId, maxPayloadBytes);
-          const decoded = _decodeRealtimeEnvelope(envelope);
-          let delivered = 0;
-          for (const ws of connections) {
-            if (opts.excludeWs && ws === opts.excludeWs) continue;
-            if (_socketBufferedBytes(ws) > maxSocketBufferBytes) {
-              handleBackpressure(ws, "__broadcast__");
-              continue;
-            }
-            try {
-              if (_sendRealtimePayload(ws, decoded)) {
-                delivered++;
-              } else {
-                metrics.dropped++;
-              }
-            } catch {
-              metrics.dropped++;
-            }
-          }
-          metrics.delivered += delivered;
-          metrics.published++;
-          return { delivered };
-        },
-
-        attach(ws, attachOptions = {}) {
-          ensureSocketTracked(ws, attachOptions.req ?? null, attachOptions.meta ?? null);
-          for (const ch of attachOptions.channels ?? []) {
-            this.join(ws, ch);
-          }
-          return {
-            join: (channel) => this.join(ws, channel),
-            leave: (channel) => this.leave(ws, channel),
-            publish: (channel, payload) => this.publish(channel, payload, { excludeWs: ws }),
-            detach: () => cleanupSocket(ws),
-          };
-        },
-
-        channels() {
-          return [...socketsByChannel.keys()];
-        },
-
-        connectionCount() {
-          return connections.size;
-        },
-
-        async _onWsUpgrade(hookCtx) {
-          if (connections.size >= maxConnections) {
-            return { allow: false, statusCode: 503, reason: "WebSocket capacity reached" };
-          }
-          const decision = await runAuthorizeHook("upgrade", hookCtx);
-          if (!decision.allow) {
-            return {
-              allow: false,
-              statusCode: decision.statusCode ?? 403,
-              reason: decision.reason ?? "Forbidden",
-              headers: decision.headers ?? {},
-            };
-          }
-          return { allow: true };
-        },
-
-        async _onWsConnect(hookCtx) {
-          const { ws, req, meta } = hookCtx ?? {};
-          ensureSocketTracked(ws, req, meta);
-          const decision = await runAuthorizeHook("connect", hookCtx);
-          if (!decision.allow) {
-            try {
-              ws?.close?.(decision.closeCode ?? 1008, decision.closeReason ?? "Policy violation");
-            } catch {}
-            cleanupSocket(ws);
-            return {
-              allow: false,
-              closeCode: decision.closeCode ?? 1008,
-              closeReason: decision.closeReason ?? "Policy violation",
-            };
-          }
-          return { allow: true };
-        },
-
-        _registerConnection(ws, req, meta) {
-          ensureSocketTracked(ws, req, meta);
-        },
-
-        _cleanupConnection(ws) {
-          cleanupSocket(ws);
-        },
-
-        _metrics() {
-          return {
-            connections: connections.size,
-            channels: socketsByChannel.size,
-            published: metrics.published,
-            delivered: metrics.delivered,
-            dropped: metrics.dropped,
-            backpressureDropped: metrics.backpressureDropped,
-            busPublishErrors: metrics.busPublishErrors,
-            redisReconnects: metrics.redisReconnects,
-          };
-        },
-
-        async _shutdown() {
-          for (const ws of connections) {
-            cleanupSocket(ws);
-          }
-          if (builtInSubWatchdog) {
-            clearInterval(builtInSubWatchdog);
-            builtInSubWatchdog = null;
-          }
-          if (redisSub) {
-            if (usingIoRedis) {
-              redisSub.removeAllListeners("message");
-            }
-            await redisSub.quit?.();
-            redisSub = null;
-          }
-          if (redisPub) {
-            await redisPub.quit?.();
-            redisPub = null;
-          }
-        },
-      };
-
-      return client;
-    },
-
-    async disconnect(client) {
-      await client._shutdown?.();
-    },
-
-    metrics(client) {
-      return client._metrics?.() ?? {};
-    },
-
-    onWsUpgrade(client, ctx) {
-      return client._onWsUpgrade?.(ctx);
-    },
-
-    async onWsConnect(client, ctx) {
-      return client._onWsConnect?.(ctx);
-    },
-
-    onWsClose(client, ctx) {
-      client._cleanupConnection?.(ctx.ws);
-    },
-  };
-}
-
-// ─── Cron ──────────────────────────────────────────────────
-
-/**
- * Parse a single cron field into a Set of matching values.
- * Supports: star, star-slash-N, N, N-M, N-M/S, comma-separated lists.
- * @param {string} field - cron field string
- * @param {number} min - minimum valid value
- * @param {number} max - maximum valid value
- * @returns {Set<number>}
- */
-function _parseCronField(field, min, max) {
-  const values = new Set();
-  for (const part of field.split(',')) {
-    const trimmed = part.trim();
-    // */N or N-M/S
-    const stepMatch = trimmed.match(/^(\*|(\d+)-(\d+))\/(\d+)$/);
-    if (stepMatch) {
-      const step = parseInt(stepMatch[4], 10);
-      if (step <= 0) throw new Error(`Invalid cron step: ${trimmed}`);
-      let start = min, end = max;
-      if (stepMatch[2] !== undefined) {
-        start = parseInt(stepMatch[2], 10);
-        end = parseInt(stepMatch[3], 10);
-      }
-      for (let i = start; i <= end; i += step) values.add(i);
-      continue;
-    }
-    // *
-    if (trimmed === '*') {
-      for (let i = min; i <= max; i++) values.add(i);
-      continue;
-    }
-    // N-M range
-    const rangeMatch = trimmed.match(/^(\d+)-(\d+)$/);
-    if (rangeMatch) {
-      const s = parseInt(rangeMatch[1], 10);
-      const e = parseInt(rangeMatch[2], 10);
-      for (let i = s; i <= e; i++) values.add(i);
-      continue;
-    }
-    // Single value
-    const num = parseInt(trimmed, 10);
-    if (Number.isNaN(num) || num < min || num > max) {
-      throw new Error(`Invalid cron value "${trimmed}" (valid range: ${min}-${max})`);
-    }
-    values.add(num);
-  }
-  return values;
-}
-
-/**
- * Parse a 5-field cron expression and return either:
- * - { type: 'interval', ms } for simple periodic patterns (e.g. "* /5 * * * *")
- * - { type: 'complex', minutes, hours, daysOfMonth, months, daysOfWeek } for complex patterns
- */
-function parseCronExpression(expr) {
-  const parts = expr.trim().split(/\s+/);
-  if (parts.length !== 5) {
-    throw new Error(`Invalid cron expression "${expr}": expected 5 fields, got ${parts.length}`);
-  }
-  const [minF, hourF, domF, monF, dowF] = parts;
-
-  // Try to detect simple interval patterns for setInterval
-  if (hourF === '*' && domF === '*' && monF === '*' && dowF === '*') {
-    if (minF === '*') return { type: 'interval', ms: 60_000 };
-    const stepMatch = minF.match(/^\*\/(\d+)$/);
-    if (stepMatch) return { type: 'interval', ms: parseInt(stepMatch[1], 10) * 60_000 };
-  }
-  if (minF === '0' && domF === '*' && monF === '*' && dowF === '*') {
-    if (hourF === '*') return { type: 'interval', ms: 3_600_000 };
-    const stepMatch = hourF.match(/^\*\/(\d+)$/);
-    if (stepMatch) return { type: 'interval', ms: parseInt(stepMatch[1], 10) * 3_600_000 };
-  }
-  if (minF === '0' && hourF === '0' && monF === '*' && dowF === '*') {
-    if (domF === '*') return { type: 'interval', ms: 86_400_000 };
-  }
-
-  // Complex pattern — parse all fields
-  return {
-    type: 'complex',
-    minutes: _parseCronField(minF, 0, 59),
-    hours: _parseCronField(hourF, 0, 23),
-    daysOfMonth: _parseCronField(domF, 1, 31),
-    months: _parseCronField(monF, 1, 12),
-    daysOfWeek: _parseCronField(dowF, 0, 6),
-  };
-}
-
-/**
- * Calculate milliseconds until the next matching time for a complex cron schedule.
- * Scans up to 366 days ahead.
- */
-function _nextCronTimeout(parsed) {
-  const now = new Date();
-  const check = new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours(), now.getMinutes() + 1, 0, 0);
-  const limit = 366 * 24 * 60; // max minutes to scan
-  for (let i = 0; i < limit; i++) {
-    const m = check.getMinutes();
-    const h = check.getHours();
-    const dom = check.getDate();
-    const mon = check.getMonth() + 1;
-    const dow = check.getDay();
-    if (parsed.minutes.has(m) && parsed.hours.has(h) &&
-        parsed.daysOfMonth.has(dom) && parsed.months.has(mon) &&
-        parsed.daysOfWeek.has(dow)) {
-      return check.getTime() - now.getTime();
-    }
-    check.setMinutes(check.getMinutes() + 1);
-  }
-  throw new Error('Could not find next cron run time within 366 days');
-}
-
-export function cron(options = {}) {
-  const leaderOnly = options.leaderOnly !== false;
-  return {
-    name: "cron",
-    version: "1.0.0",
-    inject: "cron",
-    async connect(ctx) {
-      // Leader election: workerId === 0 is the default leader.
-      // The supervisor can explicitly designate a leader via ctx._isCronLeader.
-      const isLeader = ctx.workerId === 0 || ctx._isCronLeader === true,
-        jobs = new Map(),
-        timers = [];
-
-      if (leaderOnly && !isLeader && ctx.workerId !== 0) {
-        ctx.logger.info(`Cron: worker ${ctx.workerId} is not the cron leader, cron jobs will not run on this worker`);
-      }
-
-      return {
-        jobs,
-        schedule(name, expr, fn, options = {}) {
-          if (leaderOnly && !isLeader) return;
-
-          const parsed = parseCronExpression(expr);
-
-          // Run immediately unless explicitly disabled
-          if (options.immediate !== false) {
-            (async () => {
-              try {
-                ctx.logger.info(`Cron: ${name} (initial run)`);
-                await fn();
-              } catch (e) {
-                ctx.logger.error(`Cron "${name}" initial run failed: ${e.message}`);
-              }
-            })();
-          }
-
-          let _running = false;
-          let _lastSuccess = Date.now();
-
-          const runJob = async () => {
-            const intervalMs = parsed.type === 'interval' ? parsed.ms : 60_000;
-            const timeoutMs = Math.floor(intervalMs * 0.9);
-            if (_running) {
-              if (Date.now() - _lastSuccess > intervalMs * 2) {
-                ctx.logger.warn(`Cron "${name}" appears stuck — no success for ${Math.round((Date.now() - _lastSuccess) / 1000)}s`);
-              }
-              return;
-            }
-            _running = true;
-            try {
-              ctx.logger.info(`Cron: ${name}`);
-              await Promise.race([
-                fn(),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`Cron "${name}" timed out after ${timeoutMs}ms`)), timeoutMs)),
-              ]);
-              _lastSuccess = Date.now();
-            } catch (e) {
-              ctx.logger.error(`Cron "${name}" failed: ${e.message}`);
-            } finally {
-              _running = false;
-            }
-          };
-
-          let t;
-          if (parsed.type === 'interval') {
-            t = setInterval(runJob, parsed.ms);
-            jobs.set(name, { expr, timer: t });
-            timers.push(t);
-            ctx.logger.info(`Cron: "${name}" every ${parsed.ms / 1000}s`);
-          } else {
-            // Complex pattern: use setTimeout with recalculation
-            let active = true;
-            function scheduleNext() {
-              if (!active) return;
-              const delayMs = _nextCronTimeout(parsed);
-              t = setTimeout(async () => {
-                await runJob();
-                scheduleNext();
-              }, delayMs);
-              jobs.set(name, { expr, timer: t, _cancelComplex() { active = false; } });
-              // Update the timers array entry
-              const idx = timers.indexOf(t);
-              if (idx === -1) timers.push(t);
-            }
-            scheduleNext();
-            ctx.logger.info(`Cron: "${name}" scheduled (complex expression: ${expr})`);
-          }
-        },
-        cancel(name) {
-          const j = jobs.get(name);
-          if (j) {
-            clearInterval(j.timer);
-            clearTimeout(j.timer);
-            if (j._cancelComplex) j._cancelComplex();
-            const idx = timers.indexOf(j.timer);
-            if (idx !== -1) timers.splice(idx, 1);
-            jobs.delete(name);
-          }
-        },
-        listJobs: () => [...jobs.keys()],
-        _timers: timers,
-      };
-    },
-    async disconnect(c) {
-      c._timers.forEach((t) => { clearInterval(t); clearTimeout(t); });
-      for (const j of c.jobs.values()) {
-        if (j._cancelComplex) j._cancelComplex();
-      }
-      c._timers.length = 0;
-      c.jobs.clear();
-    },
-  };
-}