mega-framework 0.1.6 → 0.1.8

package/sample/crud/apps/main/views/auth/register.ejs

@@ -13,6 +13,21 @@
         <form method="post" action="/register" novalidate>
           <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+          <div class="mb-3">
+            <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+            <input
+              type="text"
+              class="form-control <%= invalid && invalid.username ? 'is-invalid' : '' %>"
+              id="username"
+              name="username"
+              value="<%= values && values.username ? values.username : '' %>"
+              placeholder="<%= t('field_username_ph', '예: hong123') %>"
+              autocomplete="username"
+              required
+            />
+            <div class="invalid-feedback"><%= t('field_username_required', '아이디를 입력하세요.') %></div>
+          </div>
+
           <div class="mb-3">
             <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
             <input
@@ -29,18 +44,44 @@
           </div>
 
           <div class="mb-3">
-            <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+            <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+            <input
+              type="text"
+              class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+              id="nickname"
+              name="nickname"
+              value="<%= values && values.nickname ? values.nickname : '' %>"
+              placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+              autocomplete="nickname"
+              required
+            />
+            <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+          </div>
+
+          <div class="mb-3">
+            <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
             <input
               type="email"
-              class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+              class="form-control"
               id="email"
               name="email"
               value="<%= values && values.email ? values.email : '' %>"
               placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
-              autocomplete="username"
-              required
+              autocomplete="email"
+            />
+          </div>
+
+          <div class="mb-3">
+            <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+            <input
+              type="tel"
+              class="form-control"
+              id="phone_number"
+              name="phone_number"
+              value="<%= values && values.phone_number ? values.phone_number : '' %>"
+              placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+              autocomplete="tel"
             />
-            <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
           </div>
 
           <div class="mb-4">

package/sample/crud/apps/main/views/users/edit.ejs

@@ -11,6 +11,19 @@
     <form method="post" action="/admin/users/<%= values.id %>" novalidate>
       <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+      <div class="mb-3">
+        <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+        <input
+          type="text"
+          class="form-control"
+          id="username"
+          value="<%= values && values.username ? values.username : '' %>"
+          readonly
+          disabled
+        />
+        <div class="form-text"><%= t('field_username_readonly', '아이디는 변경할 수 없습니다.') %></div>
+      </div>
+
       <div class="mb-3">
         <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
         <input
@@ -25,18 +38,42 @@
         <div class="invalid-feedback"><%= t('field_name_required', '이름을 입력하세요.') %></div>
       </div>
 
-      <div class="mb-4">
-        <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+      <div class="mb-3">
+        <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+          id="nickname"
+          name="nickname"
+          value="<%= values && values.nickname ? values.nickname : '' %>"
+          placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-3">
+        <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
         <input
           type="email"
-          class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+          class="form-control"
           id="email"
           name="email"
           value="<%= values && values.email ? values.email : '' %>"
           placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
-          required
         />
-        <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-4">
+        <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+        <input
+          type="tel"
+          class="form-control"
+          id="phone_number"
+          name="phone_number"
+          value="<%= values && values.phone_number ? values.phone_number : '' %>"
+          placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+        />
       </div>
 
       <div class="d-flex gap-2">

package/sample/crud/apps/main/views/users/list.ejs

@@ -24,7 +24,9 @@
       <thead>
         <tr>
           <th scope="col" class="text-end" style="width: 5rem"><%= t('col_id', 'ID') %></th>
+          <th scope="col"><%= t('col_username', '아이디') %></th>
           <th scope="col"><%= t('col_name', '이름') %></th>
+          <th scope="col"><%= t('col_nickname', '별명') %></th>
           <th scope="col"><%= t('col_email', '이메일') %></th>
           <th scope="col"><%= t('col_created', '생성일') %></th>
           <th scope="col" class="text-end"><%= t('col_actions', '관리') %></th>
