mega-framework 0.1.7 → 0.1.8

package/README.md

@@ -39,6 +39,15 @@ npm test              # 전체 테스트(실 인프라). .env 자동 로드(ADR-
 npm run infra:down    # 인프라 종료
 ```
 
+> **워크스페이스 안내 (ADR-197)** — `sample/crud`·`sample/simple` 은 npm workspaces 라서 모든 의존성이
+> **루트 `node_modules` 로 hoist** 된다. `sample/crud/node_modules` 가 안 생기는 것이 **정상**이며
+> (sample 안에서 `npm install` 을 실행해도 루트에 설치된다), `mega-framework` 는
+> `node_modules/mega-framework → ..` self-link 로 해석된다. 확인: `npm ls --workspace sample-crud`.
+>
+> **yarn 미지원** — yarn v1 은 workspaces 에 루트 `"private": true` 를 요구하는데 본 패키지는 npm 배포
+> 대상(`private: false`)이라 `yarn install` 이 `Workspaces can only be enabled in private projects` 로
+> 실패한다. **npm 만 사용**한다(lockfile 정본 = `package-lock.json` 1벌).
+
 프로젝트 루트에 `mega.config.js`(글로벌) + 앱별 `apps/<name>/app.config.js` 를 둔다.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
@@ -69,7 +69,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src test",
+    "lint": "eslint src test scripts",
     "typecheck": "tsc -p jsconfig.json --noEmit",
     "build:types": "rm -rf types && tsc -p tsconfig.build.json",
     "format": "prettier -w src test packages",
@@ -79,8 +79,8 @@
     "infra:reset": "docker compose down -v && docker compose up -d --wait",
     "test:integration": "npm run infra:up && vitest run test/integration && npm run infra:down",
     "test:unit": "vitest run test/unit",
+    "adr:index": "node scripts/build-adr-index.js",
     "prepublishOnly": "npm run build:types && npm run lint && npm run typecheck && npm run test:unit",
-    "prepare": "npm run build:types",
     "release": "bash scripts/publish.sh"
   },
   "devDependencies": {

package/sample/crud/.env

@@ -20,6 +20,15 @@
 # NODE_ENV=development
 
 
+# ── dev watch ignore (mega.config.js > watch, ADR-220) ───────────────────────
+# `mega start --watch` 의 ignore 목록(콤마 구분 glob) — **여기가 정본**(숨은 코드 디폴트 없음).
+# "런타임이 스스로 쓰거나 재시작 없이 반영되는" 영역을 나열한다. 폴더명을 바꿨으면 이 줄만 고친다.
+#   locales: dev 의 i18n saveMissing 자동 기입(안 빼면 재시작 무한 루프) / views: EJS 는 dev 에서
+#   매 요청 재컴파일 / public: 정적 자산 / uploads·var: 사용자 업로드 등 런타임 데이터 /
+#   .mega: 마이그레이션 journal / .env*: 시크릿 변경은 수동 재시작.
+# 비우면 모든 변경이 재시작 대상이다(기동 시 경고 1줄).
+WATCH_IGNORE=**/locales/**,**/views/**,**/public/**,**/uploads/**,var/**,logs/**,tmp/**,.mega/**,**/node_modules/**,**/.git/**,**/*.test.js,**/*.spec.js,.env,.env.*,**/templates/**,data/**
+
 # ── 서버 (mega.config.js > server) ───────────────────────────────────────────
 # HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000

package/sample/crud/.env.example

@@ -20,6 +20,15 @@
 # NODE_ENV=development
 
 
+# ── dev watch ignore (mega.config.js > watch, ADR-220) ───────────────────────
+# `mega start --watch` 의 ignore 목록(콤마 구분 glob) — **여기가 정본**(숨은 코드 디폴트 없음).
+# "런타임이 스스로 쓰거나 재시작 없이 반영되는" 영역을 나열한다. 폴더명을 바꿨으면 이 줄만 고친다.
+#   locales: dev 의 i18n saveMissing 자동 기입(안 빼면 재시작 무한 루프) / views: EJS 는 dev 에서
+#   매 요청 재컴파일 / public: 정적 자산 / uploads·var: 사용자 업로드 등 런타임 데이터 /
+#   .mega: 마이그레이션 journal / .env*: 시크릿 변경은 수동 재시작.
+# 비우면 모든 변경이 재시작 대상이다(기동 시 경고 1줄).
+WATCH_IGNORE=**/locales/**,**/views/**,**/public/**,**/uploads/**,var/**,logs/**,tmp/**,.mega/**,**/node_modules/**,**/.git/**,**/*.test.js,**/*.spec.js,.env,.env.*
+
 # ── 서버 (mega.config.js > server) ───────────────────────────────────────────
 # HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000

package/sample/crud/apps/main/locales/server/en.json

@@ -313,5 +313,16 @@
   "csrf": {
     "invalid_token": "Invalid csrf token",
     "missing_secret": "Missing csrf secret"
-  }
+  },
+  "field_username": "아이디",
+  "field_username_ph": "예: hong123",
+  "field_username_required": "아이디를 입력하세요.",
+  "field_nickname": "별명",
+  "field_nickname_ph": "예: 길동이",
+  "field_nickname_required": "별명을 입력하세요.",
+  "optional": "선택",
+  "field_phone": "전화번호",
+  "field_phone_ph": "예: 010-1234-5678",
+  "col_username": "아이디",
+  "col_nickname": "별명"
 }

package/sample/crud/apps/main/locales/server/ko.json

@@ -313,5 +313,16 @@
   },
   "guide": {
     "not_found": "가이드를 찾을 수 없습니다."
-  }
+  },
+  "field_username": "아이디",
+  "field_username_ph": "예: hong123",
+  "field_username_required": "아이디를 입력하세요.",
+  "field_nickname": "별명",
+  "field_nickname_ph": "예: 길동이",
+  "field_nickname_required": "별명을 입력하세요.",
+  "optional": "선택",
+  "field_phone": "전화번호",
+  "field_phone_ph": "예: 010-1234-5678",
+  "col_username": "아이디",
+  "col_nickname": "별명"
 }

package/sample/crud/mega.config.js

@@ -175,4 +175,11 @@ export default {
   // OpenTelemetry 분산 트레이싱 — **config 블록이 아니라 .env 의 MEGA_OTEL_\*** 로 설정한다
   //   (MegaTracing.fromEnv, boot.js). MEGA_OTEL_ENABLED='true' + MEGA_OTEL_SERVICE_NAME 필수.
   //   (`tracing` 키는 스키마엔 있으나 현재 부팅이 소비하지 않음 — 죽은 설정 회피 위해 블록을 두지 않음.)
+
+  // dev watch(`mega start --watch`) ignore — .env 의 WATCH_IGNORE(콤마 구분 glob)가 정본이다
+  // (ADR-220, 숨은 코드 디폴트 없음). 폴더명을 바꾼 프로젝트는 .env 의 그 줄만 고치면 된다.
+  // 미설정이면 ignore 0 — 모든 변경이 재시작 대상(기동 시 경고 1줄).
+  watch: {
+    ignore: (process.env.WATCH_IGNORE ?? '').split(',').map((p) => p.trim()).filter(Boolean),
+  },
 }

package/sample/crud/package.json

@@ -7,7 +7,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "dev": "mega start --watch",
+    "dev": "NODE_ENV=development mega start --watch",
     "start": "NODE_ENV=production mega start",
     "migrate": "mega migrate",
     "migrate:down": "mega migrate:down",
@@ -25,4 +25,4 @@
     "concurrently": "^9.0.0",
     "vitest": "^4.1.8"
   }
-}
+}

package/sample/crud/scripts/start-ws-hub.sh

@@ -3,7 +3,7 @@
 # sample/crud — WS Hub 서버 기동 스크립트 (ADR-032/176)
 #
 # 별도 hub 프로세스(`mega-ws-hub` 바이너리, mega-framework bin)를 localhost:3100 에 띄운다.
-# 앱(`yarn dev` = `mega start`)이 app.config 의 `bridgeHub` 로 이 허브에 **자동 연결**한다(ADR-176).
+# 앱(`npm run dev` = `mega start`)이 app.config 의 `bridgeHub` 로 이 허브에 **자동 연결**한다(ADR-176).
 #
 # ⚠️ `mega-ws-hub` 는 `mega start` 와 달리 `.env` 를 자동 로드하지 않는다(직접 process.env 만 읽음,
 #    src/lib/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
@@ -22,15 +22,29 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 
 ENV_FILE=".env"
-BIN="node_modules/mega-framework/bin/mega-ws-hub.js"
+
+# mega-ws-hub 바이너리 탐색 — 두 설치 형상을 모두 지원한다:
+#   ① 독립 프로젝트(mega new 스캐폴드): 자기 node_modules 에 설치됨.
+#   ② 모노레포 workspaces(ADR-197): 의존성이 레포 루트로 hoist 되어 sample/crud 에는 node_modules 가
+#      없다(정상). 루트의 mega-framework self-link 를 따라간다.
+BIN=""
+for candidate in \
+  "node_modules/mega-framework/bin/mega-ws-hub.js" \
+  "../../node_modules/mega-framework/bin/mega-ws-hub.js"; do
+  if [ -f "$candidate" ]; then
+    BIN="$candidate"
+    break
+  fi
+done
 
 # 사전 점검 — 누락 시 silent 진행 금지, 이유를 명확히 알린다(P4/P7).
 [ -f "$ENV_FILE" ] || {
   echo "✗ $ROOT/$ENV_FILE 가 없습니다 — MEGA_WSHUB_TOKENS 등 허브 설정이 필요합니다." >&2
   exit 1
 }
-[ -f "$BIN" ] || {
-  echo "✗ $BIN 없음 — 먼저 'yarn install --ignore-engines'(또는 npm install) 로 mega-framework 를 설치/동기화하세요." >&2
+[ -n "$BIN" ] || {
+  echo "✗ mega-ws-hub.js 를 찾지 못했습니다(로컬/루트 node_modules 모두) — 'npm install' 로 mega-framework 를 설치하세요." >&2
+  echo "  (모노레포에서는 레포 루트에서 실행해야 합니다. yarn 은 미지원 — npm 사용.)" >&2
   exit 1
 }
 

package/sample/simple/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.8","results":[[":test/apps/main/index.test.js",{"duration":1.6905000000000001,"failed":false}]]}

package/src/adapters/adapter-options.js

@@ -165,6 +165,9 @@ export function resolveConnection(config, { driver, dbKey = 'database', dbConfli
   return out
 }
 
+/** pool acquire 대기 한도 프레임워크 디폴트(ms) — 명시 0 으로 드라이버 무한 대기 옵트인(ADR-216). */
+export const DEFAULT_ACQUIRE_TIMEOUT_MS = 10_000
+
 /**
  * pg 풀 매핑 — 값이 null 이면 미지원(throw), `{ key, divideBy? }` 면 키 이름 변경(+단위 변환).
  * @type {Record<string, { key: string, divideBy?: number } | null>}
@@ -216,11 +219,11 @@ export const MONGO_POOL_SPEC = {
  * @returns {Record<string, number>} 드라이버 풀 옵션 객체(빈 객체 가능).
  */
 export function normalizePool(pool, spec, driver) {
-  if (pool === undefined) return {}
-  assertPlainObject('pool', pool, { driver })
   /** @type {Record<string, number>} */
   const out = {}
-  for (const [key, value] of Object.entries(/** @type {Record<string, unknown>} */ (pool))) {
+  if (pool !== undefined) assertPlainObject('pool', pool, { driver })
+  const entries = pool === undefined ? [] : Object.entries(/** @type {Record<string, unknown>} */ (pool))
+  for (const [key, value] of entries) {
     if (value === undefined) continue
     const map = spec[key]
     if (map === undefined) {
@@ -234,5 +237,13 @@ export function normalizePool(pool, spec, driver) {
     const num = /** @type {number} */ (value)
     out[map.key] = map.divideBy ? Math.floor(num / map.divideBy) : num
   }
+  // 프레임워크 디폴트(ADR-216 G2 H-1): acquire 무한 대기(pg connectionTimeoutMillis=0 ·
+  // mongo waitQueueTimeoutMS=0 드라이버 디폴트)는 연결 leak 1건을 전체 서비스 행으로 키운다 —
+  // 미지정 시 10s 를 기본 적용한다(maria 드라이버 디폴트 10s 와 정렬). 명시 `acquireTimeoutMs: 0`
+  // 은 드라이버 무한 대기 의미 그대로 통과(무한 옵트인).
+  const acquireMap = spec.acquireTimeoutMs
+  if (acquireMap !== null && acquireMap !== undefined && out[acquireMap.key] === undefined) {
+    out[acquireMap.key] = DEFAULT_ACQUIRE_TIMEOUT_MS
+  }
   return out
 }

package/src/adapters/file-adapter.js

@@ -75,6 +75,8 @@ const KNOWN_OPTIONS = new Set(['serializer', 'extension'])
  * @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, 베이스 처리)
  */
 
 /**
@@ -94,7 +96,8 @@ export class MegaFileAdapter extends MegaCacheAdapter {
   #extension
 
   /**
-   * @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` - 옵션 타입/미지원 키 오류.
    */
