mega-framework 0.1.0

package/src/core/mega-app.js

@@ -0,0 +1,1138 @@
+// @ts-check
+import Fastify from 'fastify'
+import { WebSocketServer } from 'ws'
+import { wrapEnvelope, REPLY_START_SYMBOL } from './envelope.js'
+import { buildErrorHandler } from './error-mapper.js'
+import { Router } from './router.js'
+import { driveWsConnection, createPlainCodec, createAspCodec, rejectUpgrade } from './ws-upgrade.js'
+import { buildPerMessageDeflate } from './ws-compression.js'
+import { MegaAspTerminator } from '../lib/asp/ws-terminator.js'
+import { MegaHubLink } from './hub-link.js'
+import { HUB_MESSAGE_TYPES } from '../lib/hub-protocol.js'
+import * as MegaHealth from '../lib/mega-health.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+import { buildAdapterAccessors, getHttpCtx } from './ctx-builder.js'
+import { registerSecurityPlugins } from './security.js'
+import { registerMultipart } from './multipart.js'
+import { registerSession } from './session.js'
+import { registerI18n } from './i18n.js'
+import { registerTemplate } from './template.js'
+import { registerFormbody } from './formbody.js'
+import { registerStaticAssets } from './static-assets.js'
+import { registerOpenapi } from './openapi.js'
+import { createSessionStore } from './session-store.js'
+import { MegaBruteForce } from '../lib/mega-brute-force.js'
+import { MegaAspDecryptError } from '../lib/asp/errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import * as MegaMetrics from '../lib/mega-metrics.js'
+import { collectCluster } from './cluster-metrics.js'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** HTTP 루트 span 핸들을 reply 에 보관하는 전용 symbol(onResponse 가 꺼내 종료). */
+const HTTP_SPAN_SYMBOL = Symbol('mega.httpSpan')
+
+/**
+ * 브라우저↔Bridge WS 프레임 최대 크기 디폴트 (bytes, L-3 / ADR-099).
+ * 1 MiB — Hub(`DEFAULT_MAX_PAYLOAD_BYTES`, src/cli/ws-hub.js)와 대칭. 초과 프레임은 ws 가 1009 close.
+ * core→cli 역방향 import 를 피하려 값을 여기 별도 정의(두 곳 모두 1 MiB 로 동일).
+ */
+export const DEFAULT_WS_MAX_PAYLOAD_BYTES = 1_048_576
+
+/**
+ * MegaApp — 한 도메인 집합(hosts)에 대응하는 Fastify 인스턴스 래퍼.
+ *
+ * baseline — Fastify 인스턴스 보유, listen/close 라이프사이클.
+ * 라우터 등록·미들웨어 통합.
+ * 자동 envelope (ADR-018) + 글로벌 에러 핸들러 (ADR-025/090).
+ *
+ * ADR-002 (Fastify), ADR-063 (앱당 Fastify 인스턴스 격리), ADR-004 (dev *.localhost).
+ */
+export class MegaApp {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.name - 앱 이름 (apps/<name> 폴더와 일치, ADR-067 검증됨)
+   * @param {string[]} [opts.hosts] - 도메인 매핑 (scaffold 모드 필수, single 모드 옵셔널)
+   * @param {'scaffold'|'single'} [opts.mode='scaffold'] - 부팅 모드 (ADR-013)
+   * @param {Object} [opts.fastifyOptions] - Fastify 생성 옵션 (logger 등)
+   * @param {import('pino').Logger|false} [opts.logger] - pino 로거 인스턴스 (ADR-023/141). bootApp 이
+   *   `global.logger`(MegaLoggerConfig)로 만들어 모든 앱에 주입한다. 미주입이면 `false`(무로그). Fastify 가
+   *   요청별 child(`req.log`, reqId 바인딩)를 만들고, `ctx.log` 가 이를 노출한다(trace_id 는 mixin 자동 주입).
+   * @param {boolean} [opts.exposeInternalDetails=false] - true 면 일반 Error 메시지를
+   *   envelope 에 노출 (디버그용). 기본 false — 보안 (ADR-025).
+   * @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).
+   *   멀티 인스턴스 분산 카운팅은 `caches.rate` 별명(Redis), 미선언 시 in-memory 폴백.
+   * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
+   *   ADR-051: JSON 요청은 토큰 면제+Origin 검증, 폼 요청만 토큰 검증.
+   * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any }, websocket?: { namespaces?: string[] } }} [opts.asp] -
+   *   ASP 옵트인. `masterSecret` 있으면 모든 WS 프레임이 `E:`/`P:` prefix 코덱 경유;
+   *   `websocket.namespaces` 에 포함된 경로만 기본 암호화(`E:`), 나머지는 평문(`P:`, ADR-083). `http.enabledPaths`
+   *   가 있으면 그 glob 경로에 HTTP ASP terminator 자동 등록(ADR-127). 미지정 시 raw JSON WS.
+   * @param {{ compression?: import('./ws-compression.js').WsCompressionConfig, maxPayloadBytes?: number }} [opts.websocket] -
+   *   브라우저↔Bridge WS 옵션 (ADR-078 / MegaWebsocketAppConfig). `compression`
+   *   블록으로 per-message deflate 옵트인. 디폴트 OFF. 부팅 시 threshold 음수 / serverMaxWindowBits
+   *   범위(9~15) 위반 throw. `maxPayloadBytes` 는 WS 프레임 최대 크기(L-3, 디폴트 1 MiB — Hub 와 대칭);
+   *   초과 프레임은 ws 가 1009 close. 양의 정수 아니면 디폴트로 폴백(부팅 검증은 config-validator 가 throw).
+   * @param {Record<string, string>} [opts.databases] - 어댑터 별명 맵 `{ alias: globalKey }` (ADR-102
+   *   글로벌 공유). `ctx.db(alias)` 가 globalKey 로 바꿔 전역 공유 인스턴스(MegaAdapterManager)를 반환.
+   *   실 인스턴스는 `mega.config.js` 의 `services.databases.<globalKey>` 에 정의되고 매니저가 소유·connect.
+   * @param {Record<string, string>} [opts.caches] - 캐시 별명 맵 `{ alias: globalKey }` (`ctx.cache(alias)`).
+   * @param {Record<string, string>} [opts.buses] - 버스 별명 맵 `{ alias: globalKey }` (`ctx.bus(alias)`).
+   * @param {Record<string, string>} [opts.locks] - 락 별명 맵 `{ alias: globalKey }` (`ctx.lock(alias)`, ADR-113).
+   * @param {{ maxFileSize?: number, maxFiles?: number, allowedMimeTypes?: string[] }} [opts.upload] -
+   *   파일 업로드 옵트인 (MegaUploadConfig, per ADR-133). 있으면 `@fastify/multipart` 를 자동 등록해
+   *   `req.file()`/`req.files()`/`req.saveUploads(dir)` 를 제공한다(없으면 multipart 요청 415).
+   *   `maxFileSize`(디폴트 10 MB)·`maxFiles`(미지정=무제한)·`allowedMimeTypes`(빈 배열=전부 허용, `image/*`
+   *   와일드카드 지원). MIME 화이트리스트 위반은 415, 크기·개수 초과는 413. CSRF(폼 토큰)는 보안 플러그인이,
+   *   ASP(body 평문 통과)는 ASP terminator 가 자동 통합. 트레이싱 `mega.upload.*` + 메트릭 `mega_upload_*`.
+   * @param {false | { store: { driver: 'file'|'redis', [k: string]: any }, secret?: string, ttlMs?: number, rolling?: boolean, cookie?: object, csrf?: boolean }} [opts.session] -
+   *   세션 옵트인 (ADR-129/046). `store` = 백엔드(file/redis) inline config. `secret` =
+   *   쿠키 HMAC 시크릿(미지정 시 `opts.sessionSecret` — bootApp 이 global `server.sessionSecret` 주입).
+   *   `ttlMs`(기본 24h)·`rolling`(기본 true)·`cookie`(httpOnly/secure/sameSite). `csrf:true` 면 CSRF 를
+   *   세션 모드로(시크릿을 세션 `_csrf` 키에 바인딩). `false`/미지정 → 세션 비활성.
+   * @param {string} [opts.sessionSecret] - 세션 쿠키 HMAC 시크릿(global `server.sessionSecret`). `session.secret` 미지정 시 사용.
+   * @param {{ default?: string, available?: string[], fallback?: string, cookieName?: string, autoComplete?: { enabled?: boolean, dir?: string, debounceMs?: number }, localesDir?: string, resources?: object, exposeTranslations?: boolean, translationsPath?: string }} [opts.i18n] -
+   *   i18n 옵트인 (ADR-037/038/039/135). 있으면 앱 전용 `i18next` 인스턴스를 등록해
+   *   `req.lang`/`req.t`/`req.setLocale`/`req.translations` + `ctx.lang`/`ctx.t` 를 제공한다(없으면 ctx.t 는
+   *   passthrough). 언어 결정은 **쿠키만**(ADR-038, `cookieName` 디폴트 `mega.lang`). scope 분리(server/client,
+   *   ADR-039) — `ctx.t()` 는 server scope, `GET /i18n/translations` 는 client scope 만 노출. dev 면 누락 키
+   *   자동 생성(saveMissing axion 패턴, `autoComplete`). 트레이싱 `mega.i18n.*` + 메트릭 `mega_i18n_*`.
+   * @param {{ dir?: string, layoutDir?: string, partialsDir?: string, defaultLayout?: string, cache?: boolean }} [opts.views] -
+   *   서버사이드 템플릿 옵트인 (ADR-011/136 — EJS + ejs-mate). `dir`(뷰 루트, 예
+   *   `apps/<name>/views`)이 있을 때만 `reply.render(view, data, { layout })`(정본 res.render) + `ctx.render`
+   *   를 제공한다(없으면 미정의 → 호출 시 fail-fast). 렌더 data 에 요청별 i18n `t`/`lang` 자동 병합(다국어 뷰).
+   *   XSS auto-escape(`<%=`) 기본 + 경로 탐색 차단. 트레이싱 `mega.template.*` + 메트릭 `mega_template_*`.
+   * @param {{ enabled?: boolean, path?: string, info?: { title?: string, version?: string, description?: string }, auth?: Function[], theme?: Object }} [opts.openapi] -
+   *   OpenAPI/Swagger 옵트인 (MegaOpenApiAppConfig, ADR-070/140 — `@fastify/swagger` + `@fastify/swagger-ui`).
+   *   `enabled:true` 일 때만 라우트 schema 를 OpenAPI 3.x 명세로 수집하고 `path`(디폴트 `/docs`)에 swagger-ui 를
+   *   등록한다(디폴트 OFF — 프로덕션 노출 방지). `info`={title,version,description}. `auth` 미들웨어 배열로 docs
+   *   접근 보호(빈 배열=공개, `(req, reply, ctx)` 시그니처). `theme`=swagger-ui uiConfig. 라우트 옵션
+   *   `openapi:{tags,summary,description,deprecated}` 가 명세에 반영(router.js).
+   * @param {{ enabled?: boolean, dir?: string, prefix?: string, cacheControl?: string, dotfiles?: boolean }} [opts.staticAssets] -
+   *   정적 자산 옵트인 (MegaStaticAssetsAppConfig, ADR-071/139 — `@fastify/static`). `enabled:true` + 실존 `dir`
+   *   (서빙 루트, 예 `apps/<name>/public`)일 때만 `${prefix}/<파일>`(prefix 디폴트 `/static`)로 디스크 파일을 서빙
+   *   (디폴트 OFF). `cacheControl` = raw `Cache-Control` 헤더 문자열(예 `'public, max-age=3600'`). `dotfiles`
+   *   디폴트 false(`.git`/`.env` 차단). `enabled:true` 인데 `dir` 누락/미존재 시 프로덕션 부팅 throw / dev warn+skip.
+   *   prefix 가 `health.metricsPath` 와 같으면 부팅 throw(ADR-072).
+   * @param {{ enabled?: boolean, paths?: { live?: string, ready?: string }, exposeMetrics?: boolean, metricsPath?: string, metricsAllowList?: string[] }} [opts.health] -
+   *   운영 관측성 config(Global-only, ADR-072/131). bootApp 이 global `health` 블록을 주입한다.
+   *   `exposeMetrics:true` 면 `metricsPath`(디폴트 `/metrics`)에 Prometheus `/metrics` 라우트를 등록(보안 면제).
+   *   `metricsAllowList` = 접근 허용 IP/CIDR(빈 배열이면 메인 포트 전체 노출, ADR-131). metricsPath 가 health
+   *   경로와 충돌하면 부팅 throw. SDK 초기화(MegaMetrics.init)는 bootApp/prepareRuntime 이 담당.
+   * @param {Array<{ plugin: Function, opts?: object }>} [opts.plugins] - 플러그인이 `mega.app.use(...)`
+   *   로 등록한 Fastify 플러그인 묶음(정본 §14 hook표 — "모든 앱 인스턴스에 등록"). 부팅 orchestrator
+   *   (`bootApp`)가 `MegaPluginHost.fastifyPlugins` 를 모든 앱에 주입한다(ADR-123). 각 원소는
+   *   `this.fastify.register(plugin, opts)` 로 등록.
+   * @param {Function[]} [opts.globalMiddlewares] - 플러그인이 `mega.middlewares.global(...)` 로 등록한
+   *   글로벌 미들웨어(모든 라우트 적용). orchestrator 가 주입한다. 계약: `async (req, reply, ctx) => void`
+   *   — 라우트 핸들러와 동일한 canonical 시그니처(ADR-074/134). `ctx` 는 요청당 1회 만들어 핸들러와
+   *   공유하므로, 미들웨어가 `ctx` 에 심은 값을 핸들러가 본다. 기존 `(req, reply)` 미들웨어는 3번째
+   *   인자를 무시하므로 하위 호환.
+   */
+  constructor(opts) {
+    if (!opts || typeof opts.name !== 'string' || opts.name.length === 0) {
+      throw new Error('MegaApp: name is required')
+    }
+    this.name = opts.name
+    this.hosts = Array.isArray(opts.hosts) ? [...opts.hosts] : []
+    this.mode = opts.mode === 'single' ? 'single' : 'scaffold'
+
+    // 어댑터 별명 맵 (app.config.js 의 databases/caches/buses: { alias → globalKey }, ADR-102 글로벌
+    // 공유). 별명→globalKey→전역 공유 인스턴스(MegaAdapterManager)로 해석하는 ctx.db/cache/bus 접근자를
+    // 앱당 한 번 만들어 둔다(요청과 무관하게 안정적). 인스턴스 자체는 전역 매니저가 소유·connect.
+    /** @type {import('./ctx-builder.js').AdapterAccessors} */
+    this._adapterAccessors = buildAdapterAccessors(
+      { databases: opts.databases, caches: opts.caches, buses: opts.buses, locks: opts.locks },
+      opts.name,
+    )
+
+    /** @type {MegaBruteForce|null} ctx.bruteForce 단축의 lazy 인스턴스(앱당 1개 재사용). */
+    this._bruteForce = null
+
+    /**
+     * name → 서비스 클래스. 부팅 시 services-loader 가 `apps/<name>/services/*.js` 를 스캔해 채운다
+     * (ADR-148). 요청별 `ctx.services.<name>` lazy DI 가 이 맵을 보고 인스턴스화한다. 기본은 빈 Map
+     * (서비스 없는 앱·standalone 테스트).
+     * @type {Map<string, Function>}
+     */
+    this._serviceRegistry = new Map()
+
+    /** @type {string|null} OpenAPI 옵트인 시 swagger-ui 경로(ADR-140). envelope onRoute 가 이 경로를 제외. */
+    this._openapiPath = null
+
+    // WS ASP 옵트인 정규화. masterSecret 없으면 null = 평문 WS.
+    this._wsAsp = MegaApp._normalizeWsAsp(opts.asp)
+    // 브라우저↔Bridge WS 압축 (ADR-078). enabled=false → false (압축 OFF).
+    // 생성자에서 build → 잘못된 threshold/windowBits 면 즉시 throw(부팅 fail-fast).
+    /** @type {false | Object} _ensureWss 의 WebSocketServer perMessageDeflate 로 전달. */
+    this._wsPerMessageDeflate = buildPerMessageDeflate(opts.websocket?.compression, 'websocket.compression')
+    // WS 프레임 최대 크기 (L-3, ADR-099). Hub 와 동일하게 양의 정수만 인정, 그 외 디폴트 1 MiB 폴백.
+    // 부팅(config-validator)에서 잘못된 값은 이미 throw 되지만, 직접 생성 경로(single·테스트)는 폴백.
+    const maxPayloadRaw = opts.websocket?.maxPayloadBytes
+    /** @type {number} _ensureWss 의 WebSocketServer maxPayload 로 전달. */
+    this._wsMaxPayloadBytes =
+      Number.isInteger(maxPayloadRaw) && /** @type {number} */ (maxPayloadRaw) > 0
+        ? /** @type {number} */ (maxPayloadRaw)
+        : DEFAULT_WS_MAX_PAYLOAD_BYTES
+    /** @type {Router|null} single 모드 직접 등록(app.ws)용 lazy 라우터. */
+    this._router = null
+    /** @type {WebSocketServer|null} noServer 모드 WS 핸드셰이커 (lazy). */
+    this._wss = null
+    /** @type {MegaHubLink|null} hub 연결 (scaffold 권장). */
+    this._hubLink = null
+    /** ns(=ws path) → 활성 로컬 연결 집합 (hub broadcast 의 local fan-out 용). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    this._wsConns = new Map()
+    /** userId → 활성 로컬 연결 집합 (DIRECT 타겟팅, H-latent guard). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+    this._userConns = new Map()
+    /** sessionId → 활성 로컬 연결 1개 (세션단위 JOIN/LEAVE). @type {Map<string, import('./ws-upgrade.js').MegaWsConnection>} */
+    this._sessionConns = new Map()
+    /** @type {string[]} connectHub 으로 구독한 채널. */
+    this._hubChannels = []
+    /** connectHub 의 bridgeId (재연결 재구독·세션 JOIN 에 재사용). @type {string|null} */
+    this._hubBridgeId = null
+
+    this.fastify = Fastify({
+      // pino 로거(ADR-023/141) — bootApp 이 global.logger 로 만든 **인스턴스**를 주입(opts.logger). Fastify v5 는
+      // 인스턴스를 `loggerInstance` 로 받는다(`logger` 는 config 객체/bool 전용). 미주입이면 logger:false(무로그,
+      // 기존 동작·테스트 호환). 인스턴스를 받으면 Fastify 가 요청별 child(reqId 바인딩)를 만든다.
+      ...(opts.logger ? { loggerInstance: opts.logger } : { logger: false }),
+      // request id 자동 부여는 Fastify v5 기본 제공 (meta.request_id 용)
+      ...opts.fastifyOptions,
+    })
+
+    // 1) 응답 시작 시각 기록 (meta.took_ms 용, ADR-014)
+    this.fastify.addHook('onRequest', async (req, reply) => {
+      // REPLY_START_SYMBOL 은 Fastify 타입에 없는 우리 전용 symbol 키 — 부착 시 cast.
+      ;(/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[REPLY_START_SYMBOL] =
+        Date.now()
+    })
+
+    // 1b) HTTP 루트 span (ADR-126) — 옵트인 OFF 면 isEnabled() false 라 즉시 return(0 비용).
+    //     onRequest 에서 span 시작 + 활성 컨텍스트 진입(enterWith) → 핸들러의 ctx.tracer.span·어댑터 호출이
+    //     이 span 의 자식으로 중첩됨. onResponse 에서 status_code 기록 후 종료. 각 HTTP 요청은 독립 async
+    //     context 라 enterWith 가 요청 간 누수 없이 격리된다(실측 확인 — ADR-126).
+    this.fastify.addHook('onRequest', async (req, reply) => {
+      if (!MegaTracing.isEnabled()) return
+      const route = /** @type {any} */ (req).routeOptions?.url ?? req.url
+      const host = String(req.headers.host ?? '').split(':')[0]
+      const handle = MegaTracing.enterHttpSpan({
+        method: req.method,
+        route,
+        path: req.url,
+        host,
+        app: this.name,
+      })
+      ;(/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL] = handle
+    })
+    // onError 는 핸들러/직렬화 throw 시 호출 — 예외를 span 에 기록(상태 ERROR). 종료는 onResponse 담당.
+    this.fastify.addHook('onError', async (req, reply, err) => {
+      const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
+      handle?.setError(err)
+      // 보안 거부(ASP 복호/drift/replay/signal)도 활성 span 에 사유 기록(ADR-127).
+      // CSRF/rate-limit 은 security.js 가 직접 박는다(throw 전·onExceeded). ASP 는 기존 코드 무변경 위해 여기서.
+      if (err instanceof MegaAspDecryptError) {
+        MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.security.reason': `asp.${err.rule}` })
+      }
+    })
+    // onResponse 는 성공·에러 응답 모두에서 마지막에 호출 — 상태코드 기록 후 span 종료(단일 종료 지점).
+    this.fastify.addHook('onResponse', async (req, reply) => {
+      const handle = (/** @type {Record<symbol, any>} */ (/** @type {unknown} */ (reply)))[HTTP_SPAN_SYMBOL]
+      handle?.finish(reply.statusCode)
+      // HTTP 요청 메트릭 (ADR-131) — 옵트인 OFF 면 isEnabled() false 라 즉시 return(0 비용).
+      // route 는 **매칭된 패턴**(routeOptions.url)만 — 매칭 안 되면(404) recordHttp 가 __unmatched__ 로 접어
+      // 카디널리티 폭증 차단. reply.elapsedTime = onRequest~onResponse ms(Fastify 제공).
+      if (MegaMetrics.isEnabled()) {
+        MegaMetrics.recordHttp({
+          method: req.method,
+          route: /** @type {any} */ (req).routeOptions?.url,
+          statusCode: reply.statusCode,
+          durationMs: reply.elapsedTime,
+          app: this.name,
+        })
+      }
+    })
+
+    // 2) 자동 envelope (ADR-018, ADR-076).
+    //    onRoute 훅으로 각 라우트의 preSerialization 체인 "맨 끝" 에 wrapEnvelope 를 붙인다.
+    //    이유: Fastify 는 글로벌 preSerialization 을 라우트 레벨보다 "먼저" 실행한다
+    //    (encapsulation: outer → inner). 그래서 글로벌 addHook 으로 wrap 을 등록하면
+    //    라우트별 transform(ADR-091) 보다 wrap 이 먼저 돌아 순서가 뒤집힌다.
+    //    onRoute 로 wrap 을 라우트 preSerialization 의 마지막 함수로 append 하면
+    //    transform → wrap 순서가 보장된다 (ADR-076/091 정합). 검증: test/integration.
+    //    주의: onRoute 는 등록 "이후" 라우트만 잡으므로 /health 보다 먼저 등록해야 한다.
+    this.fastify.addHook('onRoute', (routeOptions) => {
+      // OpenAPI/swagger-ui 라우트(`${openapi.path}` 하위)는 envelope 제외 — swagger-ui 는 raw OpenAPI JSON
+      // 을 기대하므로 `{ok,data,meta}` 로 감싸면 UI 가 깨진다(ADR-140). 옵트인 OFF(_openapiPath=null)면 무영향.
+      const url = /** @type {string} */ (routeOptions.url)
+      if (this._openapiPath && (url === this._openapiPath || url.startsWith(`${this._openapiPath}/`))) return
+      const existing = routeOptions.preSerialization
+      const chain = existing ? (Array.isArray(existing) ? [...existing] : [existing]) : []
+      // async 어댑터로 감싼다: Fastify 는 done 콜백 없는 preSerialization 훅을
+      // "Promise 반환(async)" 으로만 인식한다. wrapEnvelope 는 순수 동기 함수(단위 테스트·
+      // 재사용 용이)라 그대로 넣으면 Fastify 가 콜백 스타일로 오인해 done 을 영원히 기다린다.
+      chain.push(async (req, reply, payload) => wrapEnvelope(req, reply, payload))
+      routeOptions.preSerialization = chain
+    })
+
+    // 3) 글로벌 에러 핸들러 (AJV → MegaValidationError, MegaError → envelope, ADR-090).
+    this.fastify.setErrorHandler(
+      buildErrorHandler({ exposeInternalDetails: opts.exposeInternalDetails === true }),
+    )
+
+    // 3b) 보안 플러그인 자동 등록 (ADR-127) — helmet/cors/rate-limit/csrf + ASP HTTP.
+    //     **반드시 /health 라우트 등록 "이전"** — @fastify/rate-limit 의 onRoute 가 health 의
+    //     config.rateLimit:false 면제를 보려면 플러그인이 먼저 등록돼야 한다(security.js 주석).
+    //     mega-app.js:183 TODO 해소.
+    // 세션 config 정규화 (ADR-129). session:false/undefined → 비활성.
+    // store 어댑터는 생성자에서 만들되 connect 는 onReady hook 에서(테스트 inject·listen·boot 공통 경로).
+    /** @type {import('../adapters/mega-session-adapter.js').MegaSessionAdapter | null} */
+    this._sessionStore = null
+    const sessionCfg = opts.session && opts.session !== /** @type {any} */ (false) ? opts.session : null
+
+    // CSRF 세션 모드(ADR-051/129) — session.csrf:true 면 @fastify/csrf-protection 을 sessionPlugin 모드로
+    // 등록해 시크릿을 세션(_csrf 키)에 바인딩한다. 기본은 ADR-051 쿠키 double-submit 유지(csrf 옵션 무변경).
+    let effectiveCsrf = opts.csrf
+    if (sessionCfg && sessionCfg.csrf === true && opts.csrf !== false) {
+      effectiveCsrf = { ...(typeof opts.csrf === 'object' ? opts.csrf : {}), sessionPlugin: '@fastify/session' }
+    }
+
+    // 3b) 보안 플러그인 자동 등록 (ADR-127).
+    registerSecurityPlugins(this.fastify, {
+      appName: this.name,
+      hosts: this.hosts,
+      helmet: opts.helmet,
+      cors: opts.cors,
+      rateLimit: opts.rateLimit,
+      csrf: effectiveCsrf,
+      asp: opts.asp,
+      resolveRateStore: this._buildRateStoreResolver(opts.caches),
+      logger: this.fastify.log,
+    })
+
+    // 3b-2) 파일 업로드 자동 등록 (per ADR-133) — @fastify/multipart + MIME 화이트리스트 + 경로 탐색 차단 +
+    //       트레이싱/메트릭. opts.upload 없으면 미등록(옵트인). CSRF 는 security.js 가 multipart/form-data 를
+    //       폼으로 분류해 이미 토큰 검증(per ADR-051) — 별도 배선 불필요.
+    registerMultipart(this.fastify, {
+      upload: opts.upload,
+      appName: this.name,
+      logger: this.fastify.log,
+    })
+
+    // 3c) 세션 미들웨어 (ADR-129/046) — store + 쿠키 HMAC + ctx.session.
+    //     onRequest hook 이라 csrf preHandler 보다 먼저 실행돼 세션 모드 CSRF 가 req.session 을 본다.
+    if (sessionCfg) {
+      const secret = sessionCfg.secret ?? opts.sessionSecret
+      const store = createSessionStore(sessionCfg.store, { ttlMs: sessionCfg.ttlMs })
+      this._sessionStore = store
+      registerSession(this.fastify, {
+        store,
+        secret,
+        ttlMs: sessionCfg.ttlMs,
+        rolling: sessionCfg.rolling,
+        cookie: sessionCfg.cookie,
+        driver: sessionCfg.store?.driver,
+        logger: this.fastify.log,
+      })
+      // store connect 는 onReady(테스트 inject·single listen·scaffold boot 모두 fastify.ready 경유).
+      this.fastify.addHook('onReady', async () => {
+        await store.connect()
+      })
+      // graceful shutdown 시 store disconnect (LIFO — fastify close 보다 나중 등록 = 먼저 정리되지 않도록).
+      MegaShutdown.register(`mega-session:${this.name}`, async () => {
+        await store.disconnect().catch((err) => this.fastify.log.warn({ err }, 'session store disconnect failed'))
+      })
+      this.fastify.log.debug?.({ app: this.name, driver: sessionCfg.store?.driver, csrf: sessionCfg.csrf === true }, 'session.registered')
+    }
+
+    // 3d) i18n 자동 등록 (ADR-037/038/039/135) — i18next + 쿠키 locale + scope 분리.
+    //     opts.i18n 없으면 미등록(옵트인 — ctx.t 는 ctx-builder passthrough 폴백). 보안 플러그인 뒤에 등록하나
+    //     onRequest hook + request 부착이라 라우트/hook 순서와 무관. locale 쿠키는 보안 토큰 아님(CSRF/ASP 무관).
+    registerI18n(this.fastify, {
+      i18n: opts.i18n,
+      appName: this.name,
+      logger: this.fastify.log,
+    })
+
+    // 3e) 템플릿 자동 등록 (ADR-011/136) — EJS + ejs-mate 서버사이드 렌더.
+    //     opts.views(.dir) 없으면 미등록(옵트인 — reply.render/ctx.render 미정의 → 호출 시 fail-fast).
+    //     i18n 뒤에 등록해 reply.render 가 요청별 req.t/req.lang 을 data 에 자동 병합(다국어 뷰).
+    registerTemplate(this.fastify, {
+      views: opts.views,
+      appName: this.name,
+      logger: this.fastify.log,
+    })
+
+    // 3e-2) HTML 폼 바디 파싱 자동 등록 (ADR-151) — @fastify/formbody. 서버사이드 뷰(opts.views.dir)를 켠
+    //       앱만 등록(MPA 폼 제출 = urlencoded). JSON 전용 앱은 미등록(기존 JSON/text 파싱 유지).
+    registerFormbody(this.fastify, {
+      views: opts.views,
+      appName: this.name,
+      logger: this.fastify.log,
+    })
+
+    // 3f) 정적 자산 자동 등록 (ADR-071/139) — @fastify/static 옵트인.
+    //     opts.staticAssets.enabled:true + dir 있을 때만 등록(디폴트 OFF). 라우트 등록이라 보안 onRoute hook
+    //     뒤·/health 앞에 둔다. enabled:true 인데 dir 없으면 프로덕션 throw / dev warn+skip(static-assets.js).
+    registerStaticAssets(this.fastify, {
+      staticAssets: opts.staticAssets,
+      appName: this.name,
+      logger: this.fastify.log,
+    })
+
+    // 3g) OpenAPI/Swagger 자동 등록 (ADR-070/140) — @fastify/swagger + swagger-ui 옵트인.
+    //     opts.openapi.enabled:true 일 때만 등록(디폴트 OFF). swagger 는 라우트 schema 를 onRoute 로 수집하므로
+    //     사용자 라우트 등록(부팅 시 loadRoutes/single 직접)보다 먼저 등록돼야 한다 — 생성자 시점이 그 지점.
+    //     docs auth 미들웨어엔 요청당 ctx 를 만들어 넘긴다(getHttpCtx, globalMiddleware 패턴 정합, ADR-134).
+    const openapiSummary = registerOpenapi(this.fastify, {
+      openapi: opts.openapi,
+      appName: this.name,
+      buildCtx: (/** @type {any} */ req, /** @type {any} */ reply) => getHttpCtx({ app: this, req, reply }),
+      logger: this.fastify.log,
+    })
+    // envelope onRoute 가 docs 경로를 제외하도록 path 저장(미옵트인이면 null 유지).
+    this._openapiPath = openapiSummary.path
+
+    // MegaHealth 통합 — /health (liveness) + /health/ready (readiness).
+    // onRoute 훅 등록 이후라 자동 envelope 적용됨. config.skip{Asp,Csrf,RateLimit} 3종이 각 보안 hook 의
+    // 면제 신호다(ADR-072 면제 실효, ADR-127): ASP onRequest·CSRF preHandler·rate-limit allowList 가 검사.
+    const HEALTH_EXEMPT = { skipAsp: true, skipCsrf: true, skipRateLimit: true }
+
+    // /health — liveness (항상 200)
+    this.fastify.get('/health', { config: HEALTH_EXEMPT }, async () => ({
+      status: 'ok',
+      app: this.name,
+      uptime_ms: Math.floor(process.uptime() * 1000),
+      ts: Date.now(),
+    }))
+
+    // /health/ready — readiness (checkAll 후 200 or 503)
+    this.fastify.get('/health/ready', { config: HEALTH_EXEMPT }, async (req, reply) => {
+      const snapshot = await MegaHealth.checkAll()
+      if (!snapshot.ok) reply.code(503)
+      return {
+        app: this.name,
+        ...snapshot,
+        uptime_ms: Math.floor(process.uptime() * 1000),
+        ts: Date.now(),
+      }
+    })
+
+    // /metrics — Prometheus 옵트인 (ADR-072/131). exposeMetrics:true 일 때만 등록 →
+    // 디폴트(미등록)는 Fastify 가 404(roadmap 검증 기준). /health 와 동일 보안 면제(HEALTH_EXEMPT).
+    // 접근 제어 = IP allowList(ADR-131) — 빈 list 면 메인 포트 전체 노출(운영자 결정).
+    const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
+    if (healthCfg.exposeMetrics === true) {
+      const metricsPath = typeof healthCfg.metricsPath === 'string' && healthCfg.metricsPath.length > 0 ? healthCfg.metricsPath : '/metrics'
+      // metricsPath 충돌 검증(ADR-072/04-data-models) — health 경로와 겹치면 부팅 throw(fail-fast).
+      const livePath = healthCfg.paths?.live ?? '/health'
+      const readyPath = healthCfg.paths?.ready ?? '/health/ready'
+      if (metricsPath === livePath || metricsPath === readyPath) {
+        throw new MegaConfigError(
+          'health.metrics_path_conflict',
+          `health.metricsPath='${metricsPath}' conflicts with a health path (live='${livePath}', ready='${readyPath}'). Choose a distinct path.`,
+          { details: { metricsPath, livePath, readyPath } },
+        )
+      }
+      const allowList = Array.isArray(healthCfg.metricsAllowList) ? healthCfg.metricsAllowList : []
+      this.fastify.get(metricsPath, { config: HEALTH_EXEMPT }, async (req, reply) => {
+        if (!MegaMetrics.isIpAllowed(req.ip, allowList)) {
+          this.fastify.log.debug?.({ ip: req.ip, route: metricsPath }, 'metrics.access denied (allowList)')
+          // 문자열 payload → Fastify 가 preSerialization(envelope)을 건너뜀(raw 전송). 거부도 raw 텍스트.
+          return reply.code(403).type('text/plain').send('forbidden\n')
+        }
+        // Prometheus 텍스트(문자열) 반환 → Fastify 가 string payload 라 preSerialization(wrapEnvelope)을
+        // 건너뛰어 raw 로 전송(envelope JSON 으로 안 감싸짐). onResponse 는 정상 발화 → 트레이싱 span 종료.
+        // 클러스터(ADR-154)면 collectCluster 가 마스터를 통해 전 워커 합산을 돌려준다(ADR-163) — 단일
+        // 프로세스면 로컬 collect() 와 동일. 워커별로 흩어진 카운터가 한 응답에 합산돼 스크레이프가 일관된다.
+        const body = await collectCluster()
+        reply.type(MegaMetrics.PROM_CONTENT_TYPE)
+        return body
+      })
+      this.fastify.log.debug?.({ app: this.name, metricsPath, allowList: allowList.length }, 'metrics.endpoint registered')
+    }
+
+    // 플러그인 hook 소비 (ADR-079 §14 hook표, ADR-123). orchestrator(bootApp)가
+    // MegaPluginHost 수집물(fastifyPlugins / globalMiddlewares)을 모든 앱에 주입한다. health
+    // 라우트보다 뒤에 걸지만 Fastify 글로벌 hook/register 는 scope 내 전 라우트에 적용된다.
+    if (Array.isArray(opts.plugins)) {
+      for (const entry of opts.plugins) {
+        if (!entry || typeof entry.plugin !== 'function') {
+          throw new TypeError(`MegaApp('${this.name}'): plugins[] entry must be { plugin: function, opts? }.`)
+        }
+        this.fastify.register(/** @type {any} */ (entry.plugin), entry.opts)
+      }
+    }
+    if (Array.isArray(opts.globalMiddlewares)) {
+      const self = this
+      for (const mw of opts.globalMiddlewares) {
+        if (typeof mw !== 'function') {
+          throw new TypeError(`MegaApp('${this.name}'): globalMiddlewares[] entry must be a function.`)
+        }
+        // 래퍼 arity 2(`(req, reply)`)라 Fastify 가 async preHandler 로 인식한다(arity 3 면 done 콜백 모드로
+        // 오인). 래퍼 안에서 ctx 를 만들어 미들웨어를 `(req, reply, ctx)` 로 호출한다(ADR-134). getHttpCtx 가
+        // 요청당 캐싱이라 같은 요청의 라우트 핸들러가 동일 ctx 를 이어받는다.
+        this.fastify.addHook('preHandler', async (req, reply) => {
+          const ctx = getHttpCtx({ app: self, req, reply })
+          return /** @type {any} */ (mw)(req, reply, ctx)
+        })
+      }
+    }
+
+    // MegaShutdown 에 자기 Fastify close 등록 (마지막에 등록 — LIFO 로 가장 먼저 실행)
+    MegaShutdown.register(`mega-app:${this.name}`, async () => {
+      await this.fastify.close()
+    })
+  }
+
+  /**
+   * rate-limit Redis 백엔드 해석기를 만든다 (ADR-048). 앱이 `caches.rate` 별명을 선언했고 그 어댑터가
+   * Redis(`MegaRedisAdapter`)면 ioredis raw handle 을 반환하는 함수를, 아니면 `undefined` 를 돌려준다
+   * (= in-memory 폴백, 단일 인스턴스 dev). 해석은 보안 등록 시점(생성자)에 1회 호출되며, 어댑터는
+   * 그 전에 `MegaAdapterManager` 가 connect 해 둔 상태여야 한다(부팅 orchestrator 가 보장).
+   *
+   * Redis 가 아닌 캐시를 `rate` 로 매핑한 misconfiguration 은 silent 무시하지 않고 warn 후 in-memory
+   * 폴백한다(ADR-048 — rate-limit 은 ioredis 전용, 폴백은 비치명적·문서화된 디폴트).
+   *
+   * @param {Record<string, string>} [caches] - 앱 캐시 별명 맵 `{ alias: globalKey }`.
+   * @returns {(() => import('ioredis').Redis | null) | undefined}
+   * @private
+   */
+  _buildRateStoreResolver(caches) {
+    if (!caches || typeof caches.rate !== 'string') return undefined
+    return () => {
+      const adapter = this._adapterAccessors.cache('rate') // 미선언/미등록이면 throw(fail-fast).
+      if (adapter?.constructor?.name !== 'MegaRedisAdapter') {
+        this.fastify.log.warn(
+          { app: this.name, adapter: adapter?.constructor?.name },
+          'security.rate_limit: caches.rate is not a Redis adapter — falling back to in-memory store (ADR-048).',
+        )
+        return null
+      }
+      return /** @type {import('ioredis').Redis} */ (adapter.native)
+    }
+  }
+
+  /**
+   * Single 모드 WS 채널 등록. `router.ws` 와 동일 검증 위임.
+   *
+   * 단일 파일 모드에서 `routes/` 스캔 없이 직접 채널을 등록한다 (02-architecture §3). 등록은
+   * `fastify._megaWsRoutes` 에 보관되며 {@link MegaApp#listen} 시 upgrade 핸들오프가 배선된다.
+   *
+   * @param {string} path - WS 경로 (= namespace).
+   * @param {Function} ChannelClass - MegaWebSocketController 상속.
+   * @param {{ before?: Function[], schemas?: Object }} [opts]
+   * @returns {this} 체이닝용.
+   * @throws {import('./router.js').MegaRouteError} 형식/상속 위반.
+   */
+  ws(path, ChannelClass, opts = {}) {
+    if (!this._router) this._router = new Router({ fastify: this.fastify, appName: this.name, app: this })
+    this._router.ws(path, ChannelClass, opts)
+    return this
+  }
+
+  /**
+   * 등록된 WS 라우트 목록 (router.ws + app.ws 통합). 비어 있으면 빈 배열.
+   * @returns {Array<{ path: string, ns: string, ChannelClass: Function, opts: { before?: Function[], schemas?: Object }, schemaValidators?: Record<string, import('ajv').ValidateFunction> | null }>}
+   */
+  get wsRoutes() {
+    const f = /** @type {any} */ (this.fastify)
+    return Array.isArray(f._megaWsRoutes) ? f._megaWsRoutes : []
+  }
+
+  /** 현재 연결된 hub link (미연결 시 null). */
+  get hubLink() {
+    return this._hubLink
+  }
+
+  /**
+   * 이 앱의 `ctx.db/cache/bus` 접근자 3종 (ADR-102). 요청 ctx 빌더(HTTP·WS)가 spread 해서 노출한다.
+   * 별명→globalKey→전역 공유 어댑터로 해석하며, 미선언 별명·미등록 키는 호출 시 throw.
+   * @returns {import('./ctx-builder.js').AdapterAccessors}
+   */
+  get adapterAccessors() {
+    return this._adapterAccessors
+  }
+
+  /**
+   * 이 앱의 서비스 레지스트리(name → 클래스, ADR-148). 요청 ctx 빌더가 `ctx.services.<name>` lazy DI 의
+   * 클래스 lookup 출처로 읽는다. 부팅 orchestrator 가 `setServiceRegistry` 로 채운다.
+   * @returns {Map<string, Function>}
+   */
+  get serviceRegistry() {
+    return this._serviceRegistry
+  }
+
+  /**
+   * 서비스 레지스트리 주입 (부팅 시 1회, ADR-148). services-loader 가 만든 name→Class 맵으로 교체한다.
+   * @param {Map<string, Function>} registry - name → 서비스 클래스.
+   * @returns {void}
+   * @throws {TypeError} Map 이 아니면.
+   */
+  setServiceRegistry(registry) {
+    if (!(registry instanceof Map)) {
+      throw new TypeError(`MegaApp('${this.name}').setServiceRegistry: registry must be a Map.`)
+    }
+    this._serviceRegistry = registry
+  }
+
+  /**
+   * `ctx.bruteForce` 단축이 반환하는 MegaBruteForce 인스턴스(03-api-spec §10/§786, ADR-049/130).
+   * **lazy** — 처음 접근할 때만 만들고 앱당 재사용한다. 백엔드는 `caches.rate` 별명(ADR-049 디폴트)을
+   * 해석한 redis 어댑터. rate 캐시를 선언 안 한 앱이 이 getter 를 건드리면 cache 접근자가 fail-fast
+   * (`adapter.not_registered`) — brute-force 를 안 쓰는 앱은 이 getter 를 호출하지 않으므로 무해하다.
+   * 세분 정책(도메인별 maxAttempts 등)은 `new MegaBruteForce({ cache: ctx.cache('alias'), key, ... })`
+   * 로 직접 구성한다(별도 config 키는 향후 Step, ADR-130).
+   * @returns {MegaBruteForce}
+   */
+  get bruteForce() {
+    if (this._bruteForce === null) {
+      const cache = /** @type {any} */ (this._adapterAccessors.cache('rate')) // 미선언/미등록이면 throw.
+      this._bruteForce = new MegaBruteForce({ cache, key: 'default' })
+    }
+    return this._bruteForce
+  }
+
+  /**
+   * 이 bridge 를 hub 에 연결한다 (ADR-033/059). REGISTER 핸드셰이크 완료 후
+   * 선언 채널을 구독(bridge-subscriber JOIN)하고, hub 의 BROADCAST/DIRECT 를 로컬 소켓에 전달한다.
+   *
+   * single 모드는 embedded 종단이라 hub 가 필수는 아니지만(02-architecture §3), 멀티 인스턴스
+   * fan-out 이 필요하면 single 에서도 사용 가능하다. scaffold(멀티앱/클러스터)에서 권장.
+   *
+   * @param {Object} config - MegaBridgeHubConfig (§2.1) + 구독 채널.
+   * @param {string} config.url - hub URL.
+   * @param {string} config.token - Bearer 토큰.
+   * @param {string} config.bridgeId - 운영 식별자.
+   * @param {string} [config.instanceId]
+   * @param {string[]} [config.capabilities]
+   * @param {string[]} [config.channels] - 자동 구독할 채널 목록.
+   * @param {import('../lib/mega-retry.js').MegaRetryOptions} [config.retry] - 지정 시 재연결 활성(ADR-098).
+   *   hub 재시작·drain(4503)·네트워크 단절 시 지수 백오프로 재연결하고, 성공하면 presence(채널·세션
+   *   JOIN)를 자동 재동기화한다(hub 는 절단 시점 presence 를 잃으므로).
+   * @param {import('./ws-compression.js').WsCompressionConfig} [config.compression] - Bridge↔Hub
+   *   link 압축(ADR-078 / MegaWsHubCompressionConfig). Global `wsHub.compression`
+   *   블록을 그대로 전달한다 — hub 서버와 같은 스키마. 디폴트 OFF. 잘못된 threshold/windowBits 면
+   *   즉시 throw(부팅 fail-fast).
+   * @returns {Promise<MegaHubLink>} 등록 완료된 link.
+   */
+  async connectHub(config = /** @type {any} */ ({})) {
+    const link = new MegaHubLink({
+      url: config.url,
+      token: config.token,
+      bridgeId: config.bridgeId,
+      instanceId: config.instanceId,
+      capabilities: config.capabilities,
+      retry: config.retry,
+      compression: config.compression,
+      logger: this.fastify.log,
+    })
+    this._hubLink = link
+    this._hubBridgeId = config.bridgeId
+    this._hubChannels = Array.isArray(config.channels) ? [...config.channels] : []
+    // hub → bridge 푸시를 로컬 소켓에 전달.
+    link.on(HUB_MESSAGE_TYPES.BROADCAST, (msg) => this._deliverBroadcast(/** @type {any} */ (msg).payload))
+    link.on(HUB_MESSAGE_TYPES.DIRECT, (msg) => this._deliverDirect(/** @type {any} */ (msg).payload))
+    // 재연결 성공 시 presence 재동기화(ADR-098) — hub 는 절단 시점 presence 를 잃으므로 다시 JOIN.
+    link.on(MegaHubLink.EVENTS.RECONNECTED, () => this._resyncPresence())
+    await link.connect()
+
+    // 채널 구독 — bridge-subscriber 세션 JOIN(zero-config 브로드캐스트 수신용) + 이미 붙어 있는 실
+    // 사용자 세션 재JOIN(예: 첫 connect 전에 클라가 연결됐을 수 있음).
+    this._resyncPresence()
+
+    // shutdown hook 누수 방지(L1) — 재연결 등으로 connectHub 가 다시 불려도 hook 은 항상 1개.
+    const hookName = `mega-hublink:${this.name}`
+    MegaShutdown.unregister(hookName)
+    MegaShutdown.register(hookName, async () => link.close())
+    return link
+  }
+
+  /**
+   * hub presence 재동기화 — bridge-subscriber 채널 JOIN + 활성 사용자 세션 JOIN 을 모두 다시 보낸다.
+   * 최초 등록 직후와 재연결(RECONNECTED) 직후에 호출된다. hub 의 JOIN 처리는 멱등(같은 sessionId 덮어씀).
+   * @returns {void}
+   * @private
+   */
+  _resyncPresence() {
+    const link = this._hubLink
+    if (!link?.isRegistered) return
+    const bridgeId = this._hubBridgeId ?? this.name
+    // 1) bridge-subscriber JOIN — bridge 가 채널 멤버가 되어 zero-config 브로드캐스트를 받게 한다.
+    for (const ch of this._hubChannels) {
+      link.join({
+        userId: `bridge:${bridgeId}`,
+        sessionId: `bridge:${bridgeId}#${ch}`,
+        channels: [ch],
+      })
+    }
+    // 2) 실 사용자 세션 JOIN — joinSession 으로 매핑된 활성 세션을 다시 등록(DIRECT 타겟 복구).
+    //    채널 + metadata 까지 재동기화한다(M-1) — hub 는 절단 시점 presence 를 통째로 잃으므로,
+    //    metadata 를 빠뜨리면 재연결 후 hub presence 의 메타가 silent 사라진다.
+    for (const [sessionId, conn] of this._sessionConns) {
+      if (!conn.isOpen) continue
+      link.join({
+        userId: /** @type {string} */ (conn.userId),
+        sessionId,
+        channels: conn.channels ? [...conn.channels] : [],
+        ...(conn.metadata ? { metadata: conn.metadata } : {}),
+      })
+    }
+  }
+
+  /**
+   * 실 사용자 세션을 hub presence 에 등록하고 로컬 매핑을 만든다 (OQ-010/ADR-098).
+   *
+   * 표준 패턴: WS upgrade 의 `before` 미들웨어가 인증 후 신원을 `ctx.auth` 로 싣고(ADR-091 DI),
+   * 채널의 `onConnect(sock, ctx)` 에서 `ctx.app.joinSession(sock, { userId: ctx.auth.userId, ... })`
+   * 를 호출한다. 이 매핑이 있어야 DIRECT 가 **해당 userId 세션에만** 전달된다(cross-user flood 방지,
+   * H-latent guard). 매핑 없는 연결은 DIRECT 대상에서 제외된다.
+   *
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn - onConnect 가 받은 소켓 래퍼.
+   * @param {Object} entry
+   * @param {string} entry.userId - 인증된 사용자 식별자(비어 있으면 throw).
+   * @param {string} entry.sessionId - 세션 식별자(비어 있으면 throw). 전역 유일 권장.
+   * @param {string[]} [entry.channels] - 가입 채널 목록.
+   * @param {Object} [entry.metadata] - presence 메타데이터(명시 필드만, ADR-059).
+   * @returns {this}
+   * @throws {Error} conn/userId/sessionId 누락 시 — 잘못된 매핑을 silent 통과시키지 않는다.
+   */
+  joinSession(conn, { userId, sessionId, channels = [], metadata } = /** @type {any} */ ({})) {
+    if (!conn || typeof conn.send !== 'function') {
+      throw new Error('MegaApp.joinSession: conn (MegaWsConnection) is required.')
+    }
+    if (typeof userId !== 'string' || userId.length === 0) {
+      throw new Error('MegaApp.joinSession: userId (non-empty string) is required.')
+    }
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw new Error('MegaApp.joinSession: sessionId (non-empty string) is required.')
+    }
+    const chans = Array.isArray(channels) ? [...channels] : []
+
+    // L-4: 같은 sessionId 가 다른 conn 으로 다시 join 되면(전역 유일 계약 위반) 옛 conn 을 인덱스에서
+    // 떼어 dangling 을 막는다 — 단 소켓 자체는 닫지 않는다(클라가 정리). 옛 conn 의 신원도 비워,
+    // 이후 옛 conn 의 close(_untrackWsConn)가 새 conn 이 차지한 sessionId 로 LEAVE 를 잘못 보내지
+    // 않게 한다(그대로 두면 새 세션의 hub presence 가 silent 제거됨).
+    const prior = this._sessionConns.get(sessionId)
+    if (prior && prior !== conn) {
+      this.fastify.log?.warn?.(
+        { app: this.name, sessionId, priorUserId: prior.userId, userId },
+        'ws.joinSession duplicate sessionId — prior conn left dangling (detached, not closed)',
+      )
+      if (prior.userId !== undefined) {
+        const pset = this._userConns.get(prior.userId)
+        if (pset) {
+          pset.delete(prior)
+          if (pset.size === 0) this._userConns.delete(prior.userId)
+        }
+      }
+      if (prior.ns !== undefined) {
+        const nsset = this._wsConns.get(prior.ns)
+        if (nsset) {
+          nsset.delete(prior)
+          if (nsset.size === 0) this._wsConns.delete(prior.ns)
+        }
+      }
+      prior.userId = undefined
+      prior.sessionId = undefined
+      prior.channels = null
+    }
+
+    // 연결에 신원 부착(매핑 키). _untrackWsConn 이 close 시 이 값으로 인덱스를 정리한다.
+    conn.userId = userId
+    conn.sessionId = sessionId
+    conn.channels = new Set(chans)
+    conn.metadata = metadata // M-1: 재연결 재동기화(_resyncPresence)가 보존할 수 있게 저장.
+
+    let uset = this._userConns.get(userId)
+    if (!uset) {
+      uset = new Set()
+      this._userConns.set(userId, uset)
+    }
+    uset.add(conn)
+    this._sessionConns.set(sessionId, conn)
+
+    this.fastify.log?.debug?.({ app: this.name, userId, sessionId, channels: chans }, 'ws.joinSession')
+    // hub presence 등록 — 등록 상태일 때만(미연결/재연결 중이면 _resyncPresence 가 나중에 복구).
+    if (this._hubLink?.isRegistered) {
+      this._hubLink.join({ userId, sessionId, channels: chans, ...(metadata ? { metadata } : {}) })
+    }
+    return this
+  }
+
+  /**
+   * 채널 broadcast — 로컬 ns 소켓에 즉시 전달 + (hub 연결 시) 클러스터 fan-out.
+   *
+   * @param {{ ns: string, channel: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} args
+   * @returns {void}
+   * @throws {Error} message.type(string) 누락 시 — 호출부 입력 오류를 silent drop 하지 않고 즉시 알린다(L6).
+   */
+  broadcast({ ns, channel, message, exceptSessionIds }) {
+    // 입력 검증을 한곳에서(L6) — 로컬은 받고 hub 는 message.type 없이 전송하던 비대칭을 제거.
+    if (!message || typeof message.type !== 'string') {
+      throw new Error('MegaApp.broadcast: message.type (string) is required')
+    }
+    this._deliverBroadcast({ ns, channel, message, exceptSessionIds })
+    if (this._hubLink?.isRegistered) {
+      // L-7: 빈 배열도 truthy 라 `exceptSessionIds: []` 가 wire 로 새던 비대칭 제거 — 비어 있으면 생략.
+      const hasExcept = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0
+      try {
+        this._hubLink.broadcast({ ns, channel, message, ...(hasExcept ? { exceptSessionIds } : {}) })
+      } catch (err) {
+        // 로컬 전달은 이미 성공. 클러스터 fan-out 은 best-effort(at-most-once, ADR-033)이며 소켓이
+        // 닫히는 중이면 비치명적 — 재연결 시 presence 가 재동기화된다. warn 후 호출자 보호.
+        const log = /** @type {any} */ (this.fastify.log)
+        log?.warn?.({ err, ns, channel, app: this.name }, 'app.broadcast hub fan-out failed (local delivered)')
+      }
+    }
+  }
+
+  /**
+   * 특정 사용자에게 직접 전송 (directToUser, ADR-035) — 로컬에서 그 userId 로 매핑된 연결에만 전달
+   * (H-latent guard) + (hub 연결 시) 클러스터 fan-out(다른 bridge 의 같은 userId 세션까지).
+   *
+   * {@link MegaApp#joinSession} 으로 매핑된 연결만 대상이다 — 매핑 없는 userId 면 로컬 no-op.
+   *
+   * @param {string} userId - 대상 사용자.
+   * @param {{ type: string, payload?: Object }} message - 내부 envelope `{ type, payload }`.
+   * @returns {void}
+   * @throws {Error} userId/message.type 누락 시(broadcast 와 동일한 입력 보호, L6).
+   */
+  directToUser(userId, message) {
+    if (typeof userId !== 'string' || userId.length === 0) {
+      throw new Error('MegaApp.directToUser: userId (non-empty string) is required')
+    }
+    if (!message || typeof message.type !== 'string') {
+      throw new Error('MegaApp.directToUser: message.type (string) is required')
+    }
+    this._deliverDirect({ userId, message })
+    if (this._hubLink?.isRegistered) {
+      try {
+        this._hubLink.direct({ userId, message })
+      } catch (err) {
+        // 로컬 전달은 이미 성공. 클러스터 fan-out 은 best-effort(at-most-once, ADR-033). warn 후 보호.
+        const log = /** @type {any} */ (this.fastify.log)
+        log?.warn?.({ err, userId, app: this.name }, 'app.directToUser hub fan-out failed (local delivered)')
+      }
+    }
+  }
+
+  /**
+   * 세션 presence 메타데이터 갱신 (METADATA, ADR-059) — 로컬 conn 에 저장 + (hub 연결 시) 전파.
+   *
+   * 로컬 conn 의 `metadata` 를 갱신해 두면 이후 재연결 시 {@link MegaApp#_resyncPresence} 가 최신
+   * 메타까지 복구한다(M-1). 매핑 없는 sessionId 면 no-op(로컬 저장 없이 hub 전파만은 하지 않음 —
+   * 재연결 보존 대상이 없으므로). broadcast/directToUser 와 같은 best-effort fan-out.
+   *
+   * @param {string} sessionId - 대상 세션(joinSession 으로 매핑된 것).
+   * @param {Object} metadata - 갱신할 메타데이터(명시 필드만).
+   * @returns {this}
+   * @throws {Error} sessionId/metadata 누락 시(입력 보호, L6 와 동일 원칙).
+   */
+  updateMetadata(sessionId, metadata) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw new Error('MegaApp.updateMetadata: sessionId (non-empty string) is required')
+    }
+    if (!metadata || typeof metadata !== 'object') {
+      throw new Error('MegaApp.updateMetadata: metadata (object) is required')
+    }
+    const conn = this._sessionConns.get(sessionId)
+    if (!conn) {
+      // 매핑 없는 세션 — 재연결로 보존할 로컬 대상이 없으므로 no-op(다른 bridge 세션은 그쪽이 관리).
+      this.fastify.log?.debug?.({ app: this.name, sessionId }, 'ws.updateMetadata — no local session (no-op)')
+      return this
+    }
+    conn.metadata = metadata // 재연결 재동기화가 최신 메타를 복구하도록 저장(M-1).
+    if (this._hubLink?.isRegistered) {
+      try {
+        this._hubLink.updateMetadata({ sessionId, metadata })
+      } catch (err) {
+        // hub 전파 실패는 비치명적 — 로컬 저장은 됐고 재연결 시 _resyncPresence 가 복구.
+        const log = /** @type {any} */ (this.fastify.log)
+        log?.warn?.({ err, sessionId, app: this.name }, 'app.updateMetadata hub propagate failed (local stored)')
+      }
+    }
+    return this
+  }
+
+  /**
+   * broadcast payload 를 로컬 ns 소켓에 전달한다. message 는 `{ type, payload }` 내부 envelope.
+   *
+   * `exceptSessionIds` 에 든 sessionId 로 매핑된 연결은 제외한다(ADR-098). 세션 매핑이 없는
+   * 연결(zero-config·미JOIN)은 sessionId 가 없어 제외 대상에 걸리지 않으므로 그대로 받는다.
+   *
+   * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+   * @returns {void}
+   * @private
+   */
+  _deliverBroadcast({ ns, message, exceptSessionIds }) {
+    const set = this._wsConns.get(ns)
+    if (!set || !message || typeof message.type !== 'string') return
+    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+    for (const conn of set) {
+      if (!conn.isOpen) continue
+      if (except && conn.sessionId !== undefined && except.has(conn.sessionId)) continue
+      conn.send({ type: message.type, ns, payload: message.payload })
+    }
+  }
+
+  /**
+   * direct payload 를 **해당 userId 로 매핑된 로컬 연결에만** 전달한다 (H-latent guard).
+   *
+   * 초기에는 매핑이 없어 모든 연결에 flood 됐다(cross-user 누출). {@link MegaApp#joinSession}
+   * 으로 만든 `userId → 연결` 매핑을 통해 대상 사용자에게만 보낸다. 매핑이 없는 userId 면 no-op
+   * (다른 사용자에게 새지 않음).
+   *
+   * @param {{ userId: string, message: { type: string, payload?: Object } }} payload
+   * @returns {void}
+   * @private
+   */
+  _deliverDirect({ userId, message }) {
+    if (!message || typeof message.type !== 'string') return
+    if (typeof userId !== 'string' || userId.length === 0) return
+    const set = this._userConns.get(userId)
+    if (!set) return
+    for (const conn of set) {
+      if (conn.isOpen) conn.send({ type: message.type, payload: message.payload })
+    }
+  }
+
+  /**
+   * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal). hub broadcast 의 local 전달 대상.
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+   * @returns {void}
+   */
+  _trackWsConn(conn) {
+    if (!conn.ns) return
+    let set = this._wsConns.get(conn.ns)
+    if (!set) {
+      set = new Set()
+      this._wsConns.set(conn.ns, set)
+    }
+    set.add(conn)
+  }
+
+  /**
+   * 로컬 WS 연결 해제 (close 시 driveWsConnection 이 호출 — framework-internal).
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+   * @returns {void}
+   */
+  _untrackWsConn(conn) {
+    const set = conn.ns ? this._wsConns.get(conn.ns) : undefined
+    if (set) {
+      set.delete(conn)
+      if (set.size === 0) this._wsConns.delete(conn.ns)
+    }
+    // 세션·유저 매핑 정리 + hub presence LEAVE (joinSession 으로 매핑된 연결만).
+    if (conn.userId !== undefined) {
+      const uset = this._userConns.get(conn.userId)
+      if (uset) {
+        uset.delete(conn)
+        if (uset.size === 0) this._userConns.delete(conn.userId)
+      }
+    }
+    if (conn.sessionId !== undefined) {
+      // 같은 sessionId 가 다른(새) 연결로 교체된 경우엔 이 연결만 지운다(오래된 연결의 close 가
+      // 새 매핑을 지우지 않게 동일성 확인).
+      if (this._sessionConns.get(conn.sessionId) === conn) this._sessionConns.delete(conn.sessionId)
+      if (this._hubLink?.isRegistered) {
+        try {
+          this._hubLink.leave(conn.sessionId)
+        } catch (err) {
+          // 소켓이 닫히는 중이면 LEAVE 송신 실패 — 비치명적. hub 의 bridge-gone 정리가 보강한다.
+          this.fastify.log?.debug?.({ err, sessionId: conn.sessionId, app: this.name }, 'ws.leave send failed')
+        }
+      }
+    }
+  }
+
+  /**
+   * HTTP `'upgrade'` 이벤트 처리 — 경로 매칭 → 인증(before) → 핸드셰이크 → 채널 라이프사이클.
+   *
+   * single 모드는 {@link MegaApp#listen} 이, scaffold 모드는 MegaServer 가 호스트 분기 후 호출한다.
+   * 매칭 WS 라우트가 없으면 404 로 거부 (HTTP 핸드셰이크 단계라 WS close 아님).
+   *
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:stream').Duplex} socket
+   * @param {Buffer} head
+   * @returns {void}
+   */
+  handleUpgrade(req, socket, head) {
+    const log = this.fastify.log
+
+    // H1: raw 소켓 error 가드. ws 패키지는 wss.handleUpgrade 가 WebSocket 을 만든 "후"에야
+    // 소켓에 'error' 리스너를 붙인다. 그 전(특히 비동기 before await 윈도우)에 클라이언트가
+    // ECONNRESET 등을 내면 listener 없는 EventEmitter 가 uncaught exception 으로 프로세스를
+    // 죽인다. 진입 즉시 임시 핸들러를 달고, 핸드셰이크 종단(reject 또는 WebSocket 생성) 시 뗀다.
+    const onSocketError = (/** @type {Error} */ err) => {
+      log.warn?.({ err, app: this.name }, 'raw socket error during upgrade handoff')
+    }
+    socket.on('error', onSocketError)
+    /** 임시 error 가드 해제 (각 종단 직전 호출 — 중복 호출 안전). */
+    const detachSocketGuard = () => socket.removeListener('error', onSocketError)
+
+    const path = String(req.url ?? '/').split('?')[0]
+    const route = this.wsRoutes.find((r) => r.path === path)
+    if (!route) {
+      log.debug?.({ path, app: this.name }, 'ws upgrade — no matching route (404)')
+      detachSocketGuard()
+      rejectUpgrade(socket, 404, 'Not Found', log)
+      return
+    }
+
+    // before = upgrade 인증 (ADR-091). throw 또는 false 반환 → 401 거부. 객체 반환 → 인증 신원(ctx.auth,
+    // DI): 마지막으로 객체를 돌려준 before 의 값이 신원이 된다. true/undefined 반환은 "허용,
+    // 신원 없음". onConnect 가 ctx.auth 로 받아 app.joinSession(...) 에 쓴다.
+    const before = Array.isArray(route.opts?.before) ? route.opts.before : []
+    Promise.resolve()
+      .then(async () => {
+        /** @type {any} */
+        let auth = null
+        for (const fn of before) {
+          const result = await fn(req)
+          if (result === false) return { allowed: false, auth: null }
+          if (result && typeof result === 'object') auth = result
+        }
+        return { allowed: true, auth }
+      })
+      .then(({ allowed, auth }) => {
+        if (allowed === false) {
+          log.debug?.({ path, app: this.name }, 'ws upgrade — before denied (401)')
+          detachSocketGuard()
+          rejectUpgrade(socket, 401, 'Unauthorized', log)
+          return
+        }
+        const wss = this._ensureWss()
+        wss.handleUpgrade(req, /** @type {any} */ (socket), head, (/** @type {import('ws').WebSocket} */ raw) => {
+          // WebSocket 인스턴스 생성됨 → ws 가 소켓 error 를 인수한다. 임시 가드 해제.
+          detachSocketGuard()
+          const codec = this._buildWsCodec(route, req)
+          driveWsConnection({ raw, req, route, app: this, codec, log, auth })
+        })
+      })
+      .catch((err) => {
+        // before 미들웨어 throw = 인증 실패. fail-closed 401 (silent 금지).
+        log.warn?.({ err, path, app: this.name }, 'ws upgrade — before threw (401)')
+        detachSocketGuard()
+        rejectUpgrade(socket, 401, 'Unauthorized', log)
+      })
+  }
+
+  /**
+   * 연결별 프레임 코덱 선택 (ADR-083). ASP 설정 시 namespace 활성 여부로 E:/P: 기본 결정.
+   * @param {{ path: string }} route
+   * @param {import('node:http').IncomingMessage} req
+   * @returns {import('./ws-upgrade.js').WsFrameCodec}
+   * @private
+   */
+  _buildWsCodec(route, req) {
+    const asp = this._wsAsp
+    if (!asp) return createPlainCodec()
+    const domain = String(req.headers.host ?? '').split(':')[0]
+    const ua = String(req.headers['user-agent'] ?? '')
+    // 활성 namespace = 기본 암호화(E:). 비활성 = 평문(P:). 둘 다 prefix 권위로 양방향 수신.
+    const encrypt = asp.namespaces.includes(route.path)
+    const terminator = new MegaAspTerminator({
+      masterSecret: asp.masterSecret,
+      domain,
+      wsPath: route.path,
+      ua,
+      encrypt,
+    })
+    return createAspCodec(terminator)
+  }
+
+  /**
+   * noServer 모드 WebSocketServer lazy 생성 (WS 라우트가 있을 때만).
+   * @returns {WebSocketServer}
+   * @private
+   */
+  _ensureWss() {
+    // perMessageDeflate 는 noServer 모드에서도 handleUpgrade → completeUpgrade 시 negotiate 된다
+    // (ws/lib/websocket-server.js completeUpgrade). false 면 ws 기본(압축 OFF)과 동일. ADR-078.
+    // maxPayload 명시(L-3, ADR-099) — 미지정 시 ws 기본 100 MiB 라 Hub(1 MiB)와 비대칭이 되므로 대칭화.
+    if (!this._wss) {
+      this._wss = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: this._wsPerMessageDeflate,
+        maxPayload: this._wsMaxPayloadBytes,
+      })
+    }
+    return this._wss
+  }
+
+  /**
+   * 등록된 WS 라우트가 있으면 httpServer 의 'upgrade' 이벤트를 자기 handleUpgrade 에 배선.
+   * single 모드 listen 에서 호출. WS 라우트가 없으면 no-op (불필요한 리스너 회피).
+   * @param {import('node:http').Server} httpServer
+   * @returns {void}
+   */
+  _attachWsUpgrade(httpServer) {
+    if (this.wsRoutes.length === 0) return
+    this._ensureWss()
+    httpServer.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head))
+  }
+
+  /**
+   * WS ASP 옵트인 정규화. masterSecret 없으면 null (평문 WS).
+   * @param {{ masterSecret?: string, websocket?: { namespaces?: string[] } }} [asp]
+   * @returns {{ masterSecret: string, namespaces: string[] } | null}
+   * @private
+   */
+  static _normalizeWsAsp(asp) {
+    if (!asp || typeof asp.masterSecret !== 'string' || asp.masterSecret.length === 0) {
+      return null
+    }
+    const namespaces = Array.isArray(asp.websocket?.namespaces) ? asp.websocket.namespaces : []
+    return { masterSecret: asp.masterSecret, namespaces }
+  }
+
+  /**
+   * Single 모드 전용 listen — MegaServer 거치지 않고 직접 listen.
+   * Scaffold 모드는 MegaServer.mount() + MegaServer.listen() 사용.
+   * @param {{ port?: number, host?: string }} [opts]
+   */
+  async listen(opts = {}) {
+    if (this.mode !== 'single') {
+      throw new Error(
+        `MegaApp '${this.name}' is in scaffold mode — use MegaServer.mount() + MegaServer.listen() instead.`,
+      )
+    }
+    const addr = await this.fastify.listen({ port: opts.port ?? 3000, host: opts.host ?? '0.0.0.0' })
+    // fastify.server 는 listen 후의 raw http.Server. WS 라우트가 있으면 upgrade 배선.
+    this._attachWsUpgrade(this.fastify.server)
+    return addr
+  }
+
+  /** 인스턴스 close — hub link · WS 연결 정리 후 진행 중 요청 grace 후 종료. */
+  async close() {
+    // hub link 먼저 끊는다 (더 이상 fan-out 수신 불필요). shutdown hook 도 함께 떼어 누수 방지(L1).
+    if (this._hubLink) {
+      this._hubLink.close()
+      this._hubLink = null
+      this._hubBridgeId = null
+      MegaShutdown.unregister(`mega-hublink:${this.name}`)
+    }
+    this._wsConns.clear()
+    this._userConns.clear()
+    this._sessionConns.clear()
+    // 활성 WS 연결을 먼저 정리 (1001 going away). noServer wss 는 clientTracking 기본 on.
+    if (this._wss) {
+      for (const client of this._wss.clients) client.close(1001, 'server shutting down')
+      await new Promise((resolve) => this._wss?.close(() => resolve(undefined)))
+      this._wss = null
+    }
+    await this.fastify.close()
+    // 세션 store 정리 (있으면) + shutdown hook 해제(누수 방지, hublink 패턴 정합).
+    if (this._sessionStore) {
+      MegaShutdown.unregister(`mega-session:${this.name}`)
+      await this._sessionStore.disconnect().catch((err) => this.fastify.log.warn({ err }, 'session store disconnect failed (close)'))
+    }
+  }
+
+  /** 이 앱의 세션 스토어 어댑터 (세션 미활성 시 null). 테스트·헬스용. */
+  get sessionStore() {
+    return this._sessionStore
+  }
+}