mega-framework 0.1.6 → 0.1.8

package/src/core/mega-app.js

@@ -1,17 +1,18 @@
 // @ts-check
 import Fastify from 'fastify'
 import { WebSocketServer } from 'ws'
-import { wrapEnvelope, REPLY_START_SYMBOL } from './envelope.js'
+import { wrapEnvelope, synthesizeEnvelopeResponseSchema, 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 { negotiateWsProtocol, WS_SUBPROTOCOL_PATTERN, WS_PROTOCOL_VERSION } from './ws-message.js'
 import { buildPerMessageDeflate } from './ws-compression.js'
+import { MegaWsPresence } from './ws-presence.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 { wrapPreHandler, composeTransform, composeAfter } from './pipeline.js'
 import { registerSecurityPlugins } from './security.js'
 import { registerMultipart } from './multipart.js'
 import { registerSession } from './session.js'
@@ -33,7 +34,7 @@ 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.
+ * 1 MiB — Hub(`DEFAULT_MAX_PAYLOAD_BYTES`, src/lib/ws-hub.js)와 대칭. 초과 프레임은 ws 가 1009 close.
  * core→cli 역방향 import 를 피하려 값을 여기 별도 정의(두 곳 모두 1 MiB 로 동일).
  */
 export const DEFAULT_WS_MAX_PAYLOAD_BYTES = 1_048_576
@@ -62,7 +63,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 검증, 폼 요청만 토큰 검증.
@@ -116,8 +117,10 @@ export class MegaApp {
    *   (디폴트 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] -
+   * @param {{ enabled?: boolean, paths?: { live?: string, ready?: string }, exposeCheckDetails?: boolean, exposeMetrics?: boolean, metricsPath?: string, metricsAllowList?: string[] }} [opts.health] -
    *   운영 관측성 config(Global-only, ADR-072/131). bootApp 이 global `health` 블록을 주입한다.
+   *   `exposeCheckDetails:true` 면 readiness 응답에 체크별 전체 필드(error 메시지 등)를 노출 — 기본 false
+   *   (체크별 `{ ok }` 만, ADR-186).
    *   `exposeMetrics:true` 면 `metricsPath`(디폴트 `/metrics`)에 Prometheus `/metrics` 라우트를 등록(보안 면제).
    *   `metricsAllowList` = 접근 허용 IP/CIDR(빈 배열이면 메인 포트 전체 노출, ADR-131). metricsPath 가 health
    *   경로와 충돌하면 부팅 throw. SDK 초기화(MegaMetrics.init)는 bootApp/prepareRuntime 이 담당.
@@ -130,6 +133,13 @@ export class MegaApp {
    *   — 라우트 핸들러와 동일한 canonical 시그니처(ADR-074/134). `ctx` 는 요청당 1회 만들어 핸들러와
    *   공유하므로, 미들웨어가 `ctx` 에 심은 값을 핸들러가 본다. 기존 `(req, reply)` 미들웨어는 3번째
    *   인자를 무시하므로 하위 호환.
+   * @param {Function[]} [opts.globalTransforms] - 앱/전역 레벨 응답 변환(ADR-021 체인의 "앱 → 전역"
+   *   구간, ADR-194). 계약: `async (req, reply, payload) => payload`. 라우트(+파일) transform 뒤·
+   *   자동 envelope wrap 직전에 배열 순서대로 실행(주입자가 앱 항목 먼저·전역 항목 뒤로 배열).
+   *   health/metrics 등 `config.skipGlobalLifecycle` 라우트는 제외.
+   * @param {Function[]} [opts.globalAfters] - 앱/전역 레벨 응답 후 side-effect(ADR-194). 계약:
+   *   `async (req, reply) => void` — 응답 전송 후(onResponse), throw 는 warn 로그 후 무시(ADR-091).
+   *   라우트(+파일) after 뒤에 실행. `config.skipGlobalLifecycle` 라우트는 제외.
    */
   constructor(opts) {
     if (!opts || typeof opts.name !== 'string' || opts.name.length === 0) {
@@ -162,6 +172,22 @@ export class MegaApp {
     /** @type {string|null} OpenAPI 옵트인 시 swagger-ui 경로(ADR-140). envelope onRoute 가 이 경로를 제외. */
     this._openapiPath = null
 
+    // 앱/전역 레벨 transform·after 슬롯 (ADR-021 체인의 "앱 → 전역" 구간, ADR-194). orchestrator/
+    // 플러그인이 주입하며 배열 순서가 곧 실행 순서(앱 항목 먼저·전역 항목 뒤를 주입자가 표현).
+    // onRoute 가 라우트별 체인에 합성한다 — transform 은 envelope wrap 직전, after 는 체인 끝.
+    for (const [key, list] of /** @type {Array<[string, unknown]>} */ ([
+      ['globalTransforms', opts.globalTransforms],
+      ['globalAfters', opts.globalAfters],
+    ])) {
+      if (list !== undefined && (!Array.isArray(list) || list.some((f) => typeof f !== 'function'))) {
+        throw new TypeError(`MegaApp('${this.name}'): ${key} must be an array of functions.`)
+      }
+    }
+    /** @type {Function[]} */
+    this._globalTransforms = Array.isArray(opts.globalTransforms) ? [...opts.globalTransforms] : []
+    /** @type {Function[]} */
+    this._globalAfters = Array.isArray(opts.globalAfters) ? [...opts.globalAfters] : []
+
     // WS ASP 옵트인 정규화. masterSecret 없으면 null = 평문 WS.
     this._wsAsp = MegaApp._normalizeWsAsp(opts.asp)
     // 브라우저↔Bridge WS 압축 (ADR-078). enabled=false → false (압축 OFF).
@@ -180,33 +206,26 @@ export class MegaApp {
     this._router = null
     /** @type {WebSocketServer|null} noServer 모드 WS 핸드셰이커 (lazy). */
     this._wss = null
-    /** @type {MegaHubLink|null} hub 연결 (scaffold 권장). */
-    this._hubLink = null
-    /** @type {import('./ws-cluster.js').MegaWsCluster|null} NATS 기반 클러스터 fan-out/roster (ADR-176, boot 자동배선). */
-    this._wsCluster = null
-    /** @type {import('./ws-roster.js').MegaWsRedisRoster|null} 채널별 redis roster(ADR-177, boot 자동배선).
-     * 접속자 목록(상태)을 redis HASH 로 cluster-wide 관리한다(broadcast 와 별개 — 멀티 허브 정합·즉시 스냅샷). */
-    this._wsRoster = 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 }),
+      // AJV 위반 전수 수집 (ADR-193) — 디폴트는 첫 위반 1개만 보고해 envelope details 배열(ADR-075)
+      // 표준·WS 검증(allErrors:true, ADR-096)과 비대칭이었다. customOptions 는 @fastify/ajv-compiler 가
+      // 디폴트(coerceTypes/useDefaults/removeAdditional 등) **위에 merge** 하므로(소스 확인:
+      // lib/validator-compiler.js Object.assign) allErrors 만 바꾼다. DoS 방어는 이중: 입력은 Fastify
+      // bodyLimit(기본 1 MiB)이, 응답·로그는 ajv-mapper 의 details cap(MAX_VALIDATION_DETAILS)이 bound.
+      ajv: { customOptions: { allErrors: true } },
       // request id 자동 부여는 Fastify v5 기본 제공 (meta.request_id 용)
       ...opts.fastifyOptions,
     })
 
+    // WS presence/hub 협력자 — 연결 인덱스 3종·hub link·cluster/roster 동기화를 전담(ws-presence.js).
+    // fastify 생성 직후 만들어 WS 경로 로그가 같은 pino 인스턴스를 쓴다.
+    this._presence = new MegaWsPresence({ appName: this.name, log: this.fastify.log })
+
     // 1) 응답 시작 시각 기록 (meta.took_ms 용, ADR-014)
     this.fastify.addHook('onRequest', async (req, reply) => {
       // REPLY_START_SYMBOL 은 Fastify 타입에 없는 우리 전용 symbol 키 — 부착 시 cast.
@@ -214,50 +233,63 @@ export class MegaApp {
         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({
+    // 1b) HTTP 루트 span (ADR-126) + 메트릭 (ADR-131) — **부팅 시점 분기** (G1 M-3, ADR-214).
+    //     이전엔 옵트인 OFF 여도 훅을 등록하고 본문에서 즉시 return 했는데, 본문 비용은 0 이어도
+    //     Fastify async hook 디스패치(훅당 Promise 1개) 자체가 매 요청 남는다. 옵트인은 부팅(boot 의
+    //     prepareRuntime 이 metrics → tracing 을 MegaApp 생성 **전에** init)에 결정되므로, 생성 시점에
+    //     OFF 면 훅을 아예 등록하지 않는다. 런타임 중 토글은 공개 표면에 없음(init 은 부팅 1회 계약 —
+    //     앱 생성 후 init 하는 직접 생성 경로는 미지원, ADR-214 명시).
+    const isTracingOn = MegaTracing.isEnabled()
+    const isMetricsOn = MegaMetrics.isEnabled()
+    if (isTracingOn) {
+      //     onRequest 에서 span 시작 + 활성 컨텍스트 진입(enterWith) → 핸들러의 ctx.tracer.span·어댑터 호출이
+      //     이 span 의 자식으로 중첩됨. onResponse 에서 status_code 기록 후 종료. 각 HTTP 요청은 독립 async
+      //     context 라 enterWith 가 요청 간 누수 없이 격리된다(실측 확인 — ADR-126).
+      this.fastify.addHook('onRequest', async (req, reply) => {
+        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: /** @type {any} */ (req).routeOptions?.url,
-          statusCode: reply.statusCode,
-          durationMs: reply.elapsedTime,
+          route,
+          path: req.url,
+          host,
           app: this.name,
+          // inbound traceparent/tracestate 를 부모로 복원(W3C trace context, ADR-196) — 게이트웨이/업스트림
+          // trace 에 루트 span 이 이어진다. 무효/부재 헤더는 종전대로 새 루트(fail-safe).
+          headers: req.headers,
         })
-      }
-    })
+        ;(/** @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 종료(단일 종료 지점).
+    // 트레이싱(span finish)·메트릭(recordHttp) 둘 중 하나라도 켜져 있을 때만 등록.
+    if (isTracingOn || isMetricsOn) {
+      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) — route 는 **매칭된 패턴**(routeOptions.url)만. 매칭 안 되면(404)
+        // recordHttp 가 __unmatched__ 로 접어 카디널리티 폭증 차단. reply.elapsedTime = Fastify 제공 ms.
+        if (isMetricsOn && 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 를 붙인다.
@@ -272,13 +304,34 @@ export class MegaApp {
       // 을 기대하므로 `{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
+      // response schema 는 envelope 모양으로 합성 — raw data 모양 그대로 두면 직렬화기가 envelope 를
+      // 그 스키마로 직렬화해 ok/data/meta 가 통째로 사라진다(silent 데이터 소실). 합성하면 사용자는
+      // raw data 모양만 선언(ADR-091)하면서 strict 직렬화(ADR-020)·OpenAPI 명세 정합이 함께 성립한다.
+      const schema = /** @type {Record<string, any> | undefined} */ (routeOptions.schema)
+      if (schema?.response && typeof schema.response === 'object') {
+        routeOptions.schema = { ...schema, response: synthesizeEnvelopeResponseSchema(schema.response) }
+      }
       const existing = routeOptions.preSerialization
       const chain = existing ? (Array.isArray(existing) ? [...existing] : [existing]) : []
+      // 앱/전역 transform·after (ADR-194) — health/metrics 류 인프라 라우트는 제외
+      // (config.skipGlobalLifecycle — 프로브 응답 모양은 인프라 계약이라 사용자 전역 변환 대상 아님).
+      const skipGlobalLifecycle = /** @type {any} */ (routeOptions.config)?.skipGlobalLifecycle === true
+      if (!skipGlobalLifecycle && this._globalTransforms.length > 0) {
+        // 라우트(+파일) transform 뒤·envelope wrap 앞 = ADR-021 순서(라우트 → 파일 → 앱/전역 → wrap).
+        chain.push(composeTransform(this._globalTransforms))
+      }
       // async 어댑터로 감싼다: Fastify 는 done 콜백 없는 preSerialization 훅을
       // "Promise 반환(async)" 으로만 인식한다. wrapEnvelope 는 순수 동기 함수(단위 테스트·
       // 재사용 용이)라 그대로 넣으면 Fastify 가 콜백 스타일로 오인해 done 을 영원히 기다린다.
       chain.push(async (req, reply, payload) => wrapEnvelope(req, reply, payload))
       routeOptions.preSerialization = chain
+      if (!skipGlobalLifecycle && this._globalAfters.length > 0) {
+        // after: 라우트(+파일) onResponse 뒤에 앱/전역 합성 append (ADR-021 — 라우트 → 파일 → 앱/전역).
+        const existingAfter = routeOptions.onResponse
+        const afterChain = existingAfter ? (Array.isArray(existingAfter) ? [...existingAfter] : [existingAfter]) : []
+        afterChain.push(composeAfter(this._globalAfters, { method: String(routeOptions.method), path: url }))
+        routeOptions.onResponse = afterChain
+      }
     })
 
     // 3) 글로벌 에러 핸들러 (AJV → MegaValidationError, MegaError → envelope, ADR-090).
@@ -402,7 +455,9 @@ export class MegaApp {
     // 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 }
+    // skipGlobalLifecycle(ADR-194): health/metrics 응답 모양은 인프라(프로브) 계약 — 사용자
+    // 앱/전역 transform·after 의 대상이 아니므로 제외한다(자동 envelope 는 기존대로 적용).
+    const HEALTH_EXEMPT = { skipAsp: true, skipCsrf: true, skipRateLimit: true, skipGlobalLifecycle: true }
     const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
     // 헬스 경로(ADR-072/181) — 설정 가능. 미지정/빈 문자열이면 기본 /health · /health/ready.
     const livePath = typeof healthCfg.paths?.live === 'string' && healthCfg.paths.live.length > 0 ? healthCfg.paths.live : '/health'
@@ -418,13 +473,24 @@ export class MegaApp {
         ts: Date.now(),
       }))
 
-      // readiness (checkAll 후 200 or 503)
+      // readiness (checkAll 후 200 or 503). 응답의 체크 상세는 기본 ok 불리언만 — 체크 함수가 담는
+      // error 메시지·부가 필드(내부 호스트·드라이버 정보)가 비인증 경로로 새지 않게 한다(ADR-186).
+      // 전체 상세가 필요하면 `health.exposeCheckDetails: true` 옵트인(내부망/가드 전제, 운영자 결정).
+      // 실패 상세는 응답 대신 서버 로그(warn)로 — 운영자는 항상 원인을 본다.
+      const exposeCheckDetails = healthCfg.exposeCheckDetails === true
       this.fastify.get(readyPath, { config: HEALTH_EXEMPT }, async (req, reply) => {
         const snapshot = await MegaHealth.checkAll()
-        if (!snapshot.ok) reply.code(503)
+        if (!snapshot.ok) {
+          reply.code(503)
+          this.fastify.log.warn?.({ app: this.name, checks: snapshot.checks }, 'health.ready failed')
+        }
+        const checks = exposeCheckDetails
+          ? snapshot.checks
+          : Object.fromEntries(Object.entries(snapshot.checks).map(([name, r]) => [name, { ok: /** @type {any} */ (r)?.ok === true }]))
         return {
           app: this.name,
-          ...snapshot,
+          ok: snapshot.ok,
+          checks,
           uptime_ms: Math.floor(process.uptime() * 1000),
           ts: Date.now(),
         }
@@ -474,18 +540,13 @@ export class MegaApp {
       }
     }
     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)
-        })
+        // arity-2 래퍼 + canonical ctx 주입(ADR-134) — 합성 정본은 pipeline.js(ADR-185). 라우트
+        // before/use 와 같은 래퍼라 같은 요청의 핸들러가 동일 ctx 를 이어받는다(요청당 캐싱).
+        this.fastify.addHook('preHandler', wrapPreHandler(/** @type {Function} */ (mw), this))
       }
     }
 
