mega-framework 0.1.2 → 0.1.4

package/src/core/ws-roster.js

@@ -0,0 +1,163 @@
+// @ts-check
+/**
+ * MegaWsRedisRoster — **채널별** 클러스터 접속자 목록(roster)을 redis 로 관리 (ADR-177).
+ *
+ * roster 는 "전송(broadcast)"이 아니라 **공유 상태(누가 어느 채널에 접속 중인지)** 라, 허브 개수와 무관한
+ * **공유 스토어(redis)** 가 단일 source-of-truth 다. 이로써 (1) **멀티 허브**에서도 명단이 정합하고,
+ * (2) 신규/재연결 브릿지가 `HGETALL` 한 번으로 **전체 명단을 즉시** 획득하며(허브 presence 스냅샷 불요),
+ * (3) TTL+heartbeat 로 crash 워커의 stale 엔트리를 자동 정리한다. broadcast(메시지)는 그대로 허브(또는
+ * NATS)가 fan-out 하고, 본 모듈은 **roster(상태)만** 다룬다(관심사 분리).
+ *
+ * # 키 스키마 — 채널 기준
+ *   `<prefix>:<channel>` = HASH( sessionId → JSON({ userId, metadata?, expiresAt }) )
+ *   예) `ws:roster:chat`. 룸(채널 내 더 잘게 나눔)은 **앱 비즈니스 로직** — 프레임워크는 채널 단위만.
+ *
+ * # crash 정리(TTL) — HEXPIRE 없이 모든 redis 버전 호환
+ *   per-field TTL(HEXPIRE)은 redis 7.4+ 라, 대신 **값에 `expiresAt` 을 싣고 읽을 때 lazy 만료**한다.
+ *   각 워커가 heartbeat 로 자기 로컬 세션의 `expiresAt` 을 주기 갱신 → 살아있는 세션은 유지, crash 워커의
+ *   세션은 갱신이 끊겨 만료된다. `list` 는 만료 엔트리를 결과에서 빼고 best-effort 로 `HDEL` 한다.
+ *
+ * @module core/ws-roster
+ */
+
+/** 기본 키 접두. */
+const DEFAULT_KEY_PREFIX = 'ws:roster'
+/** 기본 멤버 TTL(ms) — heartbeat 미갱신 시 stale 로 간주. */
+const DEFAULT_TTL_MS = 30_000
+
+/**
+ * 채널 roster 멤버(redis 에 저장되는 형태 — sessionId 는 HASH field 라 값엔 안 넣음).
+ * @typedef {Object} RosterMember
+ * @property {string} userId
+ * @property {Object} [metadata]
+ */
+
+/**
+ * redis 기반 채널별 roster.
+ *
+ * 앱(MegaApp) 1개당 1 인스턴스. boot 가 `bridgeHub.roster.driver==='redis'` 일 때 생성·start·shutdown 한다.
+ * redis 핸들은 캐시 어댑터의 `.native`(ioredis) 를 받는다 — pub/sub 가 아니라 HASH 명령(HSET/HGETALL/HDEL)만 쓴다.
+ */
+export class MegaWsRedisRoster {
+  /**
+   * @param {Object} opts
+   * @param {import('ioredis').Redis} opts.redis - 캐시 어댑터의 raw ioredis 핸들.
+   * @param {() => Array<{ channel: string, sessionId: string, member: RosterMember }>} opts.getLocalMembers -
+   *   이 워커의 현재 로컬 멤버 목록(heartbeat 갱신 대상). 보통 mega-app 의 세션 매핑에서 도출.
+   * @param {string} [opts.keyPrefix] - 키 접두(기본 'ws:roster').
+   * @param {number} [opts.ttlMs] - 멤버 TTL(ms, 기본 30000).
+   * @param {{ debug?: Function, warn?: Function, error?: Function }} [opts.logger]
+   */
+  constructor({ redis, getLocalMembers, keyPrefix, ttlMs, logger } = /** @type {any} */ ({})) {
+    if (!redis || typeof redis.hset !== 'function' || typeof redis.hgetall !== 'function') {
+      throw new Error('MegaWsRedisRoster: a redis(ioredis) handle (cache adapter .native) is required.')
+    }
+    this._redis = redis
+    this._getLocalMembers = typeof getLocalMembers === 'function' ? getLocalMembers : () => /** @type {Array<{ channel: string, sessionId: string, member: RosterMember }>} */ ([])
+    this._prefix = typeof keyPrefix === 'string' && keyPrefix.length > 0 ? keyPrefix : DEFAULT_KEY_PREFIX
+    this._ttlMs = Number.isInteger(ttlMs) && /** @type {number} */ (ttlMs) > 0 ? /** @type {number} */ (ttlMs) : DEFAULT_TTL_MS
+    this._log = logger
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._hbTimer = null
+  }
+
+  /** 채널 → redis 키. @param {string} channel @returns {string} @private */
+  _key(channel) {
+    return `${this._prefix}:${channel}`
+  }
+
+  /**
+   * 채널 roster 에 멤버 추가/갱신(joinSession). 키 자체에도 EXPIRE 를 걸어 버려진 채널이 새지 않게 한다.
+   * @param {string} channel @param {string} sessionId @param {RosterMember} member @returns {Promise<void>}
+   */
+  async add(channel, sessionId, member) {
+    if (typeof channel !== 'string' || typeof sessionId !== 'string') return
+    const key = this._key(channel)
+    const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt: Date.now() + this._ttlMs })
+    await this._redis.hset(key, sessionId, value)
+    // 채널 HASH 키 전체 TTL — 모든 멤버가 stale 가 돼도 키가 영구히 남지 않게(멤버 TTL 의 2배 여유).
+    await this._redis.pexpire(key, this._ttlMs * 2)
+  }
+
+  /**
+   * 채널 roster 에서 멤버 제거(disconnect).
+   * @param {string} channel @param {string} sessionId @returns {Promise<void>}
+   */
+  async remove(channel, sessionId) {
+    if (typeof channel !== 'string' || typeof sessionId !== 'string') return
+    await this._redis.hdel(this._key(channel), sessionId)
+  }
+
+  /**
+   * 채널의 **현재 접속자 목록**(만료 제외). 만료 엔트리는 best-effort 로 정리한다.
+   * @param {string} channel @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+   */
+  async list(channel) {
+    if (typeof channel !== 'string') return []
+    /** @type {Record<string, string>} */
+    const raw = await this._redis.hgetall(this._key(channel))
+    const now = Date.now()
+    /** @type {Array<{ sessionId: string, userId: string, metadata?: Object }>} */
+    const out = []
+    /** @type {string[]} 만료돼 정리할 field. */
+    const expired = []
+    for (const [sessionId, json] of Object.entries(raw ?? {})) {
+      let m
+      try {
+        m = JSON.parse(json)
+      } catch (err) {
+        // 손상 엔트리는 결과에서 제외 + 정리(silent 금지 — 사유 로그).
+        this._log?.warn?.({ err, channel, sessionId }, 'ws-roster corrupt entry (dropping)')
+        expired.push(sessionId)
+        continue
+      }
+      if (typeof m.expiresAt === 'number' && m.expiresAt < now) {
+        expired.push(sessionId) // heartbeat 끊긴 crash 세션 — 만료.
+        continue
+      }
+      out.push({ sessionId, userId: m.userId, ...(m.metadata ? { metadata: m.metadata } : {}) })
+    }
+    if (expired.length > 0) {
+      // best-effort 정리(실패해도 다음 list 에서 다시 시도) — 결과엔 이미 제외됨.
+      this._redis.hdel(this._key(channel), ...expired).catch((err) => this._log?.warn?.({ err, channel }, 'ws-roster expired cleanup failed'))
+    }
+    return out
+  }
+
+  /**
+   * heartbeat 시작 — 주기적으로 로컬 멤버의 `expiresAt` 을 갱신해 살아있음을 알린다(crash 워커는 갱신이
+   * 끊겨 만료). 프로세스 종료를 막지 않게 unref. 멱등(중복 호출 무시).
+   * @returns {void}
+   */
+  startHeartbeat() {
+    if (this._hbTimer) return
+    const intervalMs = Math.max(1000, Math.floor(this._ttlMs / 2))
+    this._hbTimer = setInterval(() => {
+      this._refreshLocal().catch((err) => this._log?.warn?.({ err }, 'ws-roster heartbeat refresh failed'))
+    }, intervalMs)
+    this._hbTimer.unref?.()
+  }
+
+  /**
+   * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+   */
+  async _refreshLocal() {
+    const members = this._getLocalMembers()
+    for (const { channel, sessionId, member } of members) {
+      await this.add(channel, sessionId, member)
+    }
+  }
+
+  /**
+   * 정리 — heartbeat 중지 + 로컬 멤버를 redis 에서 제거(graceful 종료 시 다른 워커가 즉시 정합).
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (this._hbTimer) clearInterval(this._hbTimer)
+    this._hbTimer = null
+    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리).
+    for (const { channel, sessionId } of this._getLocalMembers()) {
+      await this.remove(channel, sessionId).catch(() => {})
+    }
+  }
+}

package/src/core/ws-upgrade.js

@@ -46,6 +46,12 @@ export const CLOSE_CODE_DECRYPT_FAILED = 4500
  */
 export const CLOSE_CODE_INTERNAL_ERROR = 1011
 
