mega-framework 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.2"
+  version "0.1.3"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

package/src/adapters/file-adapter.js

@@ -6,6 +6,11 @@
  * 같은 `get/set/del/has` API 를 로컬 파일로 만족시킨다 — driver 키 한 줄만 바꿔 환경 전환(ADR-082).
  * **신규 의존성 0** (`node:fs/promises`/`node:path`/`node:crypto` 표준만).
  *
+ * ⚠️ **만료 파일 능동 정리 없음(디스크 증가 주의)**: 만료 envelope 은 **재접근(get/has) 시에만 lazy 삭제**된다.
+ * set 후 다시 조회되지 않는 만료 키는 파일로 영구 잔존하므로, **짧은 TTL + 높은 키 카디널리티**(요청별 캐시 키
+ * 등) 워크로드에선 디스크/inode 가 누적될 수 있다. 그래서 file 캐시는 **dev / 단일·단명 인스턴스 권장**이며,
+ * 프로덕션 장기 구동에는 redis 캐시 또는 외부 정리(cron unlink)를 전제로 한다(능동 sweep 은 후속 과제).
+ *
  * # 표준 표면 (MegaCacheAdapter 상속)
  *   - `_connect()`   — `fs.mkdir(basePath, { recursive: true })` 로 디렉토리 보장.
  *   - `_disconnect()`— no-op (파일시스템은 close 개념 없음).

package/src/adapters/mega-cache-adapter.js

@@ -3,8 +3,12 @@
  * MegaCacheAdapter — key-value 캐시 표준 인터페이스 (추상, 08-class-specs §3.4).
  *
  * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
- * `MegaFileAdapter` (ADR-082). 사용자 `key` 에 자동 prefix
- * `mega:cache:<appName>:<key>` 가 코어에서 부착됨 (ADR-064).
+ * `MegaFileAdapter` (ADR-082).
+ *
+ * ⚠️ **키 네임스페이스(ADR-064)**: ADR-064 가 `mega:cache:<appName>:<key>` 자동 prefix 를 *결정*했으나
+ * **현재 코어에 미구현**이다(get/set/del 이 raw `key` 를 그대로 사용). 멀티앱이 같은 redis 를 공유하면
+ * 키 충돌 위험이 있으니, **현재는 사용자가 키에 앱별 네임스페이스를 직접 붙여야 한다**. 자동 prefix 구현은
+ * 후속 과제(ADR-064 open). 단일앱(현 sample)에선 무관.
  *
  * @module adapters/mega-cache-adapter
  */

package/src/adapters/nats-adapter.js

@@ -295,11 +295,16 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    * 잡 처리 등록 — **queue group** 구독(같은 queue 구독자끼리 load-balance). 기본 queue 이름은 jobName
    * (같은 잡의 모든 워커가 한 그룹).
    *
+   * ⚠️ **전달 보장 = at-most-once(비영속, H5)**: 이건 **core NATS** queue group 이라 메시지가 디스크에
+   * 남지 않는다 — 구독자가 없거나 처리 중 죽으면 그 메시지는 **유실**된다(재시도·DLQ 없음). 유실이
+   * 치명적이거나 영속 큐/재시도/DLQ 가 필요하면 **`MegaJobQueue`(JetStream, at-least-once, ADR-028/112)**
+   * 를 쓴다. `ctx.bus(x).process` 와 `mega worker`(JetStream) 는 **전달 보장이 다르므로 혼용 금지**.
+   *
    * **subscription 핸들을 반환하지 않는 건 의도적**(L-2): worker 는 앱 수명 동안 상주하는 것이
    * 정상이고(개별 잡 처리 등록을 런타임에 떼었다 붙였다 하는 패턴은 비표준), 정리는 disconnect 시
    * `_disconnect()` 의 `nc.drain()` 이 **모든 구독을 일괄 비우며** 처리한다. 개별 unsubscribe 가
    * 필요한 일시 구독은 `subscribe()`(핸들 반환)를 쓴다 — `process` 는 fire-and-forget `enqueue` 와
-   * 대칭인 상주 worker 용이다. 영속 큐/재시도/DLQ 가 필요하면 `MegaJob`(jetstream, ADR-028).
+   * 대칭인 상주 worker 용이다.
    *
    * @param {string} jobName
    * @param {(payload: any) => any} handler

package/src/cli/commands/console-cmd.js