@@ -550,11 +611,6 @@ export class MegaApp {
     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.
@@ -603,453 +659,149 @@ export class MegaApp {
     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))
-    // 허브가 fan-out 하는 presence(JOIN/LEAVE/METADATA)·heartbeat 는 broadcast 채널 멤버십·keepalive 용으로만
-    // 의미 있다. **roster(접속자 목록)는 redis(MegaWsRedisRoster, ADR-177)가 별도 관리**하므로 브릿지는 이들을
-    // 소비하지 않는다 — no-op 핸들러로 "no handler for type" 노이즈만 차단한다(JOIN 자체는 joinSession 이
-    // broadcast 채널 가입용으로 계속 송신). 멀티 허브에서도 redis 가 single source-of-truth 라 명단이 정합.
-    const noopHub = () => {}
-    link.on(HUB_MESSAGE_TYPES.JOIN, noopHub)
-    link.on(HUB_MESSAGE_TYPES.LEAVE, noopHub)
-    link.on(HUB_MESSAGE_TYPES.BULK_LEAVE, noopHub)
-    link.on(HUB_MESSAGE_TYPES.METADATA, noopHub)
-    link.on(HUB_MESSAGE_TYPES.HEARTBEAT, noopHub)
-    // 재연결 성공 시 presence 재동기화(ADR-098) — hub 는 절단 시점 presence 를 잃으므로 broadcast 채널을 다시 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
+  // ── WS presence/hub — MegaWsPresence(ws-presence.js) 위임 ─────────────────────────────
+  // 연결 인덱스 3종·hub link·cluster/roster 동기화는 협력자(MegaWsPresence)가 전담한다.
+  // MegaApp 은 공개 표면(체이닝 포함)과 framework-internal(_접두) 멤버를 위임으로 보존한다 —
+  // driveWsConnection(_track/_untrack)·boot 자동배선(_deliver*/localRosterMembers)·기존 테스트 호환.
+
+  /** 현재 연결된 hub link (미연결 시 null). */
+  get hubLink() {
+    return this._presence.hubLink
   }
 
   /**
-   * hub presence 재동기화 — bridge-subscriber 채널 JOIN + 활성 사용자 세션 JOIN 을 모두 다시 보낸다.
-   * 최초 등록 직후와 재연결(RECONNECTED) 직후에 호출된다. hub 의 JOIN 처리는 멱등(같은 sessionId 덮어씀).
-   * @returns {void}
-   * @private
+   * 이 bridge 를 hub 에 연결한다 (ADR-033/059) — 계약·옵션은 {@link MegaWsPresence#connectHub} 정본.
+   * @param {any} [config] - MegaBridgeHubConfig(§2.1) + 구독 채널.
+   * @returns {Promise<import('./hub-link.js').MegaHubLink>} 등록 완료된 link.
    */
