mega-framework 0.1.7 → 0.1.8

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 토큰과 동일 집합이라 템플릿 작성 관례가 하나다.

package/types/cli/index.d.ts

@@ -96,29 +96,16 @@ export function resolveDb(setting: string | boolean | undefined | null): string
  */
 export function shouldReexecForWatch(flags: Record<string, string | boolean>, env: Record<string, string | undefined>): boolean;
 /**
- * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ * `mega start --watch` supervisor 의 **자식 인자**를 빌드한다 (ADR-220, ADR-182 개정).
  *
- * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - `--watch`/`--watch-ignore`(값 포함)는 부모(supervisor) 전용 — 자식 인자에서 제거한다
+ *   (가드 env 와 이중 안전으로 무한재귀 방지).
  * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
- * - watchPaths 가 있으면 `--watch-path=…`(이게 모듈 그래프 watch 를 **대체**하므로 앱 소스·전역설정 경로를
- *   명시해야 한다 — 실측 확인). 없으면 plain `--watch`(모듈 그래프 폴백).
- *
- * @param {Object} o
- * @param {string[]} o.argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
- * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만).
- * @param {string} o.selfPath - mega 진입 스크립트(`process.argv[1]`).
- * @param {string} o.execPath - node 바이너리(`process.execPath`).
- * @returns {{ command: string, args: string[] }}
- */
-export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }: {
-    argv: string[];
-    watchPaths: string[];
-    selfPath: string;
-    execPath: string;
-}): {
-    command: string;
-    args: string[];
-};
+ *
+ * @param {string[]} argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @returns {string[]} 자식 `mega` 인자(예: `['start','--port','3000','--cluster','1']`).
+ */
+export function buildWatchChildArgs(argv: string[]): string[];
 /**
  * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
  * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
@@ -178,24 +165,24 @@ export function collectRegistrations(global: Object, host: import("../lib/mega-p
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaJobWorker>}
+ * @returns {Promise<import('../lib/mega-job-worker.js').MegaJobWorker>}
  */
 export function runWorkerHost(projectRoot: string, logger?: {
     debug?: Function;
     info?: Function;
     warn?: Function;
-}): Promise<MegaJobWorker>;
+}): Promise<import("../lib/mega-job-worker.js").MegaJobWorker>;
 /**
  * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaScheduler>}
+ * @returns {Promise<import('../lib/mega-schedule.js').MegaScheduler>}
  */
 export function runSchedulerHost(projectRoot: string, logger?: {
     debug?: Function;
     info?: Function;
     warn?: Function;
-}): Promise<MegaScheduler>;
+}): Promise<import("../lib/mega-schedule.js").MegaScheduler>;
 /**
  * 마이그레이션 대상 DB 어댑터 해석 — `services.databases` 의 globalKey 로 조회한다. `--db <key>` 미지정
  * 시 유일 선언 db, 그게 아니면 `primary`, 둘 다 아니면(다중·미선언) fail-fast 로 명시를 요구한다.
@@ -245,5 +232,3 @@ export const BUILTIN_COMMANDS: Set<string>;
 /** CLI 사용법 텍스트 — commander 자동 생성(ADR-195) + 플러그인 명령 안내. 명령·옵션 정의가 곧 도움말의
  * 단일 정본이라 수기 USAGE 와의 드리프트가 없다. */
 export const USAGE: string;
-import { MegaJobWorker } from '../lib/mega-job-worker.js';
-import { MegaScheduler } from '../lib/mega-schedule.js';

package/types/cli/watch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern: string): RegExp;
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig?: {
+    ignore?: unknown;
+}, cliIgnore?: string | undefined): string[];
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel: string, regexps: RegExp[]): boolean;
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs, watchFn }: {
+    projectRoot: string;
+    watchPaths: string[];
+    ignore: string[];
+    spawnChild: () => import("node:child_process").ChildProcess;
+    out: (msg: string) => void;
+    debounceMs?: number;
+    watchFn?: (dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => {
+        close(): void;
+    };
+}): Promise<number>;
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot: string): string[];

package/types/core/ctx-builder.d.ts

@@ -63,6 +63,29 @@ export function getHttpCtx({ app, req, reply }: {
     req: import("fastify").FastifyRequest;
     reply: import("fastify").FastifyReply;
 }): Record<string, any>;