+/** 느린 소비자 백프레셔 close code (RFC 6455 §7.4.1 표준 1013 "Try Again Later", Med). */
+export const CLOSE_CODE_SLOW_CONSUMER = 1013
+
+/** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
+export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
+
 /**
  * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
  * @typedef {Object} WsFrameCodec
@@ -93,11 +99,13 @@ export class MegaWsConnection {
   /**
    * @param {import('ws').WebSocket} rawSocket
    * @param {WsFrameCodec} codec
-   * @param {{ id?: string, ns?: string, path: string }} meta
+   * @param {{ id?: string, ns?: string, path: string, maxBufferedBytes?: number }} meta
    */
   constructor(rawSocket, codec, meta) {
     /** @type {import('ws').WebSocket} */
     this._raw = rawSocket
+    /** @type {number} send 버퍼 상한(바이트) — 초과 시 느린 소비자로 보고 연결 종료(백프레셔). */
+    this._maxBufferedBytes = Number.isFinite(meta.maxBufferedBytes) ? /** @type {number} */ (meta.maxBufferedBytes) : DEFAULT_MAX_BUFFERED_BYTES
     /** @type {WsFrameCodec} */
     this._codec = codec
     /** @type {string} 연결 식별자 (ULID). */
@@ -136,6 +144,16 @@ export class MegaWsConnection {
    * @returns {void}
    */
   send(fields) {
+    // 백프레셔 가드(Med): 송신 버퍼가 상한을 넘으면 소비자가 ack 를 못 따라오는 것 → 더 쌓지 않고 연결을
+    // 종료한다(느린 소비자 몇 개가 fan-out 으로 서버 힙을 무한 적재→OOM 시키는 것 방지). close code 1013.
+    if (this._raw.bufferedAmount > this._maxBufferedBytes) {
+      try {
+        this._raw.close(CLOSE_CODE_SLOW_CONSUMER, 'backpressure: send buffer exceeded')
+      } catch {
+        // 이미 닫히는 중이면 close 는 무의미 — 무시(비치명적, 다음 send 는 isOpen 가드로 걸러짐).
+      }
+      return
+    }
     // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
     const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
     const env = createWsMessage(withNs)
@@ -175,14 +193,21 @@ export class MegaWsConnection {
  * @param {import('./mega-app.js').MegaApp|null|undefined} app
  * @param {MegaWsConnection} conn
  * @param {string|undefined} ns
- * @returns {{ list: () => Array<object>, join: (entry: object) => void, directToUser: (userId: string, message: object) => void, broadcast: (args: object) => void } | null}
+ * @returns {{ list: () => Promise<Array<object>>, join: (entry: object) => void, directToUser: (userId: string, message: object) => void, broadcast: (args: object) => void } | null}
  */
 function buildWsPresence(app, conn, ns) {
   if (!app || typeof (/** @type {any} */ (app).joinSession) !== 'function' || typeof ns !== 'string') return null
   const a = /** @type {any} */ (app)
   return {
-    /** 이 채널 ns 의 **클러스터 전역** 접속자 목록(wsCluster roster). 미배선이면 로컬 멤버만. */
-    list: () => a.roster(ns),
+    /**
+     * 이 연결이 가입한 채널의 **클러스터 전역** 접속자 목록(async). redis roster(ADR-177) 배선 시 채널 기준
+     * (redis HASH, 멀티 허브 정합); 미배선이면 NATS/로컬 ns 기준. 룸별 필터는 앱이 직접(프레임워크는 채널 단위).
+     * @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+     */
+    list: async () => {
+      if (a._wsRoster && conn.channels && conn.channels.size > 0) return a.presenceList([...conn.channels])
+      return a.roster(ns)
+    },
     /** 연결을 신원에 매핑 — `{ userId, sessionId, channels?, metadata? }`. roster 등록이 자동으로 따라온다. */
     join: (entry) => {
       a.joinSession(conn, entry)

package/src/lib/asp/nonce-cache.js

@@ -22,6 +22,9 @@ const NONCE_KEY_PREFIX = 'asp:nonce:'
 /** 기본 TTL — drift 윈도우(±60s) 의 2배 (ADR-058: EX 120). */
 const DEFAULT_TTL_SEC = 120
 
+/** in-memory nonce store 의 lazy sweep 주기 — insert 이 이 횟수만큼 누적되면 만료 일괄 제거(Med). */
+const SWEEP_EVERY_OPS = 500
+
 /**
  * MegaAspNonceCache — nonce SETNX 래퍼.
  */
@@ -62,6 +65,8 @@ export class MegaMemoryNonceStore {
   constructor() {
     /** @type {Map<string, number>} key → 만료 epoch ms */
     this._store = new Map()
+    /** @type {number} 마지막 sweep 이후 insert 횟수 — SWEEP_EVERY_OPS 마다 만료 일괄 제거. */
+    this._opsSinceSweep = 0
   }
 
   /**
@@ -71,6 +76,13 @@ export class MegaMemoryNonceStore {
    */
   async setIfNotExists(key, ttlSec) {
     const now = Date.now()
+    // lazy 주기 sweep(Med) — setIfNotExists 가 키 단건만 만료 갱신하므로, 다시 안 들어오는 nonce 는 영구
+    // 잔존(메모리 릭)한다. 타이머 없이 insert 누적이 임계를 넘을 때마다 만료를 일괄 제거해 Map 을 bound 한다
+    // (타이머 lifecycle/dispose 불필요 → 안전). 활성(미만료) nonce 는 TTL 로 자연 bound.
+    if (++this._opsSinceSweep >= SWEEP_EVERY_OPS) {
+      this.evictExpired(now)
+      this._opsSinceSweep = 0
+    }
     const exp = this._store.get(key)
     if (exp !== undefined && exp > now) return false
     this._store.set(key, now + ttlSec * 1000)

package/src/lib/logger/telegram-core.js

@@ -68,25 +68,63 @@ const LEVEL_NAMES = /** @type {Record<number, string>} */ ({
 
 /**
  * disk-backed retry queue — 전송 실패한 텍스트를 파일(JSONL)에 쌓고, 다음 기회에 재시도한다(전송 실패해도
- * 메시지를 잃지 않음, ADR-023). worker thread 내에서만 접근하므로 락 불필요(단일 소비자).
+ * 메시지를 잃지 않음, ADR-023).
+ *
+ * # in-process 직렬화 락 (ADR-023)
+ *   단일 스레드라도 `append`(open→write→close)와 `drain`(rename→read→rm)은 각 await 사이에서 **이벤트루프
+ *   인터리브**된다. 인터리브되면 append 의 `open` 이 drain 의 `rename` 보다 먼저 일어날 때, write 가 이미
+ *   rename·rm 된 inode 로 가서 항목이 **유실**된다(rename-claim 의 "유실 0" 이 깨지는 좁은 창). 그래서 큐
+ *   연산을 promise 체인 mutex 로 **직렬화**해 인터리브를 원천 차단한다. 큐 연산은 드물어(전송 실패 시
+ *   append + 주기 drain) 직렬화 비용은 무시 가능. rename-claim 은 cross-process 안전용으로 그대로 둔다.
+ *
+ * # 상한(cap) — 무한 증가 방지 (H4, 최적화 리포트)
+ *   텔레그램이 장기 장애(토큰 만료·차단·네트워크 단절)면 실패분이 무한 적재되고, drain 이 파일 전체를
+ *   메모리로 읽어 재시도→또 실패→전량 재append 한다. 그래서 `drain` 이 **maxAge 만료 + maxEntries 상한**을
+ *   적용해(오래된 것부터 드롭, 드롭 수는 `onDrop` 으로 관측) 디스크·드레인 메모리를 함께 bound 한다.
+ *   write 경로 append rate 는 transport throttle 로 이미 제한되므로 drain 시점 cap 으로 충분하다.
  */
 export class RetryQueue {
   /**
    * @param {string} filePath - JSONL 큐 파일 경로(없으면 비어 있음).
+   * @param {{ maxEntries?: number, maxAgeMs?: number, onDrop?: (count: number) => void }} [opts]
+   *   maxEntries: 보관 최대 항목 수(기본 5000, 0=무제한). maxAgeMs: 항목 최대 보존 ms(기본 24h, 0=무제한).
+   *   onDrop: cap 으로 드롭된 수 통지(관측용).
    */
-  constructor(filePath) {
+  constructor(filePath, { maxEntries = 5000, maxAgeMs = 86_400_000, onDrop } = {}) {
     /** @type {string} */
     this._file = filePath
+    /** @type {Promise<unknown>} 직렬화 락의 꼬리 — append/drain/clear 를 이 체인에 줄세운다. */
+    this._tail = Promise.resolve()
+    /** @type {number} 보관 최대 항목 수(0=무제한). */
+    this._maxEntries = Number.isInteger(maxEntries) && maxEntries > 0 ? maxEntries : 0
+    /** @type {number} 항목 최대 보존 ms(0=무제한). */
+    this._maxAgeMs = Number.isInteger(maxAgeMs) && maxAgeMs > 0 ? maxAgeMs : 0
+    /** @type {((count: number) => void) | null} cap 드롭 수 통지. */
+    this._onDrop = typeof onDrop === 'function' ? onDrop : null
   }
 
   /**
-   * 실패 메시지를 큐에 append.
+   * 큐 연산을 직렬화 — 앞 연산이 끝난 뒤(성패 무관) `fn` 을 실행한다. 한 연산의 실패가 다음 연산을 막지
+   * 않도록 락 체인은 에러를 삼키되, 호출자에겐 결과/에러를 그대로 전파한다.
+   * @template T @param {() => Promise<T>} fn @returns {Promise<T>} @private
+   */
+  _serialize(fn) {
+    const result = this._tail.then(() => fn())
+    // 락 꼬리: 앞 연산의 성패와 무관하게 다음 연산을 진행시킨다(에러는 result 로 호출자에게만 전파).
+    this._tail = result.catch(() => {})
+    return result
+  }
+
+  /**
+   * 실패 메시지를 큐에 append (직렬화됨).
    * @param {string} text
    * @returns {Promise<void>}
    */
   async append(text) {
-    await mkdir(dirname(this._file), { recursive: true })
-    await appendFile(this._file, JSON.stringify({ text, ts: Date.now() }) + '\n', 'utf8')
+    return this._serialize(async () => {
+      await mkdir(dirname(this._file), { recursive: true })
+      await appendFile(this._file, JSON.stringify({ text, ts: Date.now() }) + '\n', 'utf8')
+    })
   }
 
   /**
@@ -100,34 +138,51 @@ export class RetryQueue {
    * @returns {Promise<string[]>}
    */
   async drain() {
-    const claim = `${this._file}.draining`
-    try {
-      await rename(this._file, claim)
-    } catch (e) {
-      // 큐 파일 없음(아직 실패 없음) 또는 다른 drain 이 이미 가로챔 → 처리할 것 없음.
-      if (/** @type {NodeJS.ErrnoException} */ (e)?.code === 'ENOENT') return []
-      throw e
-    }
-    const raw = await readFile(claim, 'utf8')
-    await rm(claim, { force: true })
-    /** @type {string[]} */
-    const texts = []
-    for (const line of raw.split('\n')) {
-      if (!line.trim()) continue
+    return this._serialize(async () => {
+      const claim = `${this._file}.draining`
       try {
-        const obj = JSON.parse(line)
-        if (typeof obj.text === 'string') texts.push(obj.text)
-      } catch {
-        // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
-        continue
+        await rename(this._file, claim)
+      } catch (e) {
+        // 큐 파일 없음(아직 실패 없음) 또는 다른 drain 이 이미 가로챔 → 처리할 것 없음.
+        if (/** @type {NodeJS.ErrnoException} */ (e)?.code === 'ENOENT') return []
+        throw e
+      }
+      const raw = await readFile(claim, 'utf8')
+      await rm(claim, { force: true })
+      const now = Date.now()
+      /** @type {Array<{ text: string, ts: number }>} */
+      let entries = []
+      for (const line of raw.split('\n')) {
+        if (!line.trim()) continue
+        try {
+          const obj = JSON.parse(line)
+          if (typeof obj.text === 'string') entries.push({ text: obj.text, ts: typeof obj.ts === 'number' ? obj.ts : now })
+        } catch {
+          // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
+          continue
+        }
+      }
+      // cap(H4) — maxAge 만료 + maxEntries 상한. 오래된 것부터 드롭(최신 보존). 드롭 수는 onDrop 으로 관측.
+      let dropped = 0
+      if (this._maxAgeMs > 0) {
+        const before = entries.length
+        entries = entries.filter((e) => now - e.ts <= this._maxAgeMs)
+        dropped += before - entries.length
+      }
+      if (this._maxEntries > 0 && entries.length > this._maxEntries) {
+        dropped += entries.length - this._maxEntries
+        entries = entries.slice(entries.length - this._maxEntries) // 최신 maxEntries 만 유지.
       }
-    }
-    return texts
+      if (dropped > 0 && this._onDrop) this._onDrop(dropped)
+      return entries.map((e) => e.text)
+    })
   }
 
-  /** 큐 파일 제거(테스트·정리용). @returns {Promise<void>} */
+  /** 큐 파일 제거(테스트·정리용, 직렬화됨). @returns {Promise<void>} */
   async clear() {
-    await rm(this._file, { force: true })
+    return this._serialize(async () => {
+      await rm(this._file, { force: true })
+    })
   }
 }
 

package/src/lib/logger/telegram-transport.js

@@ -61,6 +61,8 @@ export function httpsPost(url, body, { request = httpsRequestRaw, timeoutMs = 10
  * @param {string} [opts.retryDir] - retry queue 디렉터리(디폴트 './logs/telegram-retry').
  * @param {string} [opts.serviceName]
  * @param {number} [opts.retryDrainMs] - retry 드레인 주기(디폴트 30_000).
+ * @param {number} [opts.retryMaxEntries] - retry 큐 보관 최대 항목 수(디폴트 5000, 0=무제한, H4 cap).
+ * @param {number} [opts.retryMaxAgeMs] - retry 항목 최대 보존 ms(디폴트 24h, 0=무제한, H4 cap).
  * @param {(url: string, body: string) => Promise<{ statusCode: number }>} [opts.httpsRequest] - HTTP 주입(기본=httpsPost). 단위 테스트용 seam(ADR-165 동일 패턴) — pino worker 는 미전달.
  * @returns {import('node:stream').Writable}
  */
@@ -73,10 +75,20 @@ export default function telegramTransport(opts) {
     retryDir = './logs/telegram-retry',
     serviceName = 'mega',
     retryDrainMs = 30_000,
+    retryMaxEntries = 5000,
+    retryMaxAgeMs = 86_400_000,
     httpsRequest = httpsPost,
   } = opts
   const throttle = createThrottle(throttleMax, throttleWindowMs)
-  const queue = new RetryQueue(join(retryDir, 'telegram-retry.jsonl'))
+  /** throttle 로 드롭된 메시지 수(폭주 억제) — 주기적으로 관측 노출(silent 드롭 사각 제거). */
+  let droppedByThrottle = 0
+  // retry queue cap(H4) — 무한 디스크/메모리 증가 방지. cap 드롭은 stderr 로 관측(텔레그램 sink 라
+  // logger 재귀를 피해 process.stderr 직접 사용).
+  const queue = new RetryQueue(join(retryDir, 'telegram-retry.jsonl'), {
+    maxEntries: retryMaxEntries,
+    maxAgeMs: retryMaxAgeMs,
+    onDrop: (n) => process.stderr.write(`[telegram-transport] dropped ${n} stale/over-cap retry entries (H4 cap)\n`),
+  })
 
   /** 한 건 전송 시도 — 실패/throw 시 retry queue 로. */
   async function trySend(/** @type {string} */ text) {
@@ -92,6 +104,11 @@ export default function telegramTransport(opts) {
   // 주기 드레인 — 쌓인 실패분을 재전송(여전히 실패하면 다시 큐로). unref 로 프로세스 종료 막지 않음.
   /** @returns {Promise<void>} 쌓인 실패분 재전송(여전히 실패하면 trySend 가 다시 큐로). */
   const drainTick = async () => {
+    // throttle 로 조용히 드롭된 수를 주기적으로 노출(관측 사각 제거, Med). stderr 직접(logger 재귀 회피).
+    if (droppedByThrottle > 0) {
+      process.stderr.write(`[telegram-transport] throttled-dropped ${droppedByThrottle} messages in last window\n`)
+      droppedByThrottle = 0
+    }
     const pending = await queue.drain().catch(() => /** @type {string[]} */ ([]))
     for (const text of pending) await trySend(text)
   }
@@ -113,7 +130,10 @@ export default function telegramTransport(opts) {
         } catch {
           continue // 손상 라인 skip — 다음 라인 계속.
         }
-        if (!throttle.tryAcquire(Date.now())) continue // 폭주 억제(초과분 드롭).
+        if (!throttle.tryAcquire(Date.now())) {
+          droppedByThrottle++ // 폭주 억제(초과분 드롭) — 수를 세어 drainTick 에서 관측 노출.
+          continue
+        }
         void trySend(formatMessage(record, serviceName))
       }
       cb()

package/src/lib/mega-job-queue.js

@@ -62,6 +62,19 @@ const NOT_FOUND_CODE = '404'
 /** DLQ 스트림 `max_age` 디폴트(ms) — 7일. 무한 적재 방지(ADR-134). `dlqMaxAgeMs: 0` 으로 끌 수 있다. */
 export const DEFAULT_DLQ_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
+/** DLQ 봉투에 싣는 error.stack 최대 길이(자) — poison 잡 폭주 시 DLQ 비대 방지(Med). */
+const DLQ_MAX_STACK_LEN = 4000
+
+/**
+ * DLQ 봉투용 stack 문자열을 상한으로 자른다. 초과 시 말미에 잘림 표식을 붙인다.
+ * @param {string | undefined} stack
+ * @returns {string | undefined}
+ */
+function truncateStack(stack) {
+  if (typeof stack !== 'string' || stack.length <= DLQ_MAX_STACK_LEN) return stack
+  return stack.slice(0, DLQ_MAX_STACK_LEN) + `\n… [truncated ${stack.length - DLQ_MAX_STACK_LEN} chars]`
+}
+
 /**
  * @typedef {Object} MegaJobQueueOptions
  * @property {import('nats').NatsConnection} nc - **연결된** NatsConnection(`ctx.bus(alias).native`).
@@ -387,6 +400,11 @@ export class MegaJobQueue extends EventEmitter {
    * (소비 워커 라이프사이클·bus 별명 배선은 `MegaJobWorker` 영역 — 본 메서드는 "처리 베이스".
    * 정본 `MegaWorker` = CPU `worker_threads` 풀로 별개 추상(ADR-120/ADR-121).)
    *
+   * ⚠️ **head-of-line blocking 운영 주의(Med)**: in-flight 상한은 `concurrency`(= `max_ack_pending`)다.
+   * 일시 장애로 **모든 in-flight 가 동시에 긴 백오프**(`static backoff.max` 큼 + `retries` 많음)에 들어가면
+   * 그 subject 처리량이 0 에 수렴하고 정상 메시지도 뒤에서 대기한다(메모리는 안전 — 무한 증가 X). 큰
+   * backoff 를 쓰면 `concurrency` 를 충분히 키우고, 재시도 적체를 메트릭(`job:start`/`fail` 이벤트)으로 관측하라.
+   *
    * @param {typeof MegaJob} JobClass @param {MegaJob} instance - `run` 호출 대상(서브클래스 인스턴스).
    * @param {Record<string, any>} ctx - run 에 넘길 컨텍스트.
    * @returns {Promise<{ stop: () => Promise<void> }>}
@@ -489,9 +507,11 @@ export class MegaJobQueue extends EventEmitter {
     this.#safeEmit('start', { subject, seq })
     let settled = false
     // 재시도 동안 메시지를 점유하므로 ack_wait 만료(→중복 재전달)를 막기 위해 working() 으로 lease 갱신.
+    // unref — in-flight 잡이 길게 돌아도 이 타이머가 프로세스 자연 종료를 막지 않게(형제 모듈 정합, Med).
     const heartbeat = setInterval(() => {
       if (!settled) msg.working()
     }, this.#heartbeatMs)
+    if (typeof heartbeat.unref === 'function') heartbeat.unref()
 
     // run(재시도) 결과를 변수에 담는다 — ack/DLQ(부작용) + emit 은 try/catch **밖**에서 처리한다(M-3·L-3).
     // 이유: emit('done')/emit('fail') 리스너가 throw 했을 때 run 의 catch 가 잡으면 성공 잡이 spurious
@@ -546,7 +566,8 @@ export class MegaJobQueue extends EventEmitter {
           originalSubject: subject,
           failedAt: new Date().toISOString(),
           deliveryCount: msg.info.deliveryCount,
-          error: { name: error.name, message: error.message, stack: error.stack },
+          // stack 전체를 봉투에 담으면 poison 잡 폭주 시 DLQ 직렬화 비용·디스크가 급증한다 → 상한으로 truncate(Med).
+          error: { name: error.name, message: error.message, stack: truncateStack(error.stack) },
           payload,
         }),
       )

package/src/lib/mega-logger.js

@@ -92,11 +92,49 @@ export function buildTargets(sinks, level) {
   return targets
 }
 
+/**
+ * 기본 시크릿 redact 경로(ADR-023, H2 보안). 사용자가 `logger.redact` 를 지정하지 않아도 **항상** 적용해
+ * 토큰·비밀번호·인증 헤더가 stdout/파일/텔레그램(외부 sink)으로 평문 유출되는 것을 막는다(CLAUDE.md P5).
+ * pino(fast-redact) 경로 문법으로 부팅 시 1회 검증됨(leading wildcard `*.x` 포함). 사용자 redact 는 병합된다.
+ * @type {ReadonlyArray<string>}
+ */
+export const DEFAULT_REDACT_PATHS = Object.freeze([
+  'req.headers.authorization',
+  'req.headers.cookie',
+  '*.password',
+  '*.token',
+  '*.secret',
+  '*.accessToken',
+  '*.refreshToken',
+  '*.apiKey',
+])
+
+/**
+ * 사용자 redact 설정(배열 또는 `{ paths, censor?, remove? }`)을 기본 경로와 **병합**한다(중복 제거).
+ * 사용자가 미지정이어도 기본 경로는 항상 적용된다.
+ * @param {unknown} userRedact
+ * @returns {{ paths: string[], censor?: any, remove?: boolean }}
+ */
+function mergeRedact(userRedact) {
+  /** @type {string[]} */
+  let userPaths = []
+  /** @type {Record<string, any>} */
+  let extra = {}
+  if (Array.isArray(userRedact)) {
+    userPaths = userRedact.filter((p) => typeof p === 'string')
+  } else if (userRedact && typeof userRedact === 'object' && Array.isArray(/** @type {any} */ (userRedact).paths)) {
+    const { paths, ...rest } = /** @type {any} */ (userRedact)
+    userPaths = paths.filter((/** @type {any} */ p) => typeof p === 'string')
+    extra = rest // censor/remove 보존.
+  }
+  return { paths: [...new Set([...DEFAULT_REDACT_PATHS, ...userPaths])], ...extra }
+}
+
 /**
  * `logger` config → pino 옵션(또는 비활성 시 `null`). Fastify `logger` 또는 `pino()` 에 그대로 전달 가능.
  *
  * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact?, includeRequestId? }`).
- * @returns {{ level: string, mixin: Function, redact?: string[], transport: { targets: any[] } } | null}
+ * @returns {{ level: string, mixin: Function, redact: { paths: string[] }, transport: { targets: any[] } } | null}
  */
 export function buildLoggerOptions(config) {
   if (!config || typeof config !== 'object') return null
@@ -109,7 +147,8 @@ export function buildLoggerOptions(config) {
     level,
     // trace_id/span_id 자동 주입(ADR-116) — 활성 span 없으면 빈 객체(0 비용).
     mixin: MegaTracing.logMixin,
-    ...(Array.isArray(c.redact) && c.redact.length > 0 ? { redact: c.redact } : {}),
+    // 기본 시크릿 redact 를 **항상** 적용 + 사용자 설정 병합(H2 보안). 미지정이어도 마스킹된다.
+    redact: mergeRedact(c.redact),
     transport: { targets },
   }
 }

package/src/lib/mega-shutdown.js

@@ -31,6 +31,12 @@ let isShuttingDownFlag = false
 let gracePeriodMs = 30_000
 let hardKillMs = 60_000
 let exitedHandlers = new Set()
+/** 전역 에러 핸들러 등록 여부 + 참조(reset 시 removeListener 용). @type {boolean} */
+let globalErrorsRegistered = false
+/** @type {((reason: unknown) => void) | null} */
+let unhandledRejectionHandler = null
+/** @type {((err: Error, origin?: string) => void) | null} */
+let uncaughtExceptionHandler = null
 
 /**
  * cleanup hook 등록. 순서는 등록 역순(LIFO)으로 실행.
@@ -74,8 +80,9 @@ function isShuttingDown() {
 }
 
 /**
- * SIGTERM/SIGINT 시그널 등록 (한 번만 등록됨).
- * @param {{ gracePeriodMs?: number, hardKillMs?: number, signals?: string[] }} [opts]
+ * SIGTERM/SIGINT 시그널 등록 (한 번만 등록됨). 전역 에러 핸들러(unhandledRejection/uncaughtException)도
+ * 기본 등록한다 — `globalErrorHandlers: false` 로 끌 수 있다(REPL 등).
+ * @param {{ gracePeriodMs?: number, hardKillMs?: number, signals?: string[], globalErrorHandlers?: boolean }} [opts]
  */
 function setupSignals(opts = {}) {
   if (signalsRegistered) return   // 멱등성
@@ -88,6 +95,36 @@ function setupSignals(opts = {}) {
       void now({ signal: sig, exitCode: 0 })
     })
   }
+  // 전역 에러 핸들러도 함께 등록(opt-out: globalErrorHandlers === false). REPL(console-cmd) 등은 끌 수 있다.
+  if (opts.globalErrorHandlers !== false) setupGlobalErrorHandlers()
+}
+
+/**
+ * 전역 `unhandledRejection`/`uncaughtException` 핸들러 등록 (ADR-178, 멱등). floating promise reject 나
+ * 미처리 예외로 프로세스가 **graceful 없이 즉사**(어댑터 disconnect·드레인 미실행 → 커넥션/락 누수, 진행 중
+ * 잡 유실)하는 것을 막는다. 둘 다 fatal 로깅 후 graceful shutdown(exit 1)을 트리거한다 — uncaughtException
+ * 이후의 프로세스 상태는 신뢰 불가라 복구하지 않고 정리 후 종료가 표준.
+ * @param {{ exitCode?: number }} [opts]
+ * @returns {void}
+ */
+function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
+  if (globalErrorsRegistered) return
+  globalErrorsRegistered = true
+  unhandledRejectionHandler = (reason) => {
+    const log = /** @type {any} */ (globalThis).logger
+    const err = reason instanceof Error ? reason : new Error(`unhandledRejection: ${String(reason)}`)
+    if (log?.fatal) log.fatal({ err }, 'unhandledRejection — initiating graceful shutdown')
+    else console.error('[mega-shutdown] unhandledRejection — initiating graceful shutdown:', err)
+    void now({ signal: 'unhandledRejection', exitCode })
+  }
+  uncaughtExceptionHandler = (err, origin) => {
+    const log = /** @type {any} */ (globalThis).logger
+    if (log?.fatal) log.fatal({ err, origin }, 'uncaughtException — initiating graceful shutdown')
+    else console.error('[mega-shutdown] uncaughtException — initiating graceful shutdown:', err, origin)
+    void now({ signal: 'uncaughtException', exitCode })
+  }
+  process.on('unhandledRejection', unhandledRejectionHandler)
+  process.on('uncaughtException', uncaughtExceptionHandler)
 }
 
 /**
@@ -159,6 +196,12 @@ function _reset() {
   gracePeriodMs = 30_000
   hardKillMs = 60_000
   exitedHandlers = new Set()
+  // 전역 에러 핸들러도 떼어 테스트 간 누적 방지.
+  if (unhandledRejectionHandler) process.removeListener('unhandledRejection', unhandledRejectionHandler)
+  if (uncaughtExceptionHandler) process.removeListener('uncaughtException', uncaughtExceptionHandler)
+  unhandledRejectionHandler = null
+  uncaughtExceptionHandler = null
+  globalErrorsRegistered = false
 }
 
 /**
@@ -170,6 +213,7 @@ export const MegaShutdown = {
   unregister,
   isShuttingDown,
   setupSignals,
+  setupGlobalErrorHandlers,
   now,
   registeredCount,
   _reset,