-  _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 } : {}),
-      })
-    }
+  async connectHub(config) {
+    return this._presence.connectHub(config)
   }
 
   /**
-   * 실 사용자 세션을 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).
+   * 실 사용자 세션을 hub presence 에 등록하고 로컬 매핑을 만든다 — {@link MegaWsPresence#joinSession} 위임.
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+   * @param {{ userId: string, sessionId: string, channels?: string[], metadata?: Object }} [entry]
    * @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 } : {}) })
-    }
-    // NATS roster 동기화 (ADR-176) — 프레임워크가 클러스터 접속자 목록을 자동 관리한다(개발자 코드 불요).
-    // ns 는 연결의 namespace. roster:'none' 이면 로컬만 갱신한다.
-    if (this._wsCluster && typeof conn.ns === 'string') {
-      this._wsCluster.rosterAdd({ ns: conn.ns, sessionId, userId, ...(metadata ? { metadata } : {}) })
-    }
-    // redis roster 동기화 (ADR-177) — **채널별** 접속자 목록을 redis HASH 에 add(멀티 허브 정합). best-effort.
-    if (this._wsRoster && chans.length > 0) {
-      const member = { userId, ...(metadata ? { metadata } : {}) }
-      for (const ch of chans) {
-        this._wsRoster.add(ch, sessionId, member).catch((err) =>
-          this.fastify.log?.warn?.({ err, channel: ch, app: this.name }, 'ws-roster add failed'),
-        )
-      }
-    }
+  joinSession(conn, entry) {
+    this._presence.joinSession(conn, entry)
     return this
   }
 
   /**
-   * 채널 broadcast — 로컬 ns 소켓에 즉시 전달 + (hub 연결 시) 클러스터 fan-out.
-   *
+   * 채널 broadcast — 로컬 즉시 전달 + (hub/NATS 연결 시) 클러스터 fan-out. {@link MegaWsPresence#broadcast} 위임.
    * @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)')
-      }
-    }
-    // NATS 클러스터 fan-out (ADR-176, boot 자동배선). 로컬은 위에서 전달했고, 다른 인스턴스는 구독으로
-    // 받아 각자 전달한다(echo 는 instanceId 로 스킵). publish 실패는 best-effort — local 은 이미 성공.
-    if (this._wsCluster) {
-      this._wsCluster.publishBroadcast({ ns, channel, message, exceptSessionIds }).catch((err) => {
-        const log = /** @type {any} */ (this.fastify.log)
-        log?.warn?.({ err, ns, channel, app: this.name }, 'app.broadcast nats fan-out failed (local delivered)')
-      })
-    }
+  broadcast(args) {
+    this._presence.broadcast(args)
   }
 
   /**
-   * 특정 사용자에게 직접 전송 (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 }`.
+   * 특정 사용자에게 직접 전송 (ADR-035) — {@link MegaWsPresence#directToUser} 위임.
+   * @param {string} userId
+   * @param {{ type: string, payload?: Object }} message
    * @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)')
-      }
-    }
-    // NATS 클러스터 direct (ADR-176) — 다른 인스턴스의 같은 userId 세션까지. echo 는 instanceId 로 스킵.
-    if (this._wsCluster) {
-      this._wsCluster.publishDirect(userId, message).catch((err) => {
-        const log = /** @type {any} */ (this.fastify.log)
-        log?.warn?.({ err, userId, app: this.name }, 'app.directToUser nats fan-out failed (local delivered)')
-      })
-    }
+    this._presence.directToUser(userId, message)
   }
 
   /**
-   * 세션 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 - 갱신할 메타데이터(명시 필드만).
+   * 세션 presence 메타데이터 갱신 (ADR-059) — {@link MegaWsPresence#updateMetadata} 위임.
+   * @param {string} sessionId
+   * @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)')
-      }
-    }
+    this._presence.updateMetadata(sessionId, metadata)
     return this
   }
 
   /**
-   * NATS 클러스터 fan-out/roster 를 이 앱에 배선한다 (ADR-176). boot 가 `wsCluster` config 를 보고
-   * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+   * NATS 클러스터 fan-out/roster 배선 (ADR-176, boot 자동 호출) — {@link MegaWsPresence#setWsCluster} 위임.
    * @param {import('./ws-cluster.js').MegaWsCluster|null} cluster
    * @returns {this}
    */
   setWsCluster(cluster) {
-    this._wsCluster = cluster
+    this._presence.setWsCluster(cluster)
     return this
   }
 
   /**
-   * 해당 ns(WS 채널 경로)의 **클러스터 전역 접속자 목록**을 반환한다 (ADR-176). `wsCluster` 자동배선 +
-   * `joinSession`/disconnect 훅으로 프레임워크가 동기화하므로 개발자는 roster 코드를 짜지 않고 읽기만 한다.
-   * wsCluster 미배선(또는 roster:'none')이면 로컬 멤버만 반환한다.
-   *
-   * @param {string} ns - WS namespace(채널 경로, 예: '/ws/chat').
+   * ns(WS 채널 경로) 기준 접속자 목록 (ADR-176) — {@link MegaWsPresence#roster} 위임.
+   * @param {string} ns
    * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
    */
   roster(ns) {
-    if (this._wsCluster) return this._wsCluster.roster(ns) // NATS: 이미 cluster-wide(roster 동기화 포함).
-    // ns 기준 로컬 명단(동기 API). **채널 기준 redis roster(ADR-177)** 는 `ctx.presence.list()`(async)가
-    // 다룬다 — 이 메서드는 NATS/로컬용 ns 기준 동기 API 로 유지(하위호환).
-    /** @type {Array<{ sessionId: string, userId: string, metadata?: Object }>} */
-    const out = []
-    for (const [sessionId, conn] of this._sessionConns) {
-      if (conn.ns !== ns || !conn.isOpen) continue
-      out.push({ sessionId, userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) })
-    }
-    return out
+    return this._presence.roster(ns)
   }
 
   /**
-   * 채널별 redis roster(ADR-177)를 이 앱에 배선한다. boot 가 `bridgeHub.roster.driver==='redis'` 일 때
-   * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+   * 채널별 redis roster 배선 (ADR-177, boot 자동 호출) — {@link MegaWsPresence#setWsRoster} 위임.
    * @param {import('./ws-roster.js').MegaWsRedisRoster|null} roster
    * @returns {this}
    */
   setWsRoster(roster) {
-    this._wsRoster = roster
+    this._presence.setWsRoster(roster)
     return this
   }
 
   /**
-   * 주어진 **채널들**의 cluster-wide 접속자 목록 — redis roster(원격 포함) + 로컬 세션을 병합한다(ADR-177).
-   * 로컬을 항상 포함해 join 직후 redis HSET 반영 전에도 본인이 빠지지 않게 한다. `ctx.presence.list()` 의
-   * redis 경로가 호출(async). roster 미배선이면 로컬 채널 멤버만.
+   * 채널들의 cluster-wide 접속자 목록 (ADR-177) — {@link MegaWsPresence#presenceList} 위임.
    * @param {string[]} channels
    * @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
    */
   async presenceList(channels) {
-    const want = new Set(Array.isArray(channels) ? channels : [])
-    /** @type {Map<string, { sessionId: string, userId: string, metadata?: Object }>} */
-    const out = new Map()
-    // 로컬 세션(이 워커) — 요청 채널에 가입한 것. 항상 fresh(본인 포함).
-    for (const [sessionId, conn] of this._sessionConns) {
-      if (!conn.isOpen || !conn.channels) continue
-      let inCh = false
-      for (const ch of conn.channels) {
-        if (want.has(ch)) {
-          inCh = true
-          break
-        }
-      }
-      if (inCh) out.set(sessionId, { sessionId, userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) })
-    }
-    // redis(cluster-wide) — 다른 워커/허브의 세션까지.
-    if (this._wsRoster) {
-      // 여러 채널 redis 조회를 **병렬화**(Promise.all) — onConnect 핫패스의 직렬 라운드트립 누적 제거(Med).
-      const lists = await Promise.all([...want].map((ch) => this._wsRoster.list(ch)))
-      for (const list of lists) for (const m of list) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
-    }
-    return [...out.values()]
+    return this._presence.presenceList(channels)
   }
 
   /**
-   * 이 워커의 로컬 멤버 목록 — redis roster heartbeat 갱신 대상(ADR-177). joinSession 으로 매핑된
-   * (채널 × 세션)마다 1개. MegaWsRedisRoster 가 주기적으로 이 목록의 expiresAt 을 갱신한다.
+   * 이 워커의 로컬 멤버 목록 (redis roster heartbeat 갱신 대상, ADR-177) — {@link MegaWsPresence#localRosterMembers} 위임.
    * @returns {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>}
    */
   localRosterMembers() {
-    /** @type {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>} */
-    const out = []
-    for (const [sessionId, conn] of this._sessionConns) {
-      if (!conn.isOpen || !conn.channels) continue
-      const member = { userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) }
-      for (const ch of conn.channels) out.push({ channel: ch, sessionId, member })
-    }
-    return out
+    return this._presence.localRosterMembers()
   }
 
   /**
-   * broadcast payload 를 로컬 ns 소켓에 전달한다. message 는 `{ type, payload }` 내부 envelope.
-   *
-   * `exceptSessionIds` 에 든 sessionId 로 매핑된 연결은 제외한다(ADR-098). 세션 매핑이 없는
-   * 연결(zero-config·미JOIN)은 sessionId 가 없어 제외 대상에 걸리지 않으므로 그대로 받는다.
-   *
+   * broadcast payload 로컬 전달 (framework-internal — boot 의 MegaWsCluster 배선이 사용).
    * @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 })
-    }
+  _deliverBroadcast(payload) {
+    this._presence._deliverBroadcast(payload)
   }
 
   /**
-   * direct payload 를 **해당 userId 로 매핑된 로컬 연결에만** 전달한다 (H-latent guard).
-   *
-   * 초기에는 매핑이 없어 모든 연결에 flood 됐다(cross-user 누출). {@link MegaApp#joinSession}
-   * 으로 만든 `userId → 연결` 매핑을 통해 대상 사용자에게만 보낸다. 매핑이 없는 userId 면 no-op
-   * (다른 사용자에게 새지 않음).
-   *
+   * direct payload 로컬 전달 (framework-internal — boot 의 MegaWsCluster 배선이 사용).
    * @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 })
-    }
+  _deliverDirect(payload) {
+    this._presence._deliverDirect(payload)
+  }
+
+  /**
+   * hub 의 DISCONNECT(admin-kick, ADR-097) 라우팅 처리 (framework-internal).
+   * @param {{ sessionId: string, reason?: string, requeue?: boolean }} payload
+   * @returns {void}
+   * @private
+   */
+  _handleHubDisconnect(payload) {
+    this._presence._handleHubDisconnect(payload)
   }
 
   /**
-   * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal). hub broadcast 의 local 전달 대상.
+   * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal).
    * @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)
+    this._presence._trackWsConn(conn)
   }
 
   /**
@@ -1058,42 +810,43 @@ export class MegaApp {
    * @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')
-        }
-      }
-      // NATS roster 제거 (ADR-176) — disconnect 시 클러스터 접속자 목록에서 자동 제거(개발자 코드 불요).
-      this._wsCluster?.rosterRemove(conn.sessionId)
-      // redis roster 제거 (ADR-177) — 이 세션이 가입한 모든 채널에서 제거. best-effort.
-      if (this._wsRoster && conn.channels) {
-        for (const ch of conn.channels) {
-          this._wsRoster.remove(ch, /** @type {string} */ (conn.sessionId)).catch((err) =>
-            this.fastify.log?.warn?.({ err, channel: ch, app: this.name }, 'ws-roster remove failed'),
-          )
-        }
-      }
-    }
+    this._presence._untrackWsConn(conn)
+  }
+
+  // 상태 필드 호환 접근자 — 외부 @private 사용처(ws-upgrade 의 `_wsRoster` 게이트, 테스트의 mock 주입·
+  // 검증)가 분리 전 필드명을 그대로 쓸 수 있게 presence 로 위임한다.
+  /** @returns {import('./hub-link.js').MegaHubLink|null} */
+  get _hubLink() {
+    return this._presence._hubLink
+  }
+  set _hubLink(v) {
+    this._presence._hubLink = v
+  }
+  /** @returns {import('./ws-cluster.js').MegaWsCluster|null} */
+  get _wsCluster() {
+    return this._presence._wsCluster
+  }
+  set _wsCluster(v) {
+    this._presence._wsCluster = v
+  }
+  /** @returns {import('./ws-roster.js').MegaWsRedisRoster|null} */
+  get _wsRoster() {
+    return this._presence._wsRoster
+  }
+  set _wsRoster(v) {
+    this._presence._wsRoster = v
+  }
+  /** @returns {Map<string, import('./ws-upgrade.js').MegaWsConnection>} */
+  get _sessionConns() {
+    return this._presence._sessionConns
+  }
+  /** @returns {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+  get _userConns() {
+    return this._presence._userConns
+  }
+  /** @returns {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
+  get _wsConns() {
+    return this._presence._wsConns
   }
 
   /**
@@ -1157,7 +910,11 @@ export class MegaApp {
           // WebSocket 인스턴스 생성됨 → ws 가 소켓 error 를 인수한다. 임시 가드 해제.
           detachSocketGuard()
           const codec = this._buildWsCodec(route, req)
-          driveWsConnection({ raw, req, route, app: this, codec, log, auth })
+          // 핸드셰이크에서 협상된 envelope 버전(_ensureWss handleProtocols, `mega.v<N>` subprotocol).
+          // 미협상(레거시·subprotocol 없음)이면 v1 — 연결별 envelope 검증 기준이 된다.
+          const m = WS_SUBPROTOCOL_PATTERN.exec(raw.protocol ?? '')
+          const protocolVersion = m ? Number(m[1]) : WS_PROTOCOL_VERSION
+          driveWsConnection({ raw, req, route, app: this, codec, log, auth, protocolVersion })
         })
       })
       .catch((err) => {
@@ -1206,6 +963,16 @@ export class MegaApp {
         noServer: true,
         perMessageDeflate: this._wsPerMessageDeflate,
         maxPayload: this._wsMaxPayloadBytes,
+        // envelope 버전 협상 — 클라가 `mega.v<N>` subprotocol 을 제안하면 최고 상호 버전을 채택해
+        // 응답 Sec-WebSocket-Protocol 로 확정 통지한다. mega.* 미제안(레거시)·상호 버전 없음이면
+        // subprotocol 없이 수락(= v1 폴백) — 핸드셰이크를 절대 거부하지 않아 구버전 클라가 깨지지 않는다.
+        // ⚠️ ws 기본(handleProtocols 미설정)은 첫 제안 토큰을 맹목 echo 한다(미지원 버전을 "지원한다"고
+        // 답하는 거짓 신호) — 명시 핸들러가 협상 정확성의 전제다.
+        handleProtocols: (/** @type {Set<string>} */ protocols) => {
+          const result = negotiateWsProtocol(protocols)
+          if (!result || result.subprotocol === undefined) return false // subprotocol 미선택 = v1 폴백.
+          return result.subprotocol
+        },
       })
     }
     return this._wss