@@ -34,8 +36,10 @@
         <% users.forEach(function (u) { %>
           <tr>
             <td class="text-end text-body-secondary"><%= u.id %></td>
-            <td class="fw-medium"><%= u.name %></td>
-            <td><%= u.email %></td>
+            <td class="fw-medium"><%= u.username %></td>
+            <td><%= u.name %></td>
+            <td><%= u.nickname %></td>
+            <td class="text-body-secondary"><%= u.email || '-' %></td>
             <td class="text-body-secondary small"><%= u.created_at %></td>
             <td class="text-end text-nowrap">
               <a href="/admin/users/<%= u.id %>/edit" class="btn btn-sm btn-outline-secondary"><%= t('action_edit', '수정') %></a>

package/sample/crud/apps/main/views/users/new.ejs

@@ -11,6 +11,21 @@
     <form method="post" action="/admin/users" novalidate>
       <input type="hidden" name="_csrf" value="<%= csrfToken %>" />
 
+      <div class="mb-3">
+        <label for="username" class="form-label"><%= t('field_username', '아이디') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.username ? 'is-invalid' : '' %>"
+          id="username"
+          name="username"
+          value="<%= values && values.username ? values.username : '' %>"
+          placeholder="<%= t('field_username_ph', '예: hong123') %>"
+          autocomplete="off"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_username_required', '아이디를 입력하세요.') %></div>
+      </div>
+
       <div class="mb-3">
         <label for="name" class="form-label"><%= t('field_name', '이름') %></label>
         <input
@@ -25,18 +40,55 @@
         <div class="invalid-feedback"><%= t('field_name_required', '이름을 입력하세요.') %></div>
       </div>
 
-      <div class="mb-4">
-        <label for="email" class="form-label"><%= t('field_email', '이메일') %></label>
+      <div class="mb-3">
+        <label for="nickname" class="form-label"><%= t('field_nickname', '별명') %></label>
+        <input
+          type="text"
+          class="form-control <%= invalid && invalid.nickname ? 'is-invalid' : '' %>"
+          id="nickname"
+          name="nickname"
+          value="<%= values && values.nickname ? values.nickname : '' %>"
+          placeholder="<%= t('field_nickname_ph', '예: 길동이') %>"
+          required
+        />
+        <div class="invalid-feedback"><%= t('field_nickname_required', '별명을 입력하세요.') %></div>
+      </div>
+
+      <div class="mb-3">
+        <label for="email" class="form-label"><%= t('field_email', '이메일') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
         <input
           type="email"
-          class="form-control <%= invalid && invalid.email ? 'is-invalid' : '' %>"
+          class="form-control"
           id="email"
           name="email"
           value="<%= values && values.email ? values.email : '' %>"
           placeholder="<%= t('field_email_ph', '예: hong@example.com') %>"
+        />
+      </div>
+
+      <div class="mb-3">
+        <label for="phone_number" class="form-label"><%= t('field_phone', '전화번호') %> <span class="text-body-secondary small">(<%= t('optional', '선택') %>)</span></label>
+        <input
+          type="tel"
+          class="form-control"
+          id="phone_number"
+          name="phone_number"
+          value="<%= values && values.phone_number ? values.phone_number : '' %>"
+          placeholder="<%= t('field_phone_ph', '예: 010-1234-5678') %>"
+        />
+      </div>
+
+      <div class="mb-4">
+        <label for="password" class="form-label"><%= t('field_password', '비밀번호') %></label>
+        <input
+          type="password"
+          class="form-control <%= invalid && invalid.password ? 'is-invalid' : '' %>"
+          id="password"
+          name="password"
+          autocomplete="new-password"
           required
         />
-        <div class="invalid-feedback"><%= t('field_email_required', '올바른 이메일을 입력하세요.') %></div>
+        <div class="form-text <%= invalid && invalid.password ? 'text-danger' : '' %>"><%= t('field_password_hint', '최소 8자 이상 입력하세요.') %></div>
       </div>
 
       <div class="d-flex gap-2">

package/sample/crud/docs/log_partition_design.mm.md

@@ -0,0 +1,23 @@
+# 🏗️ Log Table Partitioning Architecture
+
+## 📦 LogPartitionSchedule
+- **Role**: 로그 테이블 파티션 자동 관리 스케줄러
+- **Responsibilities**
+    - 매일 특정 시각(예: 새벽 2시)에 실행
+    - 미래(다음 달, 다다음 달) 파티션 테이블 자동 생성
+    - 과거(1개월 이전) 오래된 파티션 테이블 자동 분리(Detach) 및 삭제(Drop)
+- **Concurrency Control**
+    - `static lock = { lock: 'log-partition', ttl: 60000 }` (Redlock을 활용하여 스케줄러 인스턴스 간 중복 실행 방지)
+
+## 📦 Database Partitioned Tables
+- **Role**: 시간 기반 범위 파티셔닝(Range Partitioning by `created_at`)을 통한 로그 데이터 관리
+- **Properties**
+    - `action_logs` (PARTITION BY RANGE (created_at))
+    - `wallet_logs` (PARTITION BY RANGE (created_at))
+    - `detail_logs` (PARTITION BY RANGE (created_at))
+- **Responsibilities**
+    - 대량 로그 유입 시 쓰기 성능 향상 및 Vacuum 오버헤드 완화
+    - 보관 주기(1개월) 만료 데이터의 물리적 삭제 성능 최적화 (DROP PARTITION)
+- **Constraints**
+    - Primary Key에 파티션 키 `created_at` 포함 필수: `PRIMARY KEY (id, created_at)`
+    - Unique Index에 파티션 키 `created_at` 포함 필수: `UNIQUE (uuid, created_at)` 등

package/sample/crud/mega.config.js

@@ -4,6 +4,7 @@
  * App-only 키(databases 별명 등)는 apps/<name>/app.config.js 로.
  */
 import { CronCounterSchedule } from './apps/main/schedules/cron-counter-schedule.js'
+import { LogPartitionSchedule } from './apps/main/schedules/log-partition-schedule.js'
 import { EmailJob } from './apps/main/jobs/email-job.js'
 import { HashWorker } from './apps/main/workers/hash-worker.js'
 
@@ -135,7 +136,7 @@ export default {
   // },
 
   // 정기 작업(ADR-028/118) — `mega scheduler` 프로세스가 등록·실행한다(config.schedules, ADR-123).
-  schedules: [CronCounterSchedule],
+  schedules: [CronCounterSchedule, LogPartitionSchedule],
 
   // 영속 잡(ADR-028/119) — `mega worker` 프로세스(ecosystem instances:2)가 소비한다(config.jobs, ADR-123).
   jobs: [EmailJob],
@@ -168,10 +169,17 @@ export default {
     // (예시·미사용) liveness/readiness 경로 — 기본 '/health' · '/health/ready'.
     // paths: { live: '/health', ready: '/health/ready' },
     // (예시·미사용) 메트릭 resource service.name — 미지정 시 server.serviceName → MEGA_OTEL_SERVICE_NAME 폴백.
-    // serviceName: 'sample-crud',
+    serviceName: 'sample-crud',
   },
 
   // 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",
@@ -23,6 +23,6 @@
   },
   "devDependencies": {
     "concurrently": "^9.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   }
-}
+}

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

@@ -3,11 +3,11 @@
 # 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/cli/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
-#    읽는 env(src/cli/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
+#    src/lib/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
+#    읽는 env(src/lib/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
 #    MEGA_WSHUB_PORT(기본 3100) / MEGA_WSHUB_HOST(기본 0.0.0.0) / MEGA_WSHUB_HEARTBEAT_MS.
 #
 # 사용:
@@ -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/sample/simple/package.json

@@ -16,10 +16,10 @@
     "test": "mega test"
   },
   "dependencies": {
-    "mega-framework": "^0.1.1"
+    "mega-framework": "file:../.."
   },
   "devDependencies": {
     "concurrently": "^9.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.8"
   }
 }

