mega-framework 0.1.6 → 0.1.8

package/src/adapters/maria-adapter.js

@@ -73,9 +73,9 @@
  * @module adapters/maria-adapter
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { MegaValidationError } from '../errors/http-errors.js'
+import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js'
 import { MegaDbAdapter } from './mega-db-adapter.js'
-import { resolveConnection, normalizePool, assertPlainObject, MARIA_POOL_SPEC } from './adapter-options.js'
+import { resolveConnection, normalizePool, assertPlainObject, resolveTxIsolation, MARIA_POOL_SPEC } from './adapter-options.js'
 import * as Registry from './registry.js'
 
 /**
@@ -165,6 +165,11 @@ function resolveBigIntStrategy(options) {
 }
 
 export class MegaMariaAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'mariadb'} */
+  get driver() {
+    return 'mariadb'
+  }
+
   /** @type {import('mariadb').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
   #pool = null
   /** @type {Record<string, unknown>} _connect 의 `createPool()` 인자 (url 도 discrete 로 파싱해 항상 객체, ADR-109). */
@@ -293,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,
       },
     }
   }
@@ -318,23 +326,41 @@ export class MegaMariaAdapter extends MegaDbAdapter {
    * RELEASE SAVEPOINT) 후 반환값을 그대로 돌려주고, throw 시 rollback(또는 ROLLBACK TO SAVEPOINT)
    * 후 원본 에러 re-throw.
    *
+   * `opts.isolation`(ADR-190) — top-level 이면 `beginTransaction()` **직전에** 같은 연결에서
+   * `SET TRANSACTION ISOLATION LEVEL` 을 실행한다(MariaDB 의 `SET TRANSACTION` 은 같은 세션의
+   * **다음** 트랜잭션 1회에만 적용 — 공식 문서). 격리수준은 트랜잭션 시작 시 고정되므로
+   * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(conn: import('mariadb').PoolConnection) => Promise<T> | T} fn
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_isolation_unsupported` - nested 호출에 isolation 지정.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    const isolationSql = resolveTxIsolation(opts?.isolation, 'mariadb')
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const existing = this.#txContext.getStore()
       // nested — 진행 중 트랜잭션이 있으면 같은 연결에 SAVEPOINT 를 건다(Sqlite 와 분기).
       if (existing !== undefined) {
+        if (isolationSql !== undefined) {
+          throw new MegaInternalError(
+            'adapter.nested_isolation_unsupported',
+            `${this.constructor.name}.withTransaction() cannot set an isolation level on a nested (SAVEPOINT) transaction — isolation is fixed when the top-level transaction starts (ADR-190).`,
+            { details: { adapter: this.constructor.name, isolation: opts?.isolation } },
+          )
+        }
         return this.#runSavepoint(existing, fn)
       }
       // top-level — 풀에서 연결 1개 획득 후 beginTransaction/commit/rollback.
       const pool = /** @type {import('mariadb').Pool} */ (this.#pool)
       const conn = await pool.getConnection()
       try {
+        // SET TRANSACTION 은 다음 트랜잭션 1회에만 적용 — 반드시 beginTransaction 직전, 같은 연결에서.
+        if (isolationSql !== undefined) await conn.query(`SET TRANSACTION ISOLATION LEVEL ${isolationSql}`)
         await conn.beginTransaction()
         let result
         try {

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,11 +30,20 @@ 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 마다 다르다**(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`.
+   *
    * @template T
    * @param {(db: any) => Promise<T>} _fn - 트랜잭션 컨텍스트의 `db` 를 받는 콜백.
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [_opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
    */
-  async withTransaction(_fn) {
+  async withTransaction(_fn, _opts) {
     return this._notImplemented('withTransaction')
   }
 

package/src/adapters/mongo-adapter.js

@@ -137,9 +137,15 @@ 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 {
+  /** driver 식별자 — dialect 디스패치·CRUD 의 단일 출처(ADR-212). mongo 는 SQL CRUD 미지원(P3). @returns {'mongodb'} */
+  get driver() {
+    return 'mongodb'
+  }
+
   /** @type {import('mongodb').MongoClient | null} 연결된 MongoClient (connect 후에만). */
   #client = null
   /** @type {import('mongodb').Db | null} 선택된 Db 인스턴스 (connect 후에만). */
@@ -157,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]>}
@@ -291,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,
       },
     }
   }