@@ -1256,31 +1023,8 @@ export class MegaApp {
 
   /** 인스턴스 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}`)
-    }
-    // NATS 클러스터 정리(ADR-176) — 구독·heartbeat/sweep 타이머·roster 멤버 해제. boot 의 shutdown hook 과
-    // **양쪽**에서 정리해야 시그널을 안 거치는 종료(server.close()/프로그램적 재시작/멀티앱 부분 종료)에서도
-    // 누수가 없다(_hubLink/_wsRoster 와 동일 대칭, H1). stop() 은 _isStarted 가드로 멱등이라 중복 안전.
-    if (this._wsCluster) {
-      await this._wsCluster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-cluster stop failed'))
-      this._wsCluster = null
-      MegaShutdown.unregister(`mega-ws-cluster:${this.name}`)
-    }
-    // redis roster 정리(ADR-177) — heartbeat 중지 + 로컬 멤버 즉시 제거. _sessionConns 를 비우기 **전에**
-    // 호출해야 stop() 이 localRosterMembers 로 자기 멤버를 redis 에서 뺄 수 있다.
-    if (this._wsRoster) {
-      await this._wsRoster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-roster stop failed'))
-      this._wsRoster = null
-      MegaShutdown.unregister(`mega-wsroster:${this.name}`)
-    }
-    this._wsConns.clear()
-    this._userConns.clear()
-    this._sessionConns.clear()
+    // WS presence 정리(hub link → cluster → roster → 연결 인덱스, 협력자가 자기 hook 까지 짝맞춰 해제).
+    await this._presence.close()
     // 활성 WS 연결을 먼저 정리 (1001 going away). noServer wss 는 clientTracking 기본 on.
     if (this._wss) {
       for (const client of this._wss.clients) client.close(1001, 'server shutting down')
@@ -1288,6 +1032,10 @@ export class MegaApp {
       this._wss = null
     }
     await this.fastify.close()
+    // 생성자가 등록한 자기 close hook 도 해제 — hublink/ws-cluster/wsroster/session 4종과 동일한
+    // 짝맞춤. 남겨두면 graceful shutdown 시 이미 닫힌 fastify 를 중복 close 하고, 앱을 만들고 닫는
+    // 장수 프로세스(테스트·동적 마운트)에서 handlers 배열이 누적된다.
+    MegaShutdown.unregister(`mega-app:${this.name}`)
     // 세션 store 정리 (있으면) + shutdown hook 해제(누수 방지, hublink 패턴 정합).
     if (this._sessionStore) {
       MegaShutdown.unregister(`mega-session:${this.name}`)