+/**
+ * **lazy** HTTP ctx — 실제 ctx 빌드를 첫 속성 접근 시점까지 미루는 요청당 프록시 (G1 H-1, ADR-214).
+ *
+ * hot path 단일 최대 프레임워크 비용이 "핸들러가 ctx 를 안 써도 매 요청 무조건 buildHttpCtx"
+ * (1,615 B + ≈0.7 µs/req, CPU 2.3% — audit-G1 실측)였다. 이 프록시는 생성 비용이 객체 1개 수준이고,
+ * 핸들러·미들웨어가 ctx 의 속성을 **처음 만질 때만** {@link getHttpCtx} 로 실 ctx 를 만든다(이후 캐시).
+ *
+ * 호환성: canonical 시그니처 `(req, reply, ctx)` 는 그대로 — 모든 핸들러가 여전히 3번째 인자를 받고,
+ * 참조하는 순간부터는 기존과 동일한 실 ctx 표면(ADR-134 요청당 공유 포함)이다. 프록시 자체도 요청당
+ * 1개로 캐시되어 미들웨어와 핸들러가 **동일 객체**(`===`)를 받는다. 모든 트랩이 실 ctx 로 위임되므로
+ * `in`/spread/`Object.keys`/getter·setter(`ctx.user=`) 동작이 보존된다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getLazyHttpCtx({ app, req, reply }: {
+    app: import("./mega-app.js").MegaApp | null;
+    req: import("fastify").FastifyRequest;
+    reply: import("fastify").FastifyReply;
+}): Record<string, any>;
 /**
  * - 앱의 `app.config.js` 별명 선언 (alias → globalKey).
  */

package/types/core/hub-link.d.ts