@@ -30,7 +30,7 @@ function defaultReplFactory() {
  * @param {(msg: string) => void} [deps.out]
  * @param {() => (Promise<void> | void)} [deps.shutdown] - 주입용(테스트). REPL 종료 시 호출하는 graceful
  *   shutdown 트리거. 기본 {@link MegaShutdown.now}(등록 hook 실행 후 process.exit).
- * @param {(opts: { signals?: string[] }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
+ * @param {(opts: { signals?: string[], globalErrorHandlers?: boolean }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
  *   기본 {@link MegaShutdown.setupSignals}.
  * @returns {Promise<{ ctx: Record<string, any>, config: object, server: { context: Record<string, any> } }>}
  */
@@ -44,7 +44,9 @@ export async function startConsole(
   // 두면 REPL 종료 후에도 열린 핸들(DB 풀·redis·wsHub listen)로 프로세스가 행하고 어댑터가 미정리된다.
   // 따라서 SIGTERM 은 graceful shutdown 으로 받는다. SIGINT 은 REPL 이 소유(빈 줄 클리어 / 이중 입력 시
   // 'exit')하므로 가로채지 않는다 — 가로채면 한 번의 Ctrl-C 가 콘솔을 죽인다(ADR-167).
-  setupSignals({ signals: ['SIGTERM'] })
+  // REPL 은 전역 에러 핸들러를 끈다(globalErrorHandlers:false) — 대화형에서 사용자 코드 예외가
+  // 프로세스를 graceful shutdown 시키면 안 되고, REPL 자체 에러 복구를 방해하지 않기 위함(ADR-178).
+  setupSignals({ signals: ['SIGTERM'], globalErrorHandlers: false })
   const server = replFactory()
   Object.assign(server.context, { ctx, config: global, mega: { config: global, host } })
   // REPL 종료(.exit / Ctrl-D / 이중 Ctrl-C)는 'exit' 이벤트로 온다 — 이때 graceful shutdown 으로 어댑터 등을

package/src/core/mega-app.js

@@ -968,9 +968,9 @@ export class MegaApp {
     }
     // redis(cluster-wide) — 다른 워커/허브의 세션까지.
     if (this._wsRoster) {
-      for (const ch of want) {
-        for (const m of await this._wsRoster.list(ch)) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
-      }
+      // 여러 채널 redis 조회를 **병렬화**(Promise.all) — onConnect 핫패스의 직렬 라운드트립 누적 제거(Med).
+      const lists = await Promise.all([...want].map((ch) => this._wsRoster.list(ch)))
+      for (const list of lists) for (const m of list) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
     }
     return [...out.values()]
   }
@@ -1259,6 +1259,14 @@ export class MegaApp {
       this._hubBridgeId = null
       MegaShutdown.unregister(`mega-hublink:${this.name}`)
     }
+    // NATS 클러스터 정리(ADR-176) — 구독·heartbeat/sweep 타이머·roster 멤버 해제. boot 의 shutdown hook 과
+    // **양쪽**에서 정리해야 시그널을 안 거치는 종료(server.close()/프로그램적 재시작/멀티앱 부분 종료)에서도
+    // 누수가 없다(_hubLink/_wsRoster 와 동일 대칭, H1). stop() 은 _isStarted 가드로 멱등이라 중복 안전.
+    if (this._wsCluster) {
+      await this._wsCluster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-cluster stop failed'))
+      this._wsCluster = null
+      MegaShutdown.unregister(`mega-ws-cluster:${this.name}`)
+    }
     // redis roster 정리(ADR-177) — heartbeat 중지 + 로컬 멤버 즉시 제거. _sessionConns 를 비우기 **전에**
     // 호출해야 stop() 이 localRosterMembers 로 자기 멤버를 redis 에서 뺄 수 있다.
     if (this._wsRoster) {

package/src/core/mega-cluster.js

@@ -50,10 +50,16 @@ export class MegaCluster {
     /** @type {(() => Promise<void>) | null} */
     this._workerFn = null
 
-    // M1 — respawn backoff (crash-loop 보호)
-    this._respawnTooFast = 0          // 빠른 연속 crash 카운터
-    this._maxRapidRespawn = 5         // 5번 연속 너무 빨리 crash 하면 중단
-    this._minRespawnIntervalMs = 1000 // 1초 이내 crash 는 "너무 빠름"
+    // M1 — respawn backoff (crash-loop 보호). 멀티워커 정확성: 전역 카운터 + 정상종료-리셋은 한 워커의
+    // 정상 종료가 다른 워커들의 누적 빠른-crash 카운트를 통째로 지워 crash-loop 를 마스킹한다. 그래서
+    // **빠른 crash 타임스탬프의 슬라이딩 윈도우**로 판정한다(윈도우 내 N회 → 포기). 정상 종료는 카운트에
+    // 기여하지 않고, 오래된 빠른-crash 는 윈도우에서 자연 소거된다(안정화되면 자동 리셋).
+    this._maxRapidRespawn = 5         // 윈도우 내 5번 빠른 crash 면 중단
+    this._minRespawnIntervalMs = 1000 // 이 lifetime 미만 crash 는 "너무 빠름"
+    /** @type {number[]} 윈도우 내 빠른-crash 타임스탬프(ms). */
+    this._rapidCrashTimes = []
+    /** @type {ReturnType<typeof setTimeout>|null} SIGTERM grace 강제-kill 타이머(전원 정상종료 시 취소). */
+    this._graceTimer = null
   }
 
   /**
@@ -103,13 +109,15 @@ export class MegaCluster {
       this._shuttingDown = true
       console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
       this._broadcastShutdown()
-      // grace 초과 시 강제 kill
-      setTimeout(() => {
+      // grace 초과 시 강제 kill. 핸들을 보관해 전원 정상종료(exit 핸들러) 시 취소 — 정상 종료가 이 타이머의
+      // exit(1) 과 경합해 exit code 가 흔들리지 않게 한다(k8s/systemd 종료 판정 노이즈 제거).
+      this._graceTimer = setTimeout(() => {
         for (const w of this._workers) {
           try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
         }
         this._proc.exit(1)
-      }, this._gracePeriodMs).unref()
+      }, this._gracePeriodMs)
+      this._graceTimer.unref()
     }
     this._proc.on('SIGTERM', () => onSignal('SIGTERM'))
     this._proc.on('SIGINT', () => onSignal('SIGINT'))
@@ -124,33 +132,35 @@ export class MegaCluster {
       this._workers.delete(worker)
       if (this._shuttingDown) {
         if (this._workers.size === 0) {
+          if (this._graceTimer) clearTimeout(this._graceTimer) // 전원 정상종료 — 강제-kill 타이머 취소(exit code 경합 제거).
+          this._graceTimer = null
           console.log('[mega-cluster] all workers exited, primary exiting 0')
           this._proc.exit(0)
         }
         return
       }
       if (this._respawn) {
-        // M1 — respawn backoff: 너무 빨리 연속 crash 하면 crash-loop 으로 보고 respawn 중단.
+        // M1 — respawn backoff: 빠른 crash 의 슬라이딩 윈도우로 crash-loop 판정(멀티워커 정확).
         const now = Date.now()
         const lastBirth = worker._megaBirthAt ?? now
         const lifetimeMs = now - lastBirth
+        // 윈도우 = maxRapidRespawn 회의 빠른 재시작이 걸릴 시간 + 여유. 이보다 오래된 빠른-crash 는 소거.
+        const windowMs = this._minRespawnIntervalMs * this._maxRapidRespawn * 2
+        this._rapidCrashTimes = this._rapidCrashTimes.filter((t) => now - t < windowMs)
         if (lifetimeMs < this._minRespawnIntervalMs) {
-          this._respawnTooFast += 1
-          if (this._respawnTooFast >= this._maxRapidRespawn) {
-            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로
-            //   보인다 → systemd/k8s 가 "정상 종료" 로 판단해 재시작 안 함.
-            //   명시적 exit 1 로 "비정상 종료" 를 외부 supervisor 에 알려 재시작을 유도한다.
+          this._rapidCrashTimes.push(now) // 빠른 crash 만 윈도우에 기록(정상 lifetime 은 기여 X).
+          if (this._rapidCrashTimes.length >= this._maxRapidRespawn) {
+            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로 보인다 →
+            //   systemd/k8s 가 "정상 종료" 로 오판. 명시적 exit 1 로 비정상 종료를 알려 재시작을 유도한다.
             console.error(
-              `[mega-cluster] rapid crash-loop detected (${this._respawnTooFast} restarts within ${this._minRespawnIntervalMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+              `[mega-cluster] rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
             )
             this._proc.exit(1)
             return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
           }
-        } else {
-          this._respawnTooFast = 0   // 정상 lifetime 이면 카운터 reset
         }
         console.warn(
-          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crash-count=${this._respawnTooFast}/${this._maxRapidRespawn})`,
+          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
         )
         this._forkWorker()
       } else {

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)

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

@@ -76,16 +76,31 @@ const LEVEL_NAMES = /** @type {Record<number, string>} */ ({
  *   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
   }
 
   /**
@@ -134,19 +149,32 @@ export class RetryQueue {
       }
       const raw = await readFile(claim, 'utf8')
       await rm(claim, { force: true })
-      /** @type {string[]} */
-      const texts = []
+      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') texts.push(obj.text)
+          if (typeof obj.text === 'string') entries.push({ text: obj.text, ts: typeof obj.ts === 'number' ? obj.ts : now })
         } catch {
           // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
           continue
         }
       }
-      return texts
+      // 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 만 유지.
+      }
+      if (dropped > 0 && this._onDrop) this._onDrop(dropped)
+      return entries.map((e) => e.text)
     })
   }
 

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,