@@ -320,14 +336,27 @@ export class MegaMongoAdapter extends MegaDbAdapter {
    * throw 시 abort 후 원본 에러를 re-throw 한다. nested 호출은 ALS 로 감지해 거부(Sqlite 와 동일).
    * `session.endSession()` 은 `finally` 에서 반드시 호출(leak 방지).
    *
+   * `opts.isolation`(ADR-190) — MongoDB 트랜잭션에는 SQL 격리수준 개념이 없다(snapshot 의미는 driver/
+   * readConcern 관할). 지정 시 `adapter.invalid_option` 으로 명시 거부한다(조용히 무시 X — P4).
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(db: import('mongodb').Db, session: import('mongodb').ClientSession) => Promise<T> | T} fn
+   * @param {{ isolation?: never }} [opts] - 트랜잭션 옵션(ADR-190) — mongodb 는 isolation 미지원.
    * @returns {Promise<T>}
    * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   * @throws {MegaValidationError} `adapter.invalid_option` - isolation 지정(미지원).
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    if (opts?.isolation !== undefined) {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        'mongodb: SQL isolation levels do not apply to MongoDB transactions — remove the "isolation" option (snapshot semantics are managed by the driver/readConcern).',
+        { details: { driver: 'mongodb', option: 'isolation', value: opts.isolation } },
+      )
+    }
     return this._instrument('withTransaction', { table: undefined }, async () => {
       // nested 거부 — 진행 중 트랜잭션이 있으면 즉시 throw (Sqlite 와 동일 정책·에러 코드, ADR-108).
       // 검사를 driver 호출 전에 두어, standalone(트랜잭션 미지원)에서도 nested 거부는 동작한다.
@@ -371,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

@@ -67,8 +67,9 @@
  * @module adapters/postgres-adapter
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaInternalError } from '../errors/http-errors.js'
 import { MegaDbAdapter } from './mega-db-adapter.js'
-import { resolveConnection, normalizePool, assertPlainObject, PG_POOL_SPEC } from './adapter-options.js'
+import { resolveConnection, normalizePool, assertPlainObject, resolveTxIsolation, PG_POOL_SPEC } from './adapter-options.js'
 import * as Registry from './registry.js'
 
 /**
@@ -89,6 +90,11 @@ import * as Registry from './registry.js'
  */
 
 export class MegaPostgresAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'postgres'} */
+  get driver() {
+    return 'postgres'
+  }
+
   /** @type {import('pg').Pool | null} 연결된 Pool 인스턴스 (connect 후에만). */
   #pool = null
   /** @type {import('pg').PoolConfig} _connect 에서 `new Pool()` 에 넘길 설정 (생성자에서 구성·고정). */
@@ -210,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,
       },
     }
@@ -234,17 +244,32 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
    * RELEASE SAVEPOINT) 후 `fn` 반환값을 그대로 돌려주고, throw 시 ROLLBACK(또는 ROLLBACK TO
    * SAVEPOINT) 후 원본 에러를 re-throw 한다.
    *