@@ -117,7 +117,9 @@ export class MegaHubLink {
     /**
      * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
      *
-     * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+     * 초기 연결은 retry 유무와 무관하게 **단 1회** 시도한다. `retry` 옵션이 있으면 실패 시 백그라운드
+     * 재연결(지수 백오프)로 전환하고 reject 한다 — 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+     * 호출부(boot)는 reject 를 warn 으로 받고 부팅을 계속한다(허브 다운이 부팅을 막지 않는 계약).
      *
      * @param {Object} [opts]
      * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에

package/types/core/index.d.ts

@@ -14,7 +14,7 @@ export { bootApp, buildBootContext } from "./boot.js";
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from "./envelope.js";
 export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from "./pipeline.js";
 export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from "./ajv-mapper.js";
-export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from "./ctx-builder.js";
+export { buildHttpCtx, getHttpCtx, getLazyHttpCtx, buildAdapterAccessors } from "./ctx-builder.js";
 export { createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN } from "./ws-message.js";
 export { MegaWsConnection, driveWsConnection, createPlainCodec, createAspCodec, rejectUpgrade, CLOSE_CODE_DECRYPT_FAILED, CLOSE_CODE_INTERNAL_ERROR } from "./ws-upgrade.js";
 export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from "./ws-compression.js";

package/types/core/mega-app.d.ts

@@ -35,7 +35,7 @@ export class MegaApp {
      * @param {Object|false} [opts.helmet] - fastify-helmet 옵션 (보안 헤더). false=미등록, undefined=디폴트 ON
      *   (ADR-047/127). 라우트 옵션 오버라이드는 완전 교체(ADR-073).
      * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부, 안전 디폴트).
-     * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 100/min, ADR-048).
+     * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(IP당 1000/min, ADR-048/197).
      *   멀티 인스턴스 분산 카운팅은 `caches.rate` 별명(Redis), 미선언 시 in-memory 폴백.
      * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
      *   ADR-051: JSON 요청은 토큰 면제+Origin 검증, 폼 요청만 토큰 검증.

package/types/core/pipeline.d.ts

@@ -1,7 +1,8 @@
 /**
  * 미들웨어를 Fastify 가 async preHandler 로 인식하는 arity-2 래퍼로 감싸고, canonical ctx 를
  * 3번째 인자로 주입한다 — 핸들러·글로벌 미들웨어와 동일한 `(req, reply, ctx)` 계약(ADR-134/184).
- * getHttpCtx 는 요청당 캐싱이라 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
+ * ctx 는 **lazy 프록시**(ADR-214) — 미들웨어가 실제로 속성을 만질 때만 빌드되고, 요청당 캐싱이라
+ * 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
  *
  * @param {Function} fn - `(req, reply, ctx?)` 미들웨어 (arity-2 도 하위 호환 — 3번째 인자 무시).
  * @param {import('./mega-app.js').MegaApp | null} [app] - ctx 의 어댑터·서비스 접근자 출처(없으면 null).

package/types/core/security.d.ts

@@ -21,7 +21,7 @@
  * @param {string[]} [opts.hosts] - 앱 도메인 목록(CSRF Origin 검증 allowlist, ADR-051).
  * @param {Object|false} [opts.helmet] - fastify-helmet 옵션. false=미등록, undefined=디폴트 ON.
  * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부).
- * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(100/min).
+ * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(1000/min, ADR-214).
  * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
  * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any } }} [opts.asp] -
  *   ASP 설정. `masterSecret` + `http.enabledPaths`(비어있지 않음)가 둘 다 있을 때만 HTTP ASP 등록.
@@ -53,9 +53,9 @@ export function registerSecurityPlugins(fastify: import("fastify").FastifyInstan
         warn?: Function;
     };
 }): SecuritySummary;
-/** rate-limit 기본값 (ADR-048: IP 당 100 req/min). 사용자 config 로 완전 교체(ADR-073). */
+/** rate-limit 기본값 (IP 당 1000 req/min — ADR-048 의 100/min 은 평상 트래픽도 429 를 만드는 운영 함정이라 상향, ADR-214). 사용자 config 로 완전 교체(ADR-073). */
 export const DEFAULT_RATE_LIMIT: Readonly<{
-    max: 100;
+    max: 1000;
     timeWindow: "1 minute";
 }>;
 /**

package/types/core/session-store.d.ts

@@ -14,5 +14,12 @@ export function createSessionStore(storeConfig: {
 }, defaults?: {
     ttlMs?: number;
 }): import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+/**
+ * file driver 만료 스캔 cleanup 기본 주기(1시간, ms) — ADR-046 의 "file 모드 cleanup 자동" 약속 구현(ADR-215).
+ * 어댑터 자체 디폴트는 0(off)이라, 팩토리 경유 생성(=프레임워크 부팅 경로)에서만 기본 주기를 주입한다.
+ * 만료 파일의 lazy 삭제는 같은 sid 재접근 시에만 일어나므로, 주기 스캔이 없으면 미접근 만료 세션이
+ * 디스크에 무한 누적된다(G5 audit M-3). `cleanupIntervalMs: 0` 명시로 옵트아웃(외부 cron/scheduler 운용 시).
+ */
+export const DEFAULT_FILE_CLEANUP_INTERVAL_MS: 3600000;
 /** 지원 세션 driver 목록(테스트·문서용). */
 export const SESSION_STORE_DRIVERS: readonly string[];

package/types/core/ws-roster.d.ts

@@ -57,6 +57,15 @@ export class MegaWsRedisRoster {
      * @param {string} channel @param {string} sessionId @param {RosterMember} member @returns {Promise<void>}
      */
     add(channel: string, sessionId: string, member: RosterMember): Promise<void>;
+    /**
+     * ioredis pipeline.exec() 결과(`[err, res][]`)에서 첫 명령 오류를 throw 한다 — pipeline 은 명령별
+     * 오류를 reject 가 아니라 결과 배열에 싣기 때문에, 묵히면 호출부의 기존 실패 처리(catch+warn)가
+     * 더는 동작하지 않는다(직렬 await 시절의 throw 계약 유지).
+     * @param {Array<[Error | null, any]> | null} results
+     * @returns {void}
+     * @private
+     */
+    private _throwFirstPipelineError;
     /**
      * 채널 roster 에서 멤버 제거(disconnect).
      * @param {string} channel @param {string} sessionId @returns {Promise<void>}
@@ -78,7 +87,10 @@ export class MegaWsRedisRoster {
      */
     startHeartbeat(): void;
     /**
-     * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+     * 로컬 멤버 전체의 `expiresAt` 을 한 pipeline 으로 일괄 갱신. 직렬 add 루프(멤버당 2 RT)는 멤버
+     * 1,000 에 주기당 수백 ms — 갱신 지연이 TTL 윈도를 침식해 살아있는 세션이 lazy 만료될 수 있었다.
+     * pipeline 이면 단일 왕복 수준(실측 ~200×). 채널 키 PEXPIRE 는 채널당 1회만 싣는다.
+     * @returns {Promise<void>} @private
      */
     private _refreshLocal;
     /**

package/types/core/ws-upgrade.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max }?: {
+    maxTotalBufferedBytes?: number;
+}): {
+    maxTotalBufferedBytes: number;
+};
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget(): void;
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn: MegaWsConnection): void;
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now?: number): void;
 /**
  * 라우트 opts 의 `heartbeatMs` 를 검증해 반환한다. 미지정 → 기본 30초, `0` = liveness 끔.
  * 무효값(음수/비정수/비숫자)은 운영 실수 — 조용히 보정하지 않고 warn 로그 후 기본값을 쓴다
@@ -116,6 +136,15 @@ export const CLOSE_CODE_SLOW_CONSUMER: 1013;
 export const CLOSE_CODE_REQUEUE: 4503;
 /** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
 export const DEFAULT_MAX_BUFFERED_BYTES: number;
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES: number;
 /**
  * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
  * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지

package/types/lib/mega-circuit-breaker.d.ts

@@ -182,8 +182,10 @@ export type MegaCircuitBreakerOptions = {
      */
     rollingCountBuckets?: number;
     /**
-     * - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
-     * (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+     * - 롤링 윈도우에 이 횟수만큼 호출이 쌓이기 전엔 실패율이
+     * 높아도 open 안 함(표본 부족 조기 trip 방지). 0=비활성. ⚠️ opossum 정본값(0)과 다른 프레임워크
+     * 디폴트 — 0 이면 부팅 직후/저빈도 호출에서 **첫 실패 1건**이 실패율 100% 가 돼 즉시 30s 차단되는
+     * 풋건이라 5 로 올렸다. opossum 원 동작이 필요하면 명시적으로 0 을 지정.
      */
     volumeThreshold?: number;
     /**

package/types/lib/mega-health.d.ts

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