mega-framework 0.1.7 → 0.1.9

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
+
+(트레이드오프·후속 작업·영향 파일·검증 결과)

package/types/adapters/adapter-options.d.ts

@@ -65,6 +65,8 @@ export function normalizePool(pool: unknown, spec: Record<string, {
     key: string;
     divideBy?: number;
 } | null>, driver: string): Record<string, number>;
+/** pool acquire 대기 한도 프레임워크 디폴트(ms) — 명시 0 으로 드라이버 무한 대기 옵트인(ADR-216). */
+export const DEFAULT_ACQUIRE_TIMEOUT_MS: 10000;
 /**
  * pg 풀 매핑 — 값이 null 이면 미지원(throw), `{ key, divideBy? }` 면 키 이름 변경(+단위 변환).
  * @type {Record<string, { key: string, divideBy?: number } | null>}

package/types/adapters/file-adapter.d.ts

@@ -4,6 +4,8 @@
  * @property {string} [basePath] - 캐시 파일 저장 디렉토리 (필수).
  * @property {string} [dir] - `basePath` 의 별칭 (ADR-082 정합, 하위 호환).
  * @property {{ serializer?: 'json' | 'raw', extension?: string }} [options]
+ * @property {string} [namespace] - 캐시 키 자동 prefix `mega:cache:<namespace>:` (ADR-064/213, 베이스 처리).
+ * @property {number} [defaultTtlSec] - `set` ttl 미지정 시 디폴트(초). 0 = 무한 옵트인. (ADR-216, 베이스 처리)
  */
 /**
  * @typedef {object} CacheEnvelope - 디스크에 저장되는 단일 파일 포맷.
@@ -14,7 +16,8 @@
  */
 export class MegaFileAdapter extends MegaCacheAdapter {
     /**
-     * @param {FileConfig} [config] - services.caches.<key> 설정.
+     * @param {FileConfig} [config] - services.caches.<key> 설정. 베이스(MegaCacheAdapter)의
+     *   `namespace`(ADR-064 자동 prefix)/`defaultTtlSec`(ADR-216) 도 여기서 받는다.
      * @throws {MegaValidationError} `adapter.basepath_required` - basePath/dir 누락.
      * @throws {MegaValidationError} `adapter.invalid_option` - 옵션 타입/미지원 키 오류.
      */
@@ -69,6 +72,14 @@ export type FileConfig = {
         serializer?: "json" | "raw";
         extension?: string;
     };
+    /**
+     * - 캐시 키 자동 prefix `mega:cache:<namespace>:` (ADR-064/213, 베이스 처리).
+     */
+    namespace?: string;
+    /**
+     * - `set` ttl 미지정 시 디폴트(초). 0 = 무한 옵트인. (ADR-216, 베이스 처리)
+     */
+    defaultTtlSec?: number;
 };
 /**
  * - 디스크에 저장되는 단일 파일 포맷.

package/types/adapters/file-session-adapter.d.ts

@@ -41,13 +41,15 @@ export class MegaFileSessionAdapter extends MegaSessionAdapter {
         error?: string;
     }>;
     /**
-     * 누적 통계 + file 세션 특화.
-     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, ttlMs: number }}
+     * 누적 통계 + file 세션 특화. `cleanupIntervalMs` 노출(0=내부 타이머 off) — 만료 스캔 주기의
+     * 적용 여부를 운영/테스트가 확인하는 단일 창구(ADR-215).
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, basePath: string, ttlMs: number, cleanupIntervalMs: number }}
      */
     getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
         basePath: string;
         ttlMs: number;
+        cleanupIntervalMs: number;
     };
     #private;
 }

package/types/adapters/maria-adapter.d.ts

@@ -27,15 +27,17 @@ export class MegaMariaAdapter extends MegaDbAdapter {
         error?: string;
     }>;
     /**
-     * 누적 통계 + 풀 통계(total/idle/active/queue). 연결 전이면 풀 통계는 0.
-     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, active: number, queue: number } }}
+     * 누적 통계 + 풀 통계 — 공통 코어 키 `{ total, active, idle, waiting }` 은 4 driver 동일
+     * 형태(ADR-216 G2 H-2). `queue` 는 기존 소비자 하위 호환 별칭(= waiting). 연결 전이면 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, active: number, idle: number, waiting: number, queue: number } }}
      */
     getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
         pool: {
             total: number;
-            idle: number;
             active: number;
+            idle: number;
+            waiting: number;
             queue: number;
         };
     };

package/types/adapters/mega-cache-adapter.d.ts