package/src/adapters/adapter-manager.js

@@ -127,7 +127,8 @@ export function buildFromGlobalConfig(globalConfig, { registerShutdownHook = tru
   if (registerShutdownHook) {
     // 재빌드 안전 — 항상 1개만 유지(MegaApp 의 hublink hook 패턴과 동일).
     MegaShutdown.unregister(SHUTDOWN_HOOK)
-    MegaShutdown.register(SHUTDOWN_HOOK, async () => disconnectAll())
+    // 'adapters' stage — 서버/잡/앱 정리(어댑터를 쓰는 정리)가 모두 끝난 뒤 disconnect 된다.
+    MegaShutdown.register(SHUTDOWN_HOOK, async () => disconnectAll(), { stage: 'adapters' })
   }
 }
 

package/src/adapters/adapter-options.js

@@ -47,6 +47,36 @@ function invalidOption(message, details) {
   return new MegaValidationError('adapter.invalid_option', message, { details })
 }
 
+/**
+ * `withTransaction(fn, opts)` 의 isolation 값 → 표준 SQL 조각 (ADR-190).
+ * 화이트리스트 매핑이라 SQL 인젝션이 구조적으로 불가능하다(임의 문자열은 throw).
+ * @type {Record<string, string>}
+ */
+const TX_ISOLATION_SQL = {
+  'read uncommitted': 'READ UNCOMMITTED',
+  'read committed': 'READ COMMITTED',
+  'repeatable read': 'REPEATABLE READ',
+  serializable: 'SERIALIZABLE',
+}
+
+/**
+ * 트랜잭션 격리수준 옵션 검증 + SQL 조각 변환 (ADR-190). `undefined` 는 driver 디폴트 위임(undefined 반환).
+ * @param {unknown} isolation - `withTransaction` 의 `opts.isolation`.
+ * @param {string} driver - 에러 메시지용 driver 이름.
+ * @returns {string | undefined} `SET TRANSACTION ISOLATION LEVEL <조각>` 에 쓸 SQL 조각.
+ * @throws {MegaValidationError} `adapter.invalid_option` - 화이트리스트 외 값.
+ */
+export function resolveTxIsolation(isolation, driver) {
+  if (isolation === undefined) return undefined
+  if (typeof isolation !== 'string' || !Object.prototype.hasOwnProperty.call(TX_ISOLATION_SQL, isolation)) {
+    throw invalidOption(
+      `${driver}: withTransaction "isolation" must be one of 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'. Got ${JSON.stringify(isolation)}.`,
+      { driver, option: 'isolation', value: isolation },
+    )
+  }
+  return TX_ISOLATION_SQL[isolation]
+}
+
 /**
  * 양의 정수(> 0) 검증 (undefined 통과). 위반 시 `adapter.invalid_option` throw.
  * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
@@ -135,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>}
@@ -186,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) {
@@ -204,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 }
   }
 
   /**