@@ -245,7 +248,7 @@ export class MegaFileAdapter extends MegaCacheAdapter {
    */
   async get(key) {
     return this._instrument('get', { key }, async () => {
-      const path = this.#pathFor(key)
+      const path = this.#pathFor(this._cacheKey(key))
       let raw
       try {
         raw = await readFile(path, 'utf8')
@@ -278,6 +281,7 @@ export class MegaFileAdapter extends MegaCacheAdapter {
     // TTL·직렬화 검증은 의도적으로 `_instrument` **밖**(fail-fast). 잘못된 인자는 디스크 I/O·hook·stats
     // 이전에 거부 — 프로그래밍 오류를 instrumented 호출 통계에 섞지 않는다(L-1, redis 어댑터와 동일 결정).
     this._assertTtl(ttl)
+    ttl = this._resolveTtl(ttl, key) // 미지정 → defaultTtlSec(ADR-216). 디폴트 값은 생성자에서 검증됨.
     if (this.#serializer === 'raw' && typeof value !== 'string') {
       throw new MegaValidationError('cache.unserializable', `file set("${key}"): serializer='raw' requires a string value (got ${typeof value}).`, {
         details: { key, type: typeof value, serializer: 'raw' },
@@ -300,7 +304,7 @@ export class MegaFileAdapter extends MegaCacheAdapter {
         value,
         expiresAt: ttl !== undefined ? Date.now() + ttl * 1000 : null,
       }
-      await this.#atomicWrite(this.#pathFor(key), envelope)
+      await this.#atomicWrite(this.#pathFor(this._cacheKey(key)), envelope)
     })
   }
 
@@ -312,7 +316,7 @@ export class MegaFileAdapter extends MegaCacheAdapter {
   async del(key) {
     return this._instrument('del', { key }, async () => {
       try {
-        await unlink(this.#pathFor(key))
+        await unlink(this.#pathFor(this._cacheKey(key)))
       } catch (err) {
         // ENOENT = 이미 없음(del idempotent — 정상). 그 외 I/O 에러는 전파(무차별 삼킴 X).
         if (/** @type {any} */ (err)?.code !== 'ENOENT') throw err
@@ -331,7 +335,7 @@ export class MegaFileAdapter extends MegaCacheAdapter {
    */
   async has(key) {
     return this._instrument('has', { key }, async () => {
-      const path = this.#pathFor(key)
+      const path = this.#pathFor(this._cacheKey(key))
       let raw
       try {
         raw = await readFile(path, 'utf8')

package/src/adapters/file-session-adapter.js

@@ -199,11 +199,12 @@ export class MegaFileSessionAdapter extends MegaSessionAdapter {
   }
 
   /**
-   * 누적 통계 + 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() {
-    return { ...super.getStats(), driver: 'file', basePath: this.#basePath, ttlMs: this.#ttlMs }
+    return { ...super.getStats(), driver: 'file', basePath: this.#basePath, ttlMs: this.#ttlMs, cleanupIntervalMs: this.#cleanupIntervalMs }
   }
 
   /**

package/src/adapters/maria-adapter.js

@@ -298,19 +298,22 @@ export class MegaMariaAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + 풀 통계(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() {
     const pool = this.#pool
+    const waiting = pool?.taskQueueSize() ?? 0
     return {
       ...super.getStats(),
       driver: 'mariadb',
       pool: {
         total: pool?.totalConnections() ?? 0,
-        idle: pool?.idleConnections() ?? 0,
         active: pool?.activeConnections() ?? 0,
-        queue: pool?.taskQueueSize() ?? 0,
+        idle: pool?.idleConnections() ?? 0,
+        waiting,
+        queue: waiting,
       },
     }
   }

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

@@ -5,10 +5,15 @@
  * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
  * `MegaFileAdapter` (ADR-082).
  *
- * ⚠️ **키 네임스페이스(ADR-064)**: ADR-064 가 `mega:cache:<appName>:<key>` 자동 prefix 를 *결정*했으나
- * **현재 코어에 미구현**이다(get/set/del 이 raw `key` 를 그대로 사용). 멀티앱이 같은 redis 를 공유하면
- * 키 충돌 위험이 있으니, **현재는 사용자가 키에 앱별 네임스페이스를 직접 붙여야 한다**. 자동 prefix 구현은
- * 후속 과제(ADR-064 open). 단일앱(현 sample)에선 무관.
+ * **키 네임스페이스(ADR-064, 옵트인 — ADR-216 구현)**: `services.caches.<key>.namespace: '<name>'`
+ * 을 주면 get/set/del/has 의 키에 `mega:cache:<name>:` 가 자동 prefix 된다 — 멀티앱이 같은 redis 를
+ * 공유할 때의 키 충돌·상호 evict 차단(세션 `mega:sess:`·roster `ws:roster:` 와 대칭). 미지정 시
+ * 기존과 동일하게 raw key(하위 호환 — 기본 ON 전환은 메이저에서 재평가).
+ *
+ * **디폴트 TTL(ADR-216)**: `defaultTtlSec: <초>` 를 주면 `set` 의 ttl 미지정 호출에 적용된다 —
+ * 동적 키에 ttl 을 빠뜨려 무한 증가하는 풋건 방어. `defaultTtlSec: 0` = 무한 저장을 의식적으로
+ * 선택(경고 없음). 둘 다 미지정인 채 ttl 없는 set 이 호출되면 **인스턴스당 1회** process.emitWarning
+ * 으로 표면화한다(동작은 기존과 동일 — 무한 저장).
  *
  * @module adapters/mega-cache-adapter
  */
@@ -16,8 +21,21 @@ import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js
 import { MegaAdapter } from './mega-adapter.js'
 
 export class MegaCacheAdapter extends MegaAdapter {
+  /** @type {string | null} ADR-064 자동 prefix (`mega:cache:<namespace>:`) — 미지정이면 null(raw key). */
+  #keyPrefix = null
+
+  /** @type {number | null} set 의 ttl 미지정 시 적용할 디폴트(초). null = 미설정. */
+  #defaultTtlSec = null
+
+  /** @type {boolean} `defaultTtlSec: 0` — 무한 저장 의식적 옵트인(경고 억제). */
+  #isInfiniteTtlOptIn = false
+
+  /** @type {boolean} 무기한 set 경고를 인스턴스당 1회로 제한. */
+  #hasWarnedNoTtl = false
+
   /**
-   * @param {object} [config]
+   * @param {{ namespace?: string, defaultTtlSec?: number } & Record<string, any>} [config]
+   * @throws {MegaValidationError} `adapter.invalid_option` - namespace/defaultTtlSec 형식 오류.
    */
   constructor(config) {
     super(config)
@@ -28,6 +46,65 @@ export class MegaCacheAdapter extends MegaAdapter {
         { details: { class: 'MegaCacheAdapter' } },
       )
     }
+    const ns = config?.namespace
+    if (ns !== undefined) {
+      // 콜론·공백은 prefix 구조(`mega:cache:<ns>:<key>`)의 구분자 혼동을 만든다 — 명시 거부.
+      if (typeof ns !== 'string' || ns.length === 0 || /[\s:]/.test(ns)) {
+        throw new MegaValidationError(
+          'adapter.invalid_option',
+          `cache "namespace" must be a non-empty string without spaces/colons (got ${JSON.stringify(ns)}).`,
+          { details: { namespace: ns ?? null } },
+        )
+      }
+      this.#keyPrefix = `mega:cache:${ns}:`
+    }
+    const ttl = config?.defaultTtlSec
+    if (ttl !== undefined) {
+      if (ttl === 0) {
+        this.#isInfiniteTtlOptIn = true
+      } else if (!Number.isInteger(ttl) || ttl < 0) {
+        throw new MegaValidationError(
+          'adapter.invalid_option',
+          `cache "defaultTtlSec" must be a non-negative integer (0 = 무한 저장 옵트인, got ${JSON.stringify(ttl)}).`,
+          { details: { defaultTtlSec: ttl } },
+        )
+      } else {
+        this.#defaultTtlSec = ttl
+      }
+    }
+  }
+
+  /**
+   * 네임스페이스 적용 키 — 구체 어댑터의 get/set/del/has 가 저장소 접근 직전에 경유한다(ADR-064).
+   * @protected
+   * @param {string} key
+   * @returns {string}
+   */
+  _cacheKey(key) {
+    return this.#keyPrefix === null ? key : this.#keyPrefix + key
+  }
+
+  /**
+   * `set` 의 유효 TTL 해석 — 명시 ttl 우선, 없으면 defaultTtlSec. 둘 다 없으면 무한 저장이며
+   * `defaultTtlSec: 0` 옵트인이 아닌 한 인스턴스당 1회 경고를 낸다(키 무한 증가 풋건 표면화 —
+   * 동작은 기존과 동일, ADR-216).
+   * @protected
+   * @param {number} [ttl] - 호출자가 명시한 ttl(초).
+   * @param {string} [key] - 경고 메시지용 예시 키.
+   * @returns {number | undefined} 적용할 ttl(초) — undefined 면 무한.
+   */
+  _resolveTtl(ttl, key) {
+    if (ttl !== undefined) return ttl
+    if (this.#defaultTtlSec !== null) return this.#defaultTtlSec
+    if (!this.#isInfiniteTtlOptIn && !this.#hasWarnedNoTtl) {
+      this.#hasWarnedNoTtl = true
+      process.emitWarning(
+        `cache.set("${key ?? '?'}") without ttl and no defaultTtlSec configured — keys never expire and can grow unbounded. ` +
+          `Set services.caches.<key>.defaultTtlSec (or pass { ttl }), or defaultTtlSec: 0 to opt in to unbounded storage.`,
+        { code: 'MEGA_CACHE_NO_TTL' },
+      )
+    }
+    return undefined
   }
 
   /**
@@ -41,7 +118,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>}
    */
   async set(_key, _value, _opts = {}) {

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

@@ -30,7 +30,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/src/adapters/mongo-adapter.js

@@ -137,6 +137,7 @@ function buildMongoUri({ host, port, user, password }) {
  * @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 {
@@ -162,7 +163,7 @@ export class MegaMongoAdapter extends MegaDbAdapter {
    */
   #txContext = new AsyncLocalStorage()
   /** @type {PoolCounters} CMAP 이벤트 누적 풀 카운터. */
-  #pool = { created: 0, closed: 0, checkedOut: 0, checkedIn: 0 }
+  #pool = { created: 0, closed: 0, checkedOut: 0, checkedIn: 0, checkOutStarted: 0, checkOutFailed: 0 }
   /**
    * 등록한 CMAP 리스너 — disconnect 시 정확히 제거하기 위해 보관(누수·재연결 시 중복 방지).
    * @type {Array<[string, (...args: any[]) => void]>}
@@ -296,23 +297,33 @@ export class MegaMongoAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + 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() {
-    const { created, closed, checkedOut, checkedIn } = this.#pool
+    const { created, closed, checkedOut, checkedIn, checkOutStarted, checkOutFailed } = this.#pool
+    const total = created - closed
+    const active = checkedOut - checkedIn
     return {
       ...super.getStats(),
       driver: 'mongodb',
       dbName: this.#dbName,
       pool: {
+        total,
+        active,
+        idle: total - active,
+        waiting: checkOutStarted - checkedOut - checkOutFailed,
         created,
         closed,
         checkedOut,
         checkedIn,
-        // 파생값 — open=살아있는 연결 수, inUse=현재 체크아웃된(작업 중) 연결 수.
-        open: created - closed,
-        inUse: checkedOut - checkedIn,
+        // 파생값(기존 표면 유지) — open=살아있는 연결 수, inUse=현재 체크아웃된(작업 중) 연결 수.
+        open: total,
+        inUse: active,
       },
     }
   }
@@ -389,6 +400,9 @@ export class MegaMongoAdapter extends MegaDbAdapter {
       ['connectionClosed', () => (this.#pool.closed += 1)],
       ['connectionCheckedOut', () => (this.#pool.checkedOut += 1)],
       ['connectionCheckedIn', () => (this.#pool.checkedIn += 1)],
+      // 공통 풀 키의 waiting 파생용(ADR-216) — started - (out + failed) = 현재 대기 수.
+      ['connectionCheckOutStarted', () => (this.#pool.checkOutStarted += 1)],
+      ['connectionCheckOutFailed', () => (this.#pool.checkOutFailed += 1)],
     ]
     for (const [event, handler] of listeners) {
       client.on(event, handler)

package/src/adapters/postgres-adapter.js

@@ -216,17 +216,21 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + 풀 통계(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() {
     const pool = this.#pool
+    const total = pool?.totalCount ?? 0
+    const idle = pool?.idleCount ?? 0
     return {
       ...super.getStats(),
       driver: 'postgres',
       pool: {
-        total: pool?.totalCount ?? 0,
-        idle: pool?.idleCount ?? 0,
+        total,
+        active: total - idle,
+        idle,
         waiting: pool?.waitingCount ?? 0,
       },
     }

package/src/adapters/redis-adapter.js

@@ -61,6 +61,8 @@ import * as Registry from './registry.js'
  * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
  * @property {number} [db] - 논리 DB 번호 0~15 (connection 과 별개 축, url path 보다 우선).
  * @property {any} [pool] - 미지원 — 지정 시 `adapter.invalid_option` throw (Redis 는 풀 모델 아님, ADR-110).
+ * @property {string} [namespace] - 캐시 키 자동 prefix `mega:cache:<namespace>:` (ADR-064/213 — 멀티앱 충돌 차단, 옵트인).
+ * @property {number} [defaultTtlSec] - `set` 의 ttl 미지정 시 적용할 디폴트(초). 0 = 무한 저장 옵트인(경고 억제). (ADR-216)
  * @property {Record<string, any>} [options] - ioredis passthrough (keyPrefix, commandTimeout, tls, retryStrategy, keepAlive, …).
  */
 
@@ -267,7 +269,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async get(key) {
     return this._instrument('get', { key }, async () => {
-      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(key)
+      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(this._cacheKey(key))
       if (raw === null) return null // miss
       return JSON.parse(raw)
     })
@@ -287,6 +289,8 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
     // I/O·hook·stats 누적 이전에 fail-fast 로 거부하는 게 맞다(인자 오류는 어댑터 "호출"이 아니라
     // 프로그래밍 오류 — instrumented 호출 통계에 섞이면 안 됨). 정상 경로의 실제 I/O 만 _instrument 가 감싼다.
     this._assertTtl(ttl)
+    ttl = this._resolveTtl(ttl, key) // 미지정 → defaultTtlSec(ADR-216). 디폴트 값은 생성자에서 검증됨.
+    key = this._cacheKey(key)
     const raw = JSON.stringify(value)
     if (raw === undefined) {
       // JSON.stringify(undefined/함수/심볼) === undefined — 저장 시 silent 손상 대신 명시 거부.
@@ -309,7 +313,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async del(key) {
     return this._instrument('del', { key }, async () => {
-      await /** @type {import('ioredis').Redis} */ (this.#client).del(key)
+      await /** @type {import('ioredis').Redis} */ (this.#client).del(this._cacheKey(key))
     })
   }
 
@@ -320,7 +324,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async has(key) {
     return this._instrument('has', { key }, async () => {
-      const n = await /** @type {import('ioredis').Redis} */ (this.#client).exists(key)
+      const n = await /** @type {import('ioredis').Redis} */ (this.#client).exists(this._cacheKey(key))
       return n === 1
     })
   }

package/src/adapters/sqlite-adapter.js

@@ -219,10 +219,11 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + 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() {
+    const connected = this.state === 'connected'
     return {
       ...super.getStats(),
       driver: 'sqlite',
@@ -231,6 +232,9 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
       readonly: this.#openOptions.readonly,
       // _connect() 에서 캐시한 불변값 사용 — 미연결이면 undefined(매 호출 PRAGMA 실행 제거, L-4).
       journalMode: this.#journalMode,
+      // 공통 풀 코어 키(ADR-216 G2 H-2) — sqlite 는 connection-per-Database 단일 동기 연결이라
+      // 풀이 없다. 쿼리가 동기라 stats 를 읽는 시점엔 항상 유휴(active 0/waiting 0) — 합성 값.
+      pool: connected ? { total: 1, active: 0, idle: 1, waiting: 0 } : { total: 0, active: 0, idle: 0, waiting: 0 },
     }
   }