@@ -1,4 +1,29 @@
 export class MegaCacheAdapter extends MegaAdapter {
+    /**
+     * @param {{ namespace?: string, defaultTtlSec?: number } & Record<string, any>} [config]
+     * @throws {MegaValidationError} `adapter.invalid_option` - namespace/defaultTtlSec 형식 오류.
+     */
+    constructor(config?: {
+        namespace?: string;
+        defaultTtlSec?: number;
+    } & Record<string, any>);
+    /**
+     * 네임스페이스 적용 키 — 구체 어댑터의 get/set/del/has 가 저장소 접근 직전에 경유한다(ADR-064).
+     * @protected
+     * @param {string} key
+     * @returns {string}
+     */
+    protected _cacheKey(key: string): string;
+    /**
+     * `set` 의 유효 TTL 해석 — 명시 ttl 우선, 없으면 defaultTtlSec. 둘 다 없으면 무한 저장이며
+     * `defaultTtlSec: 0` 옵트인이 아닌 한 인스턴스당 1회 경고를 낸다(키 무한 증가 풋건 표면화 —
+     * 동작은 기존과 동일, ADR-216).
+     * @protected
+     * @param {number} [ttl] - 호출자가 명시한 ttl(초).
+     * @param {string} [key] - 경고 메시지용 예시 키.
+     * @returns {number | undefined} 적용할 ttl(초) — undefined 면 무한.
+     */
+    protected _resolveTtl(ttl?: number, key?: string): number | undefined;
     /**
      * @param {string} _key
      * @returns {Promise<any>} 값 — 없으면 `null` (throw X).
@@ -7,7 +32,7 @@ export class MegaCacheAdapter extends MegaAdapter {
     /**
      * @param {string} _key
      * @param {any} _value
-     * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 무한 (초 단위).
+     * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 defaultTtlSec, 그것도 없으면 무한(초 단위, ADR-216).
      * @returns {Promise<void>}
      */
     set(_key: string, _value: any, _opts?: {
@@ -43,5 +68,6 @@ export class MegaCacheAdapter extends MegaAdapter {
         allowZero?: boolean;
         allowInfinity?: boolean;
     }): void;
+    #private;
 }
 import { MegaAdapter } from './mega-adapter.js';

package/types/adapters/mega-db-adapter.d.ts

@@ -4,7 +4,10 @@ export class MegaDbAdapter extends MegaAdapter {
      * driver 별 구현 (postgres `BEGIN/COMMIT/ROLLBACK`, MongoDB `session.withTransaction`).
      * nested 호출은 driver 별 (postgres SAVEPOINT, MongoDB throw `adapter.nested_transaction_unsupported`).
      *
-     * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. 미지정이면 driver 디폴트. driver 별 지원:
+     * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. **미지정이면 driver 디폴트가 적용되며 그
+     * 디폴트는 driver 마다 다르다**(ADR-216 G2 M-2): postgres = READ COMMITTED,
+     * mariadb(InnoDB) = REPEATABLE READ — 같은 `withTransaction(fn)` 코드가 driver 에 따라 다른
+     * 동시성 의미를 가진다. 이식성 있는 동시성 가정이 필요하면 isolation 을 명시할 것. driver 별 지원:
      * postgres/maria 는 top-level 트랜잭션에 `SET TRANSACTION ISOLATION LEVEL` 로 반영(nested 엔 불가 —
      * `adapter.nested_isolation_unsupported`), sqlite 는 항상 SERIALIZABLE 동작이라 'serializable' 만 수용,
      * mongodb 는 SQL 격리수준 개념이 없어 지정 시 `adapter.invalid_option`.

package/types/adapters/mongo-adapter.d.ts

@@ -9,6 +9,7 @@
  * @typedef {object} PoolCounters
  * @property {number} created @property {number} closed
  * @property {number} checkedOut @property {number} checkedIn
+ * @property {number} checkOutStarted @property {number} checkOutFailed
  */
 export class MegaMongoAdapter extends MegaDbAdapter {
     /**
@@ -41,13 +42,21 @@ export class MegaMongoAdapter extends MegaDbAdapter {
         error?: string;
     }>;
     /**
-     * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 연결 전이면 카운터는 0.
-     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
+     * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 공통 코어 키
+     * `{ total, active, idle, waiting }` 은 4 driver 동일 형태(ADR-216 G2 H-2 — CMAP 누적
+     * 카운터에서 파생: total=created-closed, active=checkedOut-checkedIn,
+     * waiting=checkOutStarted-(checkedOut+checkOutFailed)). 누적 원본도 유지(하위 호환).
+     * 연결 전이면 전부 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { total: number, active: number, idle: number, waiting: number, created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
      */
     getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
         dbName: string;
         pool: {
+            total: number;
+            active: number;
+            idle: number;
+            waiting: number;
             created: number;
             closed: number;
             checkedOut: number;
@@ -135,5 +144,7 @@ export type PoolCounters = {
     closed: number;
     checkedOut: number;
     checkedIn: number;
+    checkOutStarted: number;
+    checkOutFailed: number;
 };
 import { MegaDbAdapter } from './mega-db-adapter.js';

package/types/adapters/postgres-adapter.d.ts

@@ -42,13 +42,15 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
         error?: string;
     }>;
     /**
-     * 누적 통계 + 풀 통계(total/idle/waiting). 연결 전이면 풀 통계는 0.
-     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, waiting: number } }}
+     * 누적 통계 + 풀 통계 — 공통 코어 키 `{ total, active, idle, waiting }` 은 4 driver 동일
+     * 형태(ADR-216 G2 H-2: 운영 대시보드가 driver 무관 코드로 "풀 포화" 를 묻게). 연결 전이면 0.
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, active: number, idle: number, waiting: number } }}
      */
     getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
         pool: {
             total: number;
+            active: number;
             idle: number;
             waiting: number;
         };

package/types/adapters/redis-adapter.d.ts

@@ -62,6 +62,14 @@ export type RedisConfig = {
      * - 미지원 — 지정 시 `adapter.invalid_option` throw (Redis 는 풀 모델 아님, ADR-110).
      */
     pool?: any;
+    /**
+     * - 캐시 키 자동 prefix `mega:cache:<namespace>:` (ADR-064/213 — 멀티앱 충돌 차단, 옵트인).
+     */
+    namespace?: string;
+    /**
+     * - `set` 의 ttl 미지정 시 적용할 디폴트(초). 0 = 무한 저장 옵트인(경고 억제). (ADR-216)
+     */
+    defaultTtlSec?: number;
     /**
      * - ioredis passthrough (keyPrefix, commandTimeout, tls, retryStrategy, keepAlive, …).
      */

package/types/adapters/sqlite-adapter.d.ts

@@ -37,8 +37,8 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
         error?: string;
     }>;
     /**
-     * 누적 통계 + sqlite 특화 필드.
-     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined }}
+     * 누적 통계 + sqlite 특화 필드 + 공통 풀 코어 키(합성 — 단일 연결, ADR-216).
+     * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined, pool: { total: number, active: number, idle: number, waiting: number } }}
      */
     getStats(): ReturnType<import("./mega-adapter.js").MegaAdapter["getStats"]> & {
         driver: string;
@@ -46,6 +46,12 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
         inMemory: boolean;
         readonly: boolean;
         journalMode: string | undefined;
+        pool: {
+            total: number;
+            active: number;
+            idle: number;
+            waiting: number;
+        };
     };
     /**
      * 명시적 트랜잭션 경계 (ADR-010, ADR-105). manual `BEGIN/COMMIT/ROLLBACK` 으로

package/types/cli/generators/index.d.ts

@@ -13,6 +13,16 @@
  * @returns {Artifact[]}
  */
 export function planArtifacts(kind: string, rawName: string, opts: Record<string, any>, projectRoot: string): Artifact[];
+/**
+ * 다음 ADR 번호를 해석한다 — `docs/adr/NNNN-*.md` 파일명 + 레거시 `docs/09` 헤딩(`### ADR-N:`) +
+ * 호출측이 모은 추가 번호(예: `git ls-tree origin/main` 의 원격 파일 — 병렬 task 충돌 회피)의
+ * 최댓값 + 1. 아무 ADR 도 없으면 1.
+ *
+ * @param {string} projectRoot
+ * @param {number[]} [extraNumbers] - 로컬 밖에서 관측한 번호(원격 스캔 등).
+ * @returns {number}
+ */
+export function nextAdrNumber(projectRoot: string, extraNumbers?: number[]): number;
 /**
  * 계획된 artifact 를 디스크에 쓴다. 이미 있으면 건너뛴다(force 면 덮어씀).
  * @param {Artifact[]} artifacts
@@ -83,7 +93,7 @@ export function generate(kind: string, rawName: string, opts?: object, projectRo
     skipped: string[];
 };
 /** 지원 generator 종류(roadmap §337 — 13종). */
-export const GENERATOR_KINDS: readonly ["app", "controller", "channel", "service", "model", "middleware", "route", "schedule", "job", "worker", "locale", "adapter", "migration"];
+export const GENERATOR_KINDS: readonly ["app", "controller", "channel", "service", "model", "middleware", "route", "schedule", "job", "worker", "locale", "adapter", "migration", "adr"];
 /**
  * 플러그인 scaffold manifest 의 토큰 계약(ADR-199) — `files[].path`/`files[].template` 의 `{{token}}`
  * 에 쓸 수 있는 이름과 의미. 빌트인 generator 의 base 토큰과 동일 집합이라 템플릿 작성 관례가 하나다.