threadforge 0.1.0

package/src/plugins/index.js

@@ -0,0 +1,1729 @@
+/**
+ * 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 = [],
+    buf = Buffer.alloc(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 (buf.length + d.length > MAX_REDIS_BUFFER) {
+          socket.destroy(new Error('Redis response buffer overflow'));
+          return;
+        }
+        buf = Buffer.concat([buf, d]);
+        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"));
+        buf = Buffer.alloc(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() {
+    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
+        buf = Buffer.alloc(0);
+        rq.shift().no(err);
+        return;
+      }
+      if (!r) break;
+      buf = r.rem;
+      rq.shift().ok(r.val);
+    }
+  }
+  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,
+    _subBuf: Buffer.alloc(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._subBuf.length + d.length > MAX_REDIS_BUFFER) {
+            self._subSocket.destroy(new Error('Redis sub response buffer overflow'));
+            return;
+          }
+          self._subBuf = Buffer.concat([self._subBuf, d]);
+          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._subBuf = Buffer.alloc(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() {
+      while (this._subBuf.length) {
+        let r;
+        try {
+          r = parse(this._subBuf, 0);
+        } catch {
+          this._subBuf = Buffer.alloc(0);
+          return;
+        }
+        if (!r) break;
+        this._subBuf = 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);
+      }
+    },
+
+    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._subBuf = Buffer.alloc(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();
+    },
+  };
+}