+   * `opts.isolation`(ADR-190) — top-level 이면 `BEGIN` 직후 `SET TRANSACTION ISOLATION LEVEL` 로
+   * 반영한다(PostgreSQL 은 트랜잭션 첫 쿼리 전이라 유효). 격리수준은 트랜잭션 시작 시 고정되므로
+   * nested(SAVEPOINT) 호출에 지정하면 `adapter.nested_isolation_unsupported` 로 거부한다.
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(client: import('pg').PoolClient) => Promise<T> | T} fn
+   * @param {{ isolation?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
+   * @throws {MegaInternalError} `adapter.nested_isolation_unsupported` - nested 호출에 isolation 지정.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    const isolationSql = resolveTxIsolation(opts?.isolation, 'postgres')
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const existing = this.#txContext.getStore()
       // nested — 진행 중 트랜잭션이 있으면 같은 클라이언트에 SAVEPOINT 를 건다(Sqlite 와 분기).
       if (existing !== undefined) {
+        if (isolationSql !== undefined) {
+          throw new MegaInternalError(
+            'adapter.nested_isolation_unsupported',
+            `${this.constructor.name}.withTransaction() cannot set an isolation level on a nested (SAVEPOINT) transaction — isolation is fixed when the top-level transaction starts (ADR-190).`,
+            { details: { adapter: this.constructor.name, isolation: opts?.isolation } },
+          )
+        }
         return this.#runSavepoint(existing, fn)
       }
       // top-level — 풀에서 클라이언트 1개 획득 후 BEGIN/COMMIT/ROLLBACK.
@@ -252,6 +277,8 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
       const client = await pool.connect()
       try {
         await client.query('BEGIN')
+        // 격리수준은 트랜잭션 첫 쿼리 전에만 설정 가능 — BEGIN 직후 반영(화이트리스트 SQL 조각이라 안전).
+        if (isolationSql !== undefined) await client.query(`SET TRANSACTION ISOLATION LEVEL ${isolationSql}`)
         let result
         try {
           result = await this.#txContext.run({ client, depth: 0 }, () => fn(client))

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

@@ -65,6 +65,11 @@ import * as Registry from './registry.js'
  */
 
 export class MegaSqliteAdapter extends MegaDbAdapter {
+  /** driver 식별자 — dialect 디스패치(getDialect)·CRUD 의 단일 출처(ADR-212). @returns {'sqlite'} */
+  get driver() {
+    return 'sqlite'
+  }
+
   /** @type {import('better-sqlite3').Database | null} 연결된 Database 인스턴스 (connect 후에만). */
   #db = null
   /** @type {string} DB 파일 경로 또는 ':memory:'. */
@@ -214,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',
@@ -226,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 },
     }
   }
 
@@ -237,14 +246,28 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
    * 성공 시 COMMIT 후 `fn` 반환값을 그대로 돌려주고, `fn` 이 throw 하면 ROLLBACK 후 원본 에러를
    * re-throw 한다. nested / 동시 호출은 `db.inTransaction` 으로 감지해 거부(ADR-105).
    *
+   * `opts.isolation`(ADR-190) — SQLite 트랜잭션은 항상 SERIALIZABLE 동작(단일 writer, 공식 문서)이라
+   * `'serializable'` 만 수용(no-op)하고 다른 값은 `adapter.invalid_option` 으로 명시 거부한다
+   * (조용히 무시하면 사용자가 다른 격리수준이 적용된 줄 오인 — P4).
+   *
    * hook(`onCallStart/onCallEnd`) + 상태 검증 + stats 누적은 `_instrument` 가 처리한다(ADR-077).
    *
    * @template T
    * @param {(db: import('better-sqlite3').Database) => Promise<T> | T} fn
+   * @param {{ isolation?: 'serializable' }} [opts] - 트랜잭션 옵션(ADR-190).
    * @returns {Promise<T>}
    * @throws {MegaInternalError} `adapter.nested_transaction_unsupported` - 이미 트랜잭션 진행 중.
+   * @throws {MegaValidationError} `adapter.invalid_option` - 'serializable' 외 isolation 값.
    */
-  async withTransaction(fn) {
+  async withTransaction(fn, opts) {
+    // 옵션 검증은 연결 상태와 무관한 설정 오류라 _instrument(상태 검증) 전에 fail-fast 한다.
+    if (opts?.isolation !== undefined && opts.isolation !== 'serializable') {
+      throw new MegaValidationError(
+        'adapter.invalid_option',
+        `sqlite transactions are always SERIALIZABLE — withTransaction "isolation" accepts only 'serializable'. Got ${JSON.stringify(opts.isolation)}.`,
+        { details: { driver: 'sqlite', option: 'isolation', value: opts.isolation } },
+      )
+    }
     return this._instrument('withTransaction', { table: undefined }, async () => {
       const db = /** @type {import('better-sqlite3').Database} */ (this.#db)
       if (db.inTransaction) {

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

@@ -9,7 +9,6 @@
  * @module cli/commands/console-cmd
  */
 import repl from 'node:repl'
-import { prepareRuntime } from '../../core/boot.js'
 import { MegaShutdown } from '../../lib/mega-shutdown.js'
 
 /**
@@ -38,6 +37,9 @@ export async function startConsole(
   projectRoot,
   { logger, replFactory = defaultReplFactory, out = console.log, shutdown = () => MegaShutdown.now(), setupSignals = (opts) => MegaShutdown.setupSignals(opts) } = {},
 ) {
+  // boot 그래프(fastify·OTel·pino 등)는 콘솔 기동 시점에만 로드 — scaffold.js 가 본 모듈을 정적
+  // import 하므로, 여기서 정적 import 하면 `mega help`/`g` 까지 전체 그래프를 지불하게 된다.
+  const { prepareRuntime } = await import('../../core/boot.js')
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
   out('mega: console ready — globals: ctx, config, mega')
   // prepareRuntime 이 어댑터/워커/wsHub 를 connect 하고 각자 MegaShutdown hook 을 자기등록한다. 정리 없이

package/src/cli/commands/new.js

@@ -15,6 +15,7 @@
  * @module cli/commands/new
  */
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { nameVariants } from '../template-engine.js'
@@ -76,10 +77,11 @@ function walk(dir, base, acc) {
 }
 
 /**
- * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로.
+ * 토큰 치환 — `sample-crud` 를 프로젝트명으로, package.json 의 모노레포 dep(`file:../..`)을 실제 버전으로,
+ * `.env` 의 SESSION_SECRET 을 프로젝트별 신규 시크릿으로.
  * @param {string} rel - 파일 상대경로.
  * @param {string} content - 원본 텍스트.
- * @param {{ name: string, version: string }} vars
+ * @param {{ name: string, version: string, sessionSecret: string }} vars
  * @returns {string}
  */
 function transformText(rel, content, vars) {
@@ -88,6 +90,12 @@ function transformText(rel, content, vars) {
     // 모노레포 로컬 링크 → 퍼블리시된 프레임워크 버전 핀. 스캐폴드된 프로젝트는 독립 패키지라 file: 가 안 풀린다.
     out = out.replace('"file:../.."', `"^${vars.version}"`)
   }
+  if (rel === '.env') {
+    // 세션 쿠키 HMAC 시크릿은 데모 값을 복제하면 모든 `mega new` 프로젝트가 같은 서명 키를 공유한다
+    // (세션 위조·cross-app 쿠키 수용 위험) — 프로젝트마다 신규 생성으로 치환한다. `.env.example` 은
+    // placeholder("change-me-...") 그대로 둔다(문서 역할).
+    out = out.replace(/^SESSION_SECRET=.*$/m, `SESSION_SECRET=${vars.sessionSecret}`)
+  }
   return out
 }
 
@@ -104,7 +112,9 @@ export function scaffoldProject(targetDir, { name, force = false } = {}) {
   const projectName = nameVariants(name ?? root.split(/[/\\]/).pop() ?? 'mega-app').kebab
   /** @type {string} */
   const version = JSON.parse(readFileSync(FRAMEWORK_PKG, 'utf8')).version
-  const vars = { name: projectName, version }
+  // 프로젝트별 세션 시크릿 — base64url(영숫자·-·_ 만)이라 .env 값·쉘 복붙에 안전(=/+// 회피).
+  const sessionSecret = randomBytes(32).toString('base64url')
+  const vars = { name: projectName, version, sessionSecret }
 
   /** @type {string[]} */ const written = []
   /** @type {string[]} */ const skipped = []