mega-framework 0.1.7 → 0.1.8

package/src/core/ws-upgrade.js

@@ -61,6 +61,104 @@ export const CLOSE_CODE_REQUEUE = 4503
 /** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
 export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES = 256 * 1024 * 1024
+
+/** 합산 budget 스윕 최소 간격(ms) — 매 send 마다 전 연결 O(N) 합산을 돌지 않게 하는 비용 상한. */
+const BUDGET_SWEEP_INTERVAL_MS = 250
+
+/** budget 추적 대상 연결 — driveWsConnection 경유 실연결만(직접 생성한 테스트 더블은 미추적). @type {Set<MegaWsConnection>} */
+const budgetConns = new Set()
+
+/** @type {number} 현재 합산 budget(바이트). Infinity = 옵트아웃. */
+let maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+
+/** @type {number} 마지막 budget 스윕 시각(epoch ms). */
+let lastBudgetSweepAt = 0
+
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max } = {}) {
+  if (max !== undefined) {
+    if (typeof max !== 'number' || Number.isNaN(max) || max < 0) {
+      throw new TypeError(`configureWsSendBudget: maxTotalBufferedBytes must be a non-negative number (0 = unlimited). Got ${max}`)
+    }
+    maxTotalBufferedBytes = max === 0 ? Infinity : max
+  }
+  return { maxTotalBufferedBytes }
+}
+
+/**
+ * 합산 budget 스윕 — 추적 중 전 연결의 `bufferedAmount` 를 합산해 budget 초과면 가장 큰 큐 보유
+ * 연결부터 종료한다. 스로틀({@link BUDGET_SWEEP_INTERVAL_MS}) 안쪽 재호출은 no-op(send 핫패스 보호).
+ * @param {number} [now] - epoch ms(테스트 주입용).
+ * @returns {void}
+ */
+function sweepWsSendBudget(now = Date.now()) {
+  if (now - lastBudgetSweepAt < BUDGET_SWEEP_INTERVAL_MS) return
+  lastBudgetSweepAt = now
+  if (budgetConns.size === 0 || maxTotalBufferedBytes === Infinity) return
+  let total = 0
+  for (const c of budgetConns) total += c._raw.bufferedAmount ?? 0
+  while (total > maxTotalBufferedBytes) {
+    /** @type {MegaWsConnection | null} */
+    let worst = null
+    for (const c of budgetConns) {
+      if (worst === null || (c._raw.bufferedAmount ?? 0) > (worst._raw.bufferedAmount ?? 0)) worst = c
+    }
+    const worstBytes = worst === null ? 0 : (worst._raw.bufferedAmount ?? 0)
+    if (worst === null || worstBytes === 0) break // 잔여가 전부 0 이면 더 회수할 게 없음(무한루프 차단).
+    budgetConns.delete(worst) // close 이벤트 전에 즉시 제외 — 같은 스윕 내 재선정 방지.
+    total -= worstBytes
+    try {
+      worst._raw.close(CLOSE_CODE_SLOW_CONSUMER, 'backpressure: process-wide send budget exceeded')
+    } catch {
+      // 이미 닫히는 중이면 close 는 무의미 — per-conn 가드와 동일 의미(비치명적). Set 에선 이미 제거됨.
+    }
+  }
+}
+
+/** budget 추적 등록(driveWsConnection 전용). @param {MegaWsConnection} conn @returns {void} */
+function trackWsSendBudget(conn) {
+  budgetConns.add(conn)
+}
+
+/** budget 추적 해제(연결 close 시). @param {MegaWsConnection} conn @returns {void} */
+function untrackWsSendBudget(conn) {
+  budgetConns.delete(conn)
+}
+
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget() {
+  budgetConns.clear()
+  lastBudgetSweepAt = 0
+  maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+}
+
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn) {
+  trackWsSendBudget(conn)
+}
+
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now) {
+  sweepWsSendBudget(now)
+}
+
 /**
  * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
  * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지
@@ -197,6 +295,10 @@ export class MegaWsConnection {
       }
       return
     }
+    // 프로세스 합산 budget 스윕(ADR-215) — per-conn cap 아래의 "다수의 느린 소비자" 합산 OOM 방어.
+    // 스로틀이 있어 핫패스 비용은 주기당 O(N) 1회. 스윕이 이 연결을 닫았으면(가장 큰 큐) 송신 생략.
+    sweepWsSendBudget()
+    if (this._raw.readyState !== undefined && this._raw.readyState !== 1) return
     // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
     const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
     const env = createWsMessage(withNs)
@@ -284,6 +386,8 @@ function buildWsPresence(app, conn, ns) {
  */
 export function driveWsConnection({ raw, req, route, app, codec, log, auth = null, protocolVersion = WS_PROTOCOL_VERSION }) {
   const conn = new MegaWsConnection(raw, codec, { ns: route.ns, path: route.path })
+  // 프로세스 합산 send budget 추적(ADR-215) — 실연결만 등록, close 에서 해제(아래 'close' 핸들러).
+  trackWsSendBudget(conn)
   // 협상된 envelope 버전 — 이 연결의 검증 기준이자 v2 도입 시 코덱/검증 분기의 기준점.
   conn.protocolVersion = protocolVersion
   // ChannelClass 는 부팅 시 MegaWebSocketController 상속 검증됨 (router.ws). 여기선 인스턴스화만.
@@ -400,6 +504,7 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
   }
 
   raw.on('close', (code, reasonBuf) => {
+    untrackWsSendBudget(conn)
     app._untrackWsConn?.(conn)
     const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
     log.debug?.({ connId: conn.id, code, reason }, 'ws.disconnect')

package/src/lib/mega-circuit-breaker.js

@@ -72,8 +72,10 @@ export const CAPACITY_ERROR_CODE = 'ESEMLOCKED'
  * @property {number} [resetTimeout=30000] - open 상태 유지 시간(ms). 경과 후 halfOpen 으로 1회 프로빙.
  * @property {number} [rollingCountTimeout=10000] - 실패율 집계 롤링 윈도우 길이(ms).
  * @property {number} [rollingCountBuckets=10] - 롤링 윈도우를 나누는 버킷 수.
- * @property {number} [volumeThreshold=0] - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
- *   (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+ * @property {number} [volumeThreshold=5] - 롤링 윈도우에 이 횟수만큼 호출이 쌓이기 전엔 실패율이
+ *   높아도 open 안 함(표본 부족 조기 trip 방지). 0=비활성. ⚠️ opossum 정본값(0)과 다른 프레임워크
+ *   디폴트 — 0 이면 부팅 직후/저빈도 호출에서 **첫 실패 1건**이 실패율 100% 가 돼 즉시 30s 차단되는
+ *   풋건이라 5 로 올렸다. opossum 원 동작이 필요하면 명시적으로 0 을 지정.
  * @property {number} [capacity] - 동시 진행(in-flight) 호출 상한. 초과분은 `ESEMLOCKED` 로 즉시 거부.
  *   미지정=무제한.
  * @property {(err: any, ...args: any[]) => boolean} [errorFilter] - `true` 반환 시 그 에러는 **실패로 집계하지 않음**
@@ -149,7 +151,7 @@ export class MegaCircuitBreaker {
       resetTimeout = 30_000,
       rollingCountTimeout = 10_000,
       rollingCountBuckets = 10,
-      volumeThreshold = 0,
+      volumeThreshold = 5, // opossum 정본(0)과 의도적으로 다름 — 단일 실패 즉시 open 풋건 방지.
       capacity,
       errorFilter,
       name,

package/src/lib/mega-health.js

@@ -45,6 +45,16 @@ export function register(name, fn, opts = {}) {
   checks.set(name, { fn, timeoutMs })
 }
 
+/**
+ * 등록된 체크 제거(이름 기준). 닫힌 자원(예: hub link)의 체크가 stale 클로저로 남지 않게
+ * 소유자가 register 와 짝맞춰 부른다.
+ * @param {string} name
+ * @returns {boolean} 제거됐으면 true(미등록 이름이면 false).
+ */
+export function unregister(name) {
+  return checks.delete(name)
+}
+
 /**
  * 모든 체크 실행 (병렬). 하나라도 false 면 전체 ok=false.
  * @returns {Promise<{ ok: boolean, checks: Record<string, { ok: boolean, error?: string, [key: string]: any }> }>}

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

@@ -91,6 +91,8 @@ function truncateStack(stack) {
  *   하트비트가 이 값의 절반마다 lease 를 갱신한다.
  * @property {number} [maxDeliver=5] - JetStream 최대 전달 횟수(워커 크래시 재전달 backstop).
  * @property {number} [heartbeatMs] - `working()` 전송 주기(ms). 기본 `max(1000, ackWaitMs/2)`.
+ *   양의 정수 + `< ackWaitMs` 필수(생성자 fail-fast) — 이상이면 lease 갱신이 늦어 정상 처리 중
+ *   중복 재전달, 0 이하면 working() 플러딩.
  * @property {string} [streamPrefix='MEGA_JOBS'] - 스트림 이름 접두사.
  * @property {number} [dlqMaxAgeMs=604800000] - DLQ 스트림 메시지 보존 기한(ms, 디폴트 7일). 초과한 실패
  *   잡은 NATS 가 자동 만료시킨다(무한 적재 방지, ADR-134). `0` 이면 무제한(끔 — 영구 보존). **신규 DLQ
@@ -135,6 +137,13 @@ export class MegaJobQueue extends EventEmitter {
   /** @type {import('nats').JetStreamClient|null} */ #js = null
   /** @type {import('nats').JetStreamManager|null} */ #jsm = null
   /** @type {Promise<void>|null} ensureReady 멱등 가드. */ #readyPromise = null
+  /**
+   * subject 별 ensureStream 멱등 캐시(#readyPromise 와 동일 패턴). 없으면 enqueue 가 매 호출
+   * `jsm.streams.info` RPC ×2(워크+DLQ)를 반복해 enqueue 비용의 2/3 가 존재 재확인에 낭비된다.
+   * 실패한 Promise 는 캐시에서 비워 다음 호출이 재시도하게 한다.
+   * @type {Map<string, Promise<void>>}
+   */
+  #ensuredStreams = new Map()
 
   /**
    * @param {MegaJobQueueOptions} options
@@ -164,6 +173,11 @@ export class MegaJobQueue extends EventEmitter {
     if (typeof runTimeoutMs !== 'number' || !Number.isInteger(runTimeoutMs) || runTimeoutMs < 0) {
       throw new TypeError(`MegaJobQueue: runTimeoutMs must be an integer >= 0 (0 = unlimited). Got: ${runTimeoutMs}.`)
     }
+    // heartbeatMs: working() lease 갱신 주기. ackWaitMs 이상이면 갱신이 늦어 정상 처리 중 lease 가
+    // 만료돼 중복 재전달(at-least-once 폭증)되고, 0 이하면 setInterval 1ms 클램프로 working() 플러딩.
+    if (heartbeatMs !== undefined && (typeof heartbeatMs !== 'number' || !Number.isInteger(heartbeatMs) || heartbeatMs < 1 || heartbeatMs >= ackWaitMs)) {
+      throw new TypeError(`MegaJobQueue: heartbeatMs must be a positive integer < ackWaitMs (${ackWaitMs}). Got: ${heartbeatMs}.`)
+    }
     this.#nc = nc
     this.#ackWaitMs = ackWaitMs
     this.#maxDeliver = maxDeliver
@@ -336,16 +350,30 @@ export class MegaJobQueue extends EventEmitter {
    * @param {typeof MegaJob} JobClass @returns {Promise<void>}
    */
   async ensureStream(JobClass) {
-    await this.ensureReady()
     const subject = this.#assertJobSubject(JobClass)
-    const nats = /** @type {typeof import('nats')} */ (this.#nats)
-    await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
-    // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
-    // dlqMaxBytes 미지정이면 max_bytes 미지정.
-    await this.#ensureStreamExists(this.#dlqStreamName(subject), [`${subject}.dlq`], nats.RetentionPolicy.Limits, {
-      maxAgeMs: this.#dlqMaxAgeMs,
-      maxBytes: this.#dlqMaxBytes,
-    })
+    // subject 별 1회만 실제 확인(RPC ×2) — 이후 호출은 캐시된 Promise 를 기다린다(동시 호출도 1회).
+    const cached = this.#ensuredStreams.get(subject)
+    if (cached) return cached
+    const ensured = (async () => {
+      await this.ensureReady()
+      const nats = /** @type {typeof import('nats')} */ (this.#nats)
+      await this.#ensureStreamExists(this.#workStreamName(subject), [subject], nats.RetentionPolicy.Workqueue)
+      // DLQ 스트림에 한도를 건다(무한 적재 방지, ADR-134). dlqMaxAgeMs=0 이면 max_age 미지정(무제한),
+      // dlqMaxBytes 미지정이면 max_bytes 미지정.
+      await this.#ensureStreamExists(this.#dlqStreamName(subject), [`${subject}.dlq`], nats.RetentionPolicy.Limits, {
+        maxAgeMs: this.#dlqMaxAgeMs,
+        maxBytes: this.#dlqMaxBytes,
+      })
+    })()
+    this.#ensuredStreams.set(subject, ensured)
+    try {
+      await ensured
+    } catch (err) {
+      // 실패는 캐시하지 않는다 — NATS 일시 장애 후 다음 enqueue/consume 이 재시도할 수 있게.
+      this.#ensuredStreams.delete(subject)
+      throw err
+    }
+    return ensured
   }
 
   /**
@@ -399,14 +427,26 @@ export class MegaJobQueue extends EventEmitter {
   }
 
   /**
-   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다.
-   * @param {typeof MegaJob} JobClass @param {any} payload @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
+   * 잡을 큐에 넣는다(JetStream publish — 서버에 영속 저장). 스트림이 없으면 만든다(subject 별 1회 확인 후 캐시).
+   *
+   * @param {typeof MegaJob} JobClass @param {any} payload
+   * @param {{ msgID?: string }} [opts] - `msgID` = JetStream `Nats-Msg-Id` dedup 키(옵트인). 스트림
+   *   duplicate window(NATS 기본 2분 — 운영자가 NATS CLI 로 스트림별 조정) 안의 같은 msgID 재발행은
+   *   적재되지 않고 `duplicate: true` 로 반환된다. 비즈니스 멱등키(주문 ID 등)를 권장. 미지정 시
+   *   dedup 없음 — `duplicate` 는 항상 false.
+   * @returns {Promise<{ seq: number, stream: string, duplicate: boolean }>}
    */
-  async enqueue(JobClass, payload) {
+  async enqueue(JobClass, payload, { msgID } = /** @type {{ msgID?: string }} */ ({})) {
+    if (msgID !== undefined && (typeof msgID !== 'string' || msgID.length === 0)) {
+      throw new TypeError(`MegaJobQueue.enqueue: msgID, if set, must be a non-empty string. Got: ${msgID}.`)
+    }
     await this.ensureStream(JobClass)
     const subject = /** @type {string} */ (JobClass.subject)
     const js = /** @type {import('nats').JetStreamClient} */ (this.#js)
-    const ack = await js.publish(subject, this.#encode(payload))
+    // msgID(옵트인) = JetStream `Nats-Msg-Id` dedup — 스트림 duplicate window(NATS 기본 2분) 안의
+    // 같은 msgID 재발행은 적재되지 않고 ack.duplicate=true 로 돌아온다(producer 중복: 재시도 enqueue·
+    // 이중 클릭 방어). 미지정 시 dedup 없음(기존 동작, 비용 0) — duplicate 는 그때 항상 false.
+    const ack = await js.publish(subject, this.#encode(payload), msgID !== undefined ? { msgID } : undefined)
     // dispatch 는 publish(부작용) 완료 후 발화 — 리스너 throw 가 반환값/흐름을 오염시키지 않게 safeEmit(L-3).
     this.#safeEmit('dispatch', { subject, seq: ack.seq, stream: ack.stream })
     return { seq: ack.seq, stream: ack.stream, duplicate: ack.duplicate }

package/src/lib/mega-job.js

@@ -73,7 +73,14 @@ export class MegaJob {
   /** @type {string|undefined} bus 별명(`ctx.bus(alias)`). 워커 배선이 nc 해석에 사용. */
   static bus = undefined
 
-  /** @type {number} 동시 처리 메시지 수(consumer max_ack_pending). 기본 1(순차·안전). */
+  /**
+   * @type {number} 동시 처리 메시지 수. 기본 1(순차·안전).
+   *
+   * ⚠️ 이 값은 durable consumer 의 `max_ack_pending` 으로 들어가므로 **워커 그룹(같은 subject 를
+   * 소비하는 모든 인스턴스) 전체의 합산 in-flight 상한**이다 — `mega worker` 인스턴스를 늘려도
+   * 합산 동시 처리는 이 값을 넘지 못한다. 처리량을 늘리려면 인스턴스 증설과 **함께** concurrency 를
+   * 키워야 한다(실측: c=1→c=32 에서 처리량 ~10배).
+   */
   static concurrency = 1
 
   /** @type {number} run 실패 시 **추가** 재시도 횟수(첫 시도 제외). 기본 3(OQ-012). */

package/src/lib/mega-metrics.js

@@ -36,6 +36,7 @@
  * @see https://opentelemetry.io/docs/specs/otel/metrics/ (OTel metrics)
  * @see https://prometheus.io/docs/instrumenting/exposition_formats/ (Prometheus 텍스트 포맷)
  */
+import { getHeapStatistics } from 'node:v8'
 import { MeterProvider } from '@opentelemetry/sdk-metrics'
 import { PrometheusExporter, PrometheusSerializer } from '@opentelemetry/exporter-prometheus'
 import { buildOtelResource } from './otel-resource.js'
@@ -547,7 +548,7 @@ function buildInstruments(meter) {
  */
 function registerSystemGauges(meter) {
   const memory = meter.createObservableGauge('mega_process_memory_bytes', {
-    description: '프로세스 메모리 사용량(바이트) — kind=rss|heap_used|heap_total|external 라벨.',
+    description: '프로세스 메모리 사용량(바이트) — kind=rss|heap_used|heap_total|external|array_buffers 라벨.',
     unit: 'By',
   })
   memory.addCallback((result) => {
@@ -556,6 +557,32 @@ function registerSystemGauges(meter) {
     result.observe(mu.heapUsed, { kind: 'heap_used' })
     result.observe(mu.heapTotal, { kind: 'heap_total' })
     result.observe(mu.external, { kind: 'external' })
+    // arrayBuffers 분리 노출(ADR-215, G5 M-5) — mongo driver 등 ArrayBuffer 상주분을 heap 과 구분해
+    // "RSS 만 보는" 관측 함정(burst 후 V8 페이지 미반환 = 정상 평형)을 운영자가 분해해 읽을 수 있게.
+    result.observe(mu.arrayBuffers ?? 0, { kind: 'array_buffers' })
+  })
+
+  // V8 힙 통계(ADR-215, G5 M-5) — heap_size_limit(OOM 한계)·total_available_size(여유)·physical 등
+  // process.memoryUsage 가 못 보여주는 V8 내부 수위. kind 는 고정 enum 이라 카디널리티 안전.
+  const V8_HEAP_KINDS = Object.freeze([
+    'total_heap_size',
+    'total_physical_size',
+    'total_available_size',
+    'used_heap_size',
+    'heap_size_limit',
+    'malloced_memory',
+    'peak_malloced_memory',
+    'external_memory',
+  ])
+  const v8Heap = meter.createObservableGauge('mega_v8_heap_bytes', {
+    description: `V8 힙 통계(바이트, v8.getHeapStatistics) — kind=${V8_HEAP_KINDS.join('|')} 라벨.`,
+    unit: 'By',
+  })
+  v8Heap.addCallback((result) => {
+    const hs = /** @type {Record<string, number>} */ (/** @type {unknown} */ (getHeapStatistics()))
+    for (const kind of V8_HEAP_KINDS) {
+      if (typeof hs[kind] === 'number') result.observe(hs[kind], { kind })
+    }
   })
 
   const uptime = meter.createObservableGauge('mega_process_uptime_seconds', {

package/src/lib/mega-plugin.js

@@ -62,12 +62,12 @@ const LIFECYCLE_EVENTS = /** @type {const} */ (['beforeBoot', 'afterBoot', 'befo
  * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
  */
 
-/** 빌트인 generator 13종 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+/** 빌트인 generator 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
  * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
  * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
 export const RESERVED_GENERATOR_NAMES = new Set([
   'app', 'controller', 'channel', 'service', 'model', 'middleware', 'route',
-  'schedule', 'job', 'worker', 'locale', 'adapter', 'migration',
+  'schedule', 'job', 'worker', 'locale', 'adapter', 'migration', 'adr',
 ])
 
 /**

package/src/lib/mega-worker.js

@@ -16,7 +16,9 @@
  *     프로세스 메모리 격리), process=`child_process.fork`(완전 격리, 더 무거움). 둘 다 node 빌트인(의존성 0).
  *   - **풀 정책** — `static poolSize`(디폴트 `os.cpus().length - 1`, 최소 1). 작업 큐 + 가용 워커에 디스패치.
  *   - **crash 자동 재시작** — 워커가 예기치 않게 죽으면 in-flight task 를 `worker.crashed` 로 reject 하고
- *     `static maxRestarts`(디폴트 5)까지 교체 워커를 띄운다(MegaJobWorker M-1 패턴 정합).
+ *     `static maxRestarts`(디폴트 5)/`static restartWindowMs`(디폴트 60s) **슬라이딩 윈도우** 안에서만
+ *     교체 워커를 띄운다 — 윈도우 내 한도 초과 = crash-loop 으로 보고 포기(MegaCluster 정책 통일).
+ *     산발 crash(윈도우 밖)는 한도를 소모하지 않아 장수 프로세스의 풀이 영구 축소되지 않는다.
  *   - **graceful shutdown** — `stop()`: 새 `run()` 거부 + 큐 대기분 `worker.stopped` reject + in-flight 완료
  *     대기(allSettled) → 워커 terminate. `MegaShutdown` 통합은 workers-manager 가 배선.
  *
@@ -57,6 +59,14 @@ const DEFAULT_POOL_SIZE = Math.max(1, os.cpus().length - 1)
 /** crash 시 풀 전체에서 허용하는 교체 워커 재시작 총량 디폴트. */
 const DEFAULT_MAX_RESTARTS = 5
 
+/**
+ * crash 교체 판정 윈도우 기본값(ms) — 60초. `maxRestarts` 는 이 윈도우 **안의** 교체 횟수 상한이다
+ * (수명 누적이 아님). 누적 카운터면 몇 주 간격의 산발 crash 도 한도를 소모해 장수 프로세스의 풀이
+ * 영구 축소되다 `pool_exhausted` 로 죽는다 — crash-loop(즉시 연속 사망)만 막으면 되는 안전망이므로
+ * 시간 윈도우 판정이 맞다(MegaCluster 의 rapid-crash 슬라이딩 윈도우와 정책 통일).
+ */
+const DEFAULT_RESTART_WINDOW_MS = 60_000
+
 /**
  * @typedef {object} WorkerHandle - 풀 안의 워커 1개 핸들.
  * @property {number} id - 핸들 식별자(로그/디버그).
@@ -94,7 +104,8 @@ export class MegaWorker extends EventEmitter {
   /** @type {boolean} */ #stopping = false
   /** @type {number} */ #nextTaskId = 1
   /** @type {number} */ #nextHandleId = 1
-  /** @type {number} crash 교체 누적. */ #restarts = 0
+  /** @type {number[]} crash 교체 시각(epoch ms) 슬라이딩 윈도우 — restartWindowMs 밖은 판정 시 제거. */
+  #restartTimes = []
   /** @type {number} 진행 중인 교체 spawn 수(일시적 풀 0 상태에서 run 을 큐잉할지 판단). */ #pendingRespawns = 0
 
   /**
@@ -130,12 +141,18 @@ export class MegaWorker extends EventEmitter {
     return typeof p === 'number' ? p : DEFAULT_POOL_SIZE
   }
 
-  /** @returns {number} crash 교체 허용 총량. */
+  /** @returns {number} 윈도우({@link MegaWorker#restartWindowMs}) 내 crash 교체 허용 횟수. */
   get maxRestarts() {
     const r = /** @type {any} */ (this.constructor).maxRestarts
     return Number.isInteger(r) && r >= 0 ? r : DEFAULT_MAX_RESTARTS
   }
 
+  /** @returns {number} crash 교체 판정 슬라이딩 윈도우(ms). `static restartWindowMs` 로 조정. */
+  get restartWindowMs() {
+    const w = /** @type {any} */ (this.constructor).restartWindowMs
+    return Number.isInteger(w) && w > 0 ? w : DEFAULT_RESTART_WINDOW_MS
+  }
+
   /** @returns {boolean} start() 후 stop() 전이면 true. */
   get isStarted() {
     return this.#started
@@ -511,8 +528,14 @@ export class MegaWorker extends EventEmitter {
    * @returns {void}
    */
   #scheduleRespawn() {
-    if (this.#stopping || this.#restarts >= this.maxRestarts) return
-    this.#restarts++
+    if (this.#stopping) return
+    // 슬라이딩 윈도우 판정 — 윈도우 밖 기록을 비우고 남은 횟수가 한도면 crash-loop 으로 보고 포기.
+    // (수명 누적이 아니라서 산발 crash 는 풀을 영구 축소시키지 않는다 — MegaCluster 정책 통일.)
+    const now = Date.now()
+    const windowStart = now - this.restartWindowMs
+    this.#restartTimes = this.#restartTimes.filter((t) => t >= windowStart)
+    if (this.#restartTimes.length >= this.maxRestarts) return
+    this.#restartTimes.push(now)
     this.#pendingRespawns++
     this.#spawn()
       .then((h) => {

package/src/lib/ws-hub.js

@@ -103,7 +103,7 @@ export class MegaWsHub {
     this._wss = null
     /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
     this._livenessTimer = null
-    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number }>} */
+    /** 등록된 bridge 연결. connId → { socket, lastSeen, protocolVersion, presenceFanout }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number, protocolVersion?: number, presenceFanout?: boolean }>} */
     this._bridges = new Map()
     /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
     this._sessions = new Map()
@@ -111,6 +111,13 @@ export class MegaWsHub {
     this._channelSessions = new Map()
     /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
     this._userSessions = new Map()
+    /**
+     * 역인덱스: channel → (bridgeConnId → 그 bridge 의 채널 내 세션 수). BROADCAST 의 bridge 선정을
+     * 세션 수 무관 O(bridge 수)로 만든다 — 멤버 10k 채널에서 메시지당 수백 µs 가 µs 대로 떨어진다.
+     * `_addSession`/`_removeSession` 이 증분 유지(카운트 0 → 키 제거), 메모리는 채널×bridge 수준.
+     * @type {Map<string, Map<string, number>>}
+     */
+    this._channelBridges = new Map()
   }
 
   /** hub 식별자. */
@@ -170,6 +177,20 @@ export class MegaWsHub {
     let isRegistered = false
     this._log?.debug?.({ connId }, 'ws-hub connection (awaiting register)')
 
+    // 미등록 연결 register 타임아웃 — liveness(_checkLiveness)는 등록된 bridge 만 스캔하므로,
+    // REGISTER 를 안 보내는 연결(오설정 bridge·포트 스캐너·half-open)은 이 타이머가 없으면
+    // fd/메모리로 영구 잔존한다. heartbeatMs 안에 등록 못 하면 1008 로 닫는다(fail-closed).
+    const registerTimer = setTimeout(() => {
+      if (isRegistered) return
+      this._log?.warn?.({ connId, timeoutMs: this._heartbeatMs }, 'ws-hub register timeout — closing unregistered connection (1008)')
+      try {
+        socket.close(1008, 'register timeout')
+      } catch (err) {
+        this._log?.debug?.({ err, connId }, 'ws-hub register-timeout close failed (already closing)')
+      }
+    }, this._heartbeatMs)
+    registerTimer.unref?.()
+
     socket.on('message', (raw) => {
       const frame = Array.isArray(raw) ? Buffer.concat(raw).toString('utf8') : raw.toString('utf8')
       let msg
@@ -196,12 +217,14 @@ export class MegaWsHub {
           return
         }
         isRegistered = this._handleRegister(connId, socket, msg)
+        if (isRegistered) clearTimeout(registerTimer)
         return
       }
       this._route(connId, socket, msg)
     })
 
     socket.on('close', () => {
+      clearTimeout(registerTimer) // 미등록 타임아웃 정리(등록 전 절단·정상 종료 공통).
       if (isRegistered) this._handleBridgeGone(connId)
       this._log?.debug?.({ connId }, 'ws-hub connection closed')
     })
@@ -234,7 +257,10 @@ export class MegaWsHub {
     const protocolVersion = hasVersionRequest
       ? negotiateHubProtocolVersion(payload.protocolVersion)
       : HUB_PROTOCOL_VERSION
-    this._bridges.set(connId, { socket, lastSeen: Date.now(), protocolVersion })
+    // presence fan-out 은 옵트인 — roster 가 redis 로 분리(ADR-177)된 뒤 bridge 는 JOIN/LEAVE/METADATA
+    // 를 no-op 으로 버리므로, `presence-fanout` capability 를 선언한 bridge 에만 보낸다(죽은 트래픽 제거).
+    const presenceFanout = Array.isArray(payload.capabilities) && payload.capabilities.includes('presence-fanout')
+    this._bridges.set(connId, { socket, lastSeen: Date.now(), protocolVersion, presenceFanout })
     this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId, protocolVersion }, 'ws-hub bridge registered')
     this._safeSend(socket, createHubMessage({
       type: T.REGISTER_OK,
@@ -262,12 +288,12 @@ export class MegaWsHub {
     switch (type) {
       case T.JOIN:
         this._addSession(connId, payload)
-        // 클러스터 presence 공유 — 다른 모든 bridge 에 같은 JOIN fan-out (07 §2).
-        this._fanOutToOthers(connId, msg)
+        // 클러스터 presence 공유 — `presence-fanout` 선언 bridge 에만 (07 §2 + ADR-177 후 죽은 트래픽 제거).
+        this._fanOutPresence(connId, msg)
         break
       case T.LEAVE: {
         const removed = this._removeSession(payload.sessionId)
-        if (removed) this._fanOutToOthers(connId, msg)
+        if (removed) this._fanOutPresence(connId, msg)
         break
       }
       case T.BULK_LEAVE: {
@@ -289,7 +315,7 @@ export class MegaWsHub {
         const session = this._sessions.get(payload.sessionId)
         if (session) {
           session.metadata = payload.metadata
-          this._fanOutToOthers(connId, msg) // presence 메타 동기화
+          this._fanOutPresence(connId, msg) // presence 메타 동기화 — 옵트인 bridge 만.
         }
         break
       }
@@ -360,6 +386,7 @@ export class MegaWsHub {
         this._channelSessions.set(ch, set)
       }
       set.add(entry.sessionId)
+      this._bumpChannelBridge(ch, connId, +1)
     }
     let uset = this._userSessions.get(entry.userId)
     if (!uset) {
@@ -369,6 +396,27 @@ export class MegaWsHub {
     uset.add(entry.sessionId)
   }
 
+  /**
+   * channel→bridge 역인덱스 증분 갱신. 카운트가 0 이 되면 키를 지워 인덱스가 stale 하지 않게 한다.
+   * @param {string} channel @param {string} connId @param {1|-1} delta
+   * @private
+   */
+  _bumpChannelBridge(channel, connId, delta) {
+    let counts = this._channelBridges.get(channel)
+    if (!counts) {
+      if (delta < 0) return // 제거인데 인덱스 없음 — 정합상 없을 일이지만 방어.
+      counts = new Map()
+      this._channelBridges.set(channel, counts)
+    }
+    const next = (counts.get(connId) ?? 0) + delta
+    if (next > 0) {
+      counts.set(connId, next)
+    } else {
+      counts.delete(connId)
+      if (counts.size === 0) this._channelBridges.delete(channel)
+    }
+  }
+
   /**
    * presence 에서 세션 제거. 빈 인덱스는 정리.
    * @param {string} sessionId
@@ -385,6 +433,7 @@ export class MegaWsHub {
         set.delete(sessionId)
         if (set.size === 0) this._channelSessions.delete(ch)
       }
+      this._bumpChannelBridge(ch, session.bridgeConnId, -1)
     }
     const uset = this._userSessions.get(session.userId)
     if (uset) {
@@ -415,7 +464,8 @@ export class MegaWsHub {
   }
 
   /**
-   * origin 을 제외한 모든 등록 bridge 로 송신 (presence 공유용). envelope 는 1회만 직렬화(L5).
+   * origin 을 제외한 모든 등록 bridge 로 송신. envelope 는 1회만 직렬화(L5).
+   * BULK_LEAVE(bridge-gone 정리 통지)처럼 전 bridge 가 받아야 하는 통지에 쓴다.
    * @param {string} exceptConnId
    * @param {Object} envelope
    * @private
@@ -427,6 +477,25 @@ export class MegaWsHub {
     }
   }
 
+  /**
+   * presence(JOIN/LEAVE/METADATA) fan-out — `presence-fanout` capability 를 선언한 bridge 에만 송신.
+   * roster 가 redis 로 분리(ADR-177)된 뒤 표준 bridge 는 이 타입들을 no-op 으로 버리므로, 옵트인하지
+   * 않은 bridge 에는 보내지 않는다 — 세션 churn × bridge 수 만큼의 죽은 프레임을 제거한다.
+   * 구버전 bridge 호환: hub presence 를 실제로 쓰려는 bridge 는 capability 로 명시 선언한다.
+   * @param {string} exceptConnId
+   * @param {Object} envelope
+   * @private
+   */
+  _fanOutPresence(exceptConnId, envelope) {
+    /** @type {string | null} 첫 대상에서 1회 직렬화(L5) — 대상 0 이면 직렬화도 안 함. */
+    let data = null
+    for (const [connId, bridge] of this._bridges) {
+      if (connId === exceptConnId || !(/** @type {any} */ (bridge).presenceFanout)) continue
+      if (data === null) data = JSON.stringify(envelope)
+      this._sendSerialized(bridge.socket, data)
+    }
+  }
+
   /**
    * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
    *
@@ -441,12 +510,24 @@ export class MegaWsHub {
    * @private
    */
   _fanOutChannel(channel, exceptConnId, envelope, exceptSessionIds) {
+    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+    if (!except) {
+      // 일반 경로(대부분의 메시지): channel→bridge 역인덱스로 선정이 O(bridge 수) — 세션 수 무관.
+      const counts = this._channelBridges.get(channel)
+      if (!counts || counts.size === 0) return
+      const data = JSON.stringify(envelope)
+      for (const connId of counts.keys()) {
+        if (connId !== exceptConnId) this._sendTo(connId, data)
+      }
+      return
+    }
+    // exceptSessionIds 경로(드묾): "제외 세션만 가진 bridge 통째 스킵" 판정에 세션 단위 정보가
+    // 필요하므로 기존 멤버 순회를 유지한다.
     const sids = this._channelSessions.get(channel)
     if (!sids) return
-    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
     const targets = new Set()
     for (const sid of sids) {
-      if (except && except.has(sid)) continue // 제외 세션은 bridge 선정에 기여하지 않음
+      if (except.has(sid)) continue // 제외 세션은 bridge 선정에 기여하지 않음
       const session = this._sessions.get(sid)
       if (session && session.bridgeConnId !== exceptConnId) targets.add(session.bridgeConnId)
     }

package/templates/adr/code.tpl

@@ -0,0 +1,23 @@
+---
+number: {{number}}
+title: {{title}}
+date: {{date}}
+status: accepted
+supersedes: []
+superseded_by: null
+tags: []
+---
+
+# ADR-{{number}}: {{title}}
+
+## Context
+
+(결정이 필요했던 배경 — 문제·제약·관련 ADR 링크)
+
+## Decision
+
+(무엇을 결정했는가 — 한 문장 요지 + 세부 사항)
+
+## Consequences
+
+(트레이드오프·후속 작업·영향 파일·검증 결과)