mega-framework 0.1.6 → 0.1.8

package/src/core/boot.js

@@ -7,17 +7,13 @@
  * 본 모듈이 그 단일 지점이다 — `loadPlugins` 를 실 부팅 시퀀스에 끼우고 lifecycle hook(beforeBoot/
  * afterBoot/beforeShutdown)을 구동한다(ADR-123).
  *
- * # 부팅 시퀀스 (02-architecture §14 — 4·5단계 = 플러그인)
- *   1. `loadAndValidateConfig(projectRoot)` — mega.config.js + app.config.js 로드·검증(1~3단계).
- *   4·5. `loadPlugins(global.plugins, host, { projectRoot })` — resolve→shape→apiVersion→install(순서대로).
- *   2. `buildFromGlobalConfig(global)` — 어댑터 인스턴스화 + LIFO shutdown hook(**앱 생성보다 먼저**,
- *      adapter-manager 종료 순서 주석).
- *   3. `connectAll({ ping })` — 어댑터 connect(+옵션 healthCheck). 실패 시 매니저가 LIFO cleanup 후 throw.
- *   7. `host.runLifecycle('beforeBoot', ctx)` — 부팅 직전 hook(L-2 ctx 주입).
- *   6. 각 앱: `new MegaApp({ ...config, plugins, globalMiddlewares })` + 라우트 자동 로딩 + vhost mount.
- *   9. `server.listen({ port, host })`(listen=false 면 건너뜀 — 테스트/CLI 분기).
- *   10. `host.runLifecycle('afterBoot', ctx)` — 부팅 완료 hook.
- *   +  beforeShutdown hook 을 `MegaShutdown` 에 브리지(graceful, per-hook catch — ADR-122).
+ * # 부팅 시퀀스 — declarative step 배열이 정본 (02-architecture §14 의 코드화)
+ *   - 공통 토대 = {@link PREPARE_STEP_NAMES}: config → plugins → adapters → health-auto-checks →
+ *     metrics → tracing → workers → ws-hub → boot-context (`prepareRuntime`).
+ *   - 서버 부팅 = {@link BOOT_STEP_NAMES}: runtime(↑) → before-boot-hook → logger → server → apps →
+ *     cluster-transport → listen → after-boot-hook → shutdown-bridge (`bootApp`).
+ *   각 step 은 prerequisite(`needs` — 선행 산출물 검증)와 on-fail 정책(`onFail` — 기본 abort)을
+ *   명시한다({@link runBootSteps}). 순서를 바꾸거나 step 을 빼면 prerequisite 가 즉시 throw 한다.
  *
  * # ⚠️ install → buildFromGlobalConfig 순서 (config-driven driver 의 핵심 제약)
  *   roadmap §224 검증기준("샘플 플러그인이 `adapters.register('sample')` → `services.databases.x.driver:
@@ -54,7 +50,9 @@ import { MegaWsCluster } from './ws-cluster.js'
 import { MegaWsRedisRoster } from './ws-roster.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
-import { MegaWsHub } from '../cli/ws-hub.js'
+import * as MegaHealth from '../lib/mega-health.js'
+import { MegaWsHub } from '../lib/ws-hub.js'
+import { MegaConfigError } from '../errors/config-error.js'
 
 /**
  * 부팅 결과 핸들.
@@ -65,7 +63,7 @@ import { MegaWsHub } from '../cli/ws-hub.js'
  * @property {Array<{ name: string, config: Object }>} apps - 로드된 앱 config 목록.
  * @property {MegaApp[]} megaApps - 생성된 MegaApp 인스턴스(등록 순서).
  * @property {BootContext} ctx - lifecycle hook 에 넘긴 boot context.
- * @property {import('../cli/ws-hub.js').MegaWsHub | null} wsHub - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
+ * @property {import('../lib/ws-hub.js').MegaWsHub | null} wsHub - embedded wsHub(ADR-137, `wsHub.enabled` OFF 면 null).
  * @property {import('pino').Logger | null} appLogger - 공유 pino 로거(ADR-141, logger 비활성이면 null). CLI 시작 메시지 등에 재사용.
  */
 
@@ -118,75 +116,217 @@ export function buildBootContext(global, logger) {
 }
 
 /**
- * 런타임 공통 준비 — config 로드 → 플러그인 install → 어댑터 build → connect → boot ctx.
- * `bootApp`(서버)·`mega worker`/`mega scheduler`(CLI 호스트)가 **같은 순서**를 공유한다(install <
- * build — config-driven driver 제약, 위 주석 참조). lifecycle hook/앱 생성/ listen 직전까지의 토대.
+ * 공유 어댑터 전수의 `healthCheck()` 를 `MegaHealth` 에 `<domain>:<globalKey>` 이름으로 등록한다.
+ * `/health/ready` 가 어댑터 생사를 실제로 반영하게 하는 배선 — `prepareRuntime` 이 connect 직후
+ * 호출한다(`health.autoChecks:false` 옵트아웃). 등록은 이름 기준 덮어쓰기라 재부팅(테스트)에도 멱등.
  *
- * @param {string} projectRoot
- * @param {{ ping?: boolean, logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
- * @returns {Promise<{ global: Object, apps: Array<{ name: string, config: Object }>, host: MegaPluginHost, ctx: BootContext, wsHub: (MegaWsHub | null) }>}
+ * @param {Array<{ domain: string, key: string, adapter: { healthCheck: () => Promise<{ ok: boolean }> } }>} [entries] -
+ *   대상 어댑터 엔트리(기본: 어댑터 매니저의 전체 등록분). 테스트 주입용.
+ * @returns {string[]} 등록한 체크 이름 목록.
  */
-export async function prepareRuntime(projectRoot, { ping = false, logger } = {}) {
-  // 1~3단계: config 로드 + 검증.
-  const { global, apps } = await loadAndValidateConfig(projectRoot)
-  logger?.debug?.({ apps: apps.map((a) => a.name) }, 'boot.config loaded')
-
-  // 4·5단계: 플러그인 로딩 + install — **어댑터 빌드보다 먼저**(config-driven driver, 상단 주석 참조).
-  const host = new MegaPluginHost({ logger })
-  await loadPlugins(/** @type {any} */ (global).plugins, host, { projectRoot, logger })
-  logger?.debug?.({ plugins: host.loadedPlugins.map((p) => p.name) }, 'boot.plugins installed')
-
-  // 어댑터 인스턴스화 + connect (MegaApp 생성보다 먼저 — LIFO shutdown 순서, adapter-manager 주석).
-  buildFromGlobalConfig(global)
-  await connectAll({ logger, ping })
-  logger?.debug?.('boot.adapters connected')
-
-  // 메트릭 SDK 옵트인 (ADR-072/131) — global `health.exposeMetrics:true` 면 MegaMetrics 초기화
-  // + 어댑터 onCallEnd 일괄 구독(connect 직후 — 모든 공유 어댑터 호출이 mega_adapter_* 메트릭으로 집계).
-  // 옵트인 OFF 면 init 미호출 → 모든 record* 가 0 비용. /metrics 라우트는 MegaApp 이 같은 config 로 등록.
-  const healthCfg = /** @type {any} */ (global).health
-  if (healthCfg && healthCfg.exposeMetrics === true && !MegaMetrics.isEnabled()) {
-    MegaMetrics.init({
-      serviceName: healthCfg.serviceName ?? /** @type {any} */ (global).server?.serviceName ?? process.env.MEGA_OTEL_SERVICE_NAME ?? 'mega-framework',
-      version: /** @type {any} */ (global).server?.version,
-      environment: process.env.NODE_ENV,
-    })
-    const subscribed = MegaMetrics.attachToManager({ entries: adapterEntries })
-    MegaShutdown.register('mega-metrics', async () => {
-      await MegaMetrics.shutdown()
-    })
-    logger?.debug?.({ subscribed }, 'boot.metrics enabled')
+export function registerAdapterHealthChecks(entries = adapterEntries()) {
+  /** @type {string[]} */
+  const names = []
+  for (const e of entries) {
+    const name = `${e.domain}:${e.key}`
+    MegaHealth.register(name, () => e.adapter.healthCheck())
+    names.push(name)
   }
+  return names
+}
 
-  // 트레이싱 SDK 옵트인 (ADR-104/114/126/163) — `MEGA_OTEL_ENABLED=true` env 면 MegaTracing 초기화 + 어댑터
-  // onCallEnd 일괄 구독(자동 span, ADR-114). 메트릭(위)과 대칭 — `fromEnv` 가 env 게이트(미설정/false=no-op,
-  // 0 비용)한다. 미옵트인이면 mega-app 의 HTTP/WS 루트 span·`ctx.tracer.span` 이 모두 no-op. **부팅에서 한 번
-  // 켜야 프로덕션 분산 트레이싱이 동작한다** — 이전엔 boot 가 `MegaTracing.fromEnv()` 를 호출하지 않아(메트릭만
-  // 배선) 프로덕션에서 트레이싱이 미작동했다(ADR-163 에서 boot 배선 추가). 재진입 방지로 isEnabled 가드.
-  if (!MegaTracing.isEnabled() && MegaTracing.fromEnv() === true) {
-    const tracedAdapters = MegaTracing.attachToManager({ entries: adapterEntries })
-    MegaShutdown.register('mega-tracing', async () => {
-      await MegaTracing.shutdown()
-    })
-    logger?.debug?.({ subscribed: tracedAdapters }, 'boot.tracing enabled')
+/**
+ * 부트 step 정의 — 부팅 시퀀스의 한 단계.
+ * @typedef {Object} BootStep
+ * @property {string} name - step 이름(로그·prerequisite 에러 식별자).
+ * @property {string[]} [needs] - 선행 step 이 state 에 만들어 둬야 하는 키(prerequisite). 누락 시
+ *   `boot.step_prerequisite` throw — step 순서 변경·누락 같은 배선 실수를 즉시 드러낸다.
+ * @property {'abort'|'warn'} [onFail] - 실패 정책. `'abort'`(기본) = fail-fast throw(M-1 정리 경로),
+ *   `'warn'` = best-effort(warn 로그 후 다음 step 계속 — 부팅을 막으면 안 되는 부가 단계용).
+ * @property {(state: Record<string, any>) => Promise<void>|void} run - 단계 본체. 산출물은 state 에 쓴다.
+ */
+
+/**
+ * step 배열 실행기 — 각 step 의 prerequisite 검증 → 실행 → 길목 debug 로그(start/done/tookMs).
+ * 실패는 step 의 `onFail` 정책을 따른다(기본 abort — 현재 부트 시퀀스 전 단계가 fail-fast).
+ *
+ * @param {BootStep[]} steps - 실행할 step 정의(순서 = 시퀀스 정본).
+ * @param {Record<string, any>} state - step 간 공유 상태(산출물 버스).
+ * @param {{ debug?: Function, warn?: Function }} [logger]
+ * @returns {Promise<void>}
+ * @throws {MegaConfigError} prerequisite 누락(`boot.step_prerequisite`) — 배선 오류는 즉시 abort.
+ */
+export async function runBootSteps(steps, state, logger) {
+  for (const step of steps) {
+    for (const key of step.needs ?? []) {
+      if (state[key] === undefined) {
+        throw new MegaConfigError(
+          'boot.step_prerequisite',
+          `boot step '${step.name}' requires state '${key}' (produced by an earlier step).`,
+          { details: { step: step.name, missing: key } },
+        )
+      }
+    }
+    const startedAt = Date.now()
+    logger?.debug?.({ step: step.name }, 'boot.step start')
+    try {
+      await step.run(state)
+    } catch (err) {
+      if (step.onFail === 'warn') {
+        // best-effort step — 부가 단계 실패가 부팅을 막지 않는다(silent 금지, warn 가시화).
+        logger?.warn?.({ err, step: step.name }, 'boot.step failed (best-effort, continuing)')
+        continue
+      }
+      logger?.debug?.({ step: step.name }, 'boot.step failed — aborting boot')
+      throw err
+    }
+    logger?.debug?.({ step: step.name, tookMs: Date.now() - startedAt }, 'boot.step done')
   }
+}
 
-  // CPU 워커 풀(ADR-124) — 등록 소스 = `config.workers`(정적) + 플러그인 `host.listWorkers()`(동적,
-  // ADR-134). jobs/schedules 듀얼 소스(`collectRegistrations`, ADR-123)와 동형이다. `buildWorkers` 가
-  // `static name` 중복을 부팅 시 fail-fast 한다. 어댑터 connect **뒤**에 등록되므로 MegaShutdown LIFO 상
-  // 워커가 어댑터보다 먼저 정리된다(워커가 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
-  const workerClasses = [...(/** @type {any} */ (global).workers ?? []), ...host.listWorkers()]
-  buildWorkers({ workers: /** @type {any} */ (workerClasses) }, { projectRoot })
-  await startWorkers({ logger })
-  logger?.debug?.({ workers: workerClasses.length }, 'boot.workers started')
+/**
+ * 런타임 공통 준비 step 들 — `prepareRuntime` 의 시퀀스 정본. `bootApp`(서버)·`mega worker`/
+ * `mega scheduler`(CLI 호스트)가 같은 순서를 공유한다(install < build — config-driven driver 제약,
+ * 모듈 상단 주석). state 입력 = { projectRoot, ping, logger }, 산출 = { global, apps, host, ctx, wsHub }.
+ * @type {BootStep[]}
+ */
+const PREPARE_STEPS = [
+  {
+    name: 'config',
+    run: async (st) => {
+      // 1~3단계: config 로드 + 검증.
+      const { global, apps } = await loadAndValidateConfig(st.projectRoot)
+      st.global = global
+      st.apps = apps
+      st.logger?.debug?.({ apps: apps.map((/** @type {any} */ a) => a.name) }, 'boot.config loaded')
+    },
+  },
+  {
+    name: 'plugins',
+    needs: ['global'],
+    run: async (st) => {
+      // 4·5단계: 플러그인 로딩 + install — **어댑터 빌드보다 먼저**(config-driven driver, 상단 주석 참조).
+      const host = new MegaPluginHost({ logger: st.logger })
+      await loadPlugins(/** @type {any} */ (st.global).plugins, host, { projectRoot: st.projectRoot, logger: st.logger })
+      st.host = host
+      st.logger?.debug?.({ plugins: host.loadedPlugins.map((p) => p.name) }, 'boot.plugins installed')
+    },
+  },
+  {
+    name: 'adapters',
+    needs: ['global', 'host'],
+    run: async (st) => {
+      // 어댑터 인스턴스화 + connect (MegaApp 생성보다 먼저 — shutdown 'adapters' stage, adapter-manager 주석).
+      buildFromGlobalConfig(st.global)
+      await connectAll({ logger: st.logger, ping: st.ping })
+      st.logger?.debug?.('boot.adapters connected')
+    },
+  },
+  {
+    name: 'health-auto-checks',
+    needs: ['global'],
+    run: (st) => {
+      // readiness 자동 체크 — 공유 어댑터의 healthCheck 를 MegaHealth 에 등록한다(`health.autoChecks:false`
+      // 옵트아웃, ADR-189). 부팅 후 어댑터가 죽으면 /health/ready 가 503 으로 떨어져 LB/probe 가 트래픽을
+      // 회수한다. 같은 이름 재등록은 덮어쓰기라 멱등.
+      if (/** @type {any} */ (st.global).health?.autoChecks !== false) {
+        const registered = registerAdapterHealthChecks()
+        if (registered.length > 0) st.logger?.debug?.({ checks: registered }, 'boot.health autoChecks registered')
+      }
+    },
+  },
+  {
+    name: 'metrics',
+    needs: ['global'],
+    run: (st) => {
+      // 메트릭 SDK 옵트인 (ADR-072/131) — global `health.exposeMetrics:true` 면 MegaMetrics 초기화
+      // + 어댑터 onCallEnd 일괄 구독(connect 직후 — 모든 공유 어댑터 호출이 mega_adapter_* 메트릭으로 집계).
+      // 옵트인 OFF 면 init 미호출 → 모든 record* 가 0 비용. /metrics 라우트는 MegaApp 이 같은 config 로 등록.
+      const healthCfg = /** @type {any} */ (st.global).health
+      if (healthCfg && healthCfg.exposeMetrics === true && !MegaMetrics.isEnabled()) {
+        MegaMetrics.init({
+          serviceName: healthCfg.serviceName ?? /** @type {any} */ (st.global).server?.serviceName ?? process.env.MEGA_OTEL_SERVICE_NAME ?? 'mega-framework',
+          version: /** @type {any} */ (st.global).server?.version,
+          environment: process.env.NODE_ENV,
+        })
+        const subscribed = MegaMetrics.attachToManager({ entries: adapterEntries })
+        // 'telemetry' stage — 어댑터 disconnect 메트릭까지 기록된 뒤 SDK 를 내린다.
+        MegaShutdown.register('mega-metrics', async () => {
+          await MegaMetrics.shutdown()
+        }, { stage: 'telemetry' })
+        st.logger?.debug?.({ subscribed }, 'boot.metrics enabled')
+      }
+    },
+  },
+  {
+    name: 'tracing',
+    run: (st) => {
+      // 트레이싱 SDK 옵트인 (ADR-104/114/126/163) — `MEGA_OTEL_ENABLED=true` env 면 MegaTracing 초기화 + 어댑터
+      // onCallEnd 일괄 구독(자동 span, ADR-114). 메트릭(위)과 대칭 — `fromEnv` 가 env 게이트(미설정/false=no-op,
+      // 0 비용)한다. 미옵트인이면 mega-app 의 HTTP/WS 루트 span·`ctx.tracer.span` 이 모두 no-op. **부팅에서 한 번
+      // 켜야 프로덕션 분산 트레이싱이 동작한다** — 이전엔 boot 가 `MegaTracing.fromEnv()` 를 호출하지 않아(메트릭만
+      // 배선) 프로덕션에서 트레이싱이 미작동했다(ADR-163 에서 boot 배선 추가). 재진입 방지로 isEnabled 가드.
+      if (!MegaTracing.isEnabled() && MegaTracing.fromEnv() === true) {
+        const tracedAdapters = MegaTracing.attachToManager({ entries: adapterEntries })
+        // 'telemetry' stage — 어댑터 disconnect span 까지 export 된 뒤 SDK 를 내린다(이전 LIFO 는
+        // 트레이싱이 어댑터보다 먼저 내려가 disconnect span 이 유실됐다).
+        MegaShutdown.register('mega-tracing', async () => {
+          await MegaTracing.shutdown()
+        }, { stage: 'telemetry' })
+        st.logger?.debug?.({ subscribed: tracedAdapters }, 'boot.tracing enabled')
+      }
+    },
+  },
+  {
+    name: 'workers',
+    needs: ['global', 'host'],
+    run: async (st) => {
+      // CPU 워커 풀(ADR-124) — 등록 소스 = `config.workers`(정적) + 플러그인 `host.listWorkers()`(동적,
+      // ADR-134). jobs/schedules 듀얼 소스(`collectRegistrations`, ADR-123)와 동형이다. `buildWorkers` 가
+      // `static name` 중복을 부팅 시 fail-fast 한다. 어댑터 connect **뒤** 'workers' stage 에 등록되므로
+      // 종료 시 워커가 어댑터보다 먼저 정리된다(워커가 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
+      const workerClasses = [...(/** @type {any} */ (st.global).workers ?? []), ...st.host.listWorkers()]
+      buildWorkers({ workers: /** @type {any} */ (workerClasses) }, { projectRoot: st.projectRoot })
+      await startWorkers({ logger: st.logger })
+      st.logger?.debug?.({ workers: workerClasses.length }, 'boot.workers started')
+    },
+  },
+  {
+    name: 'ws-hub',
+    needs: ['global'],
+    run: async (st) => {
+      // embedded wsHub (ADR-137) — `global.wsHub.enabled=true` 면 같은 프로세스에 hub 를 띄운다(single-node).
+      // 어댑터 connect 뒤·앱 생성 전에 listen 상태로 만들어 앱이 bridgeHub(localhost)로 붙을 수 있게 한다.
+      // 빈 acceptedTokens 면 MegaWsHub 생성자가 fail-fast throw(ADR-059). SIGTERM 시 drain(4503) 종료.
+      st.wsHub = await startEmbeddedWsHub(/** @type {any} */ (st.global).wsHub, st.logger)
+    },
+  },
+  {
+    name: 'boot-context',
+    needs: ['global'],
+    run: (st) => {
+      st.ctx = buildBootContext(st.global, st.logger)
+    },
+  },
+]
 
-  // embedded wsHub (ADR-137) — `global.wsHub.enabled=true` 면 같은 프로세스에 hub 를 띄운다(single-node).
-  // 어댑터 connect 뒤·앱 생성 전에 listen 상태로 만들어 앱이 bridgeHub(localhost)로 붙을 수 있게 한다.
-  // 빈 acceptedTokens 면 MegaWsHub 생성자가 fail-fast throw(ADR-059). SIGTERM 시 drain(4503) 종료.
-  const wsHub = await startEmbeddedWsHub(/** @type {any} */ (global).wsHub, logger)
+/** prepareRuntime step 이름 시퀀스(정본) — introspection·테스트용. */
+export const PREPARE_STEP_NAMES = Object.freeze(PREPARE_STEPS.map((s) => s.name))
 
-  const ctx = buildBootContext(global, logger)
-  return { global, apps, host, ctx, wsHub }
+/**
+ * 런타임 공통 준비 — {@link PREPARE_STEPS}(config → plugins → adapters → health-auto-checks →
+ * metrics → tracing → workers → ws-hub → boot-context)를 {@link runBootSteps} 로 실행한다.
+ * `bootApp`(서버)·`mega worker`/`mega scheduler`(CLI 호스트)가 **같은 순서**를 공유한다.
+ *
+ * @param {string} projectRoot
+ * @param {{ ping?: boolean, logger?: { debug?: Function, info?: Function, warn?: Function } }} [opts]
+ * @returns {Promise<{ global: Object, apps: Array<{ name: string, config: Object }>, host: MegaPluginHost, ctx: BootContext, wsHub: (MegaWsHub | null) }>}
+ */
+export async function prepareRuntime(projectRoot, { ping = false, logger } = {}) {
+  /** @type {Record<string, any>} */
+  const st = { projectRoot, ping, logger }
+  await runBootSteps(PREPARE_STEPS, st, logger)
+  return { global: st.global, apps: st.apps, host: st.host, ctx: st.ctx, wsHub: st.wsHub }
 }
 
 /**
@@ -197,15 +337,27 @@ export async function prepareRuntime(projectRoot, { ping = false, logger } = {})
  *     trustedProxies(목록)가 있으면 그것을, 없으면 trustProxy(boolean/number/string)를 그대로 넘긴다.
  *   - timeouts.requestMs → Fastify `requestTimeout`(요청 수신 제한, slow-loris 보호).
  *   - keepAliveMs       → Fastify `keepAliveTimeout`(keep-alive 소켓 idle 제한, ALB 정합).
+ *
+ * 프로덕션(`NODE_ENV==='production'`)에서 trustProxy/trustedProxies 미설정이면 **부팅 warn 1회**(ADR-186).
+ * 프록시/LB 뒤에서 미설정 시 `req.protocol`/`req.ip` 가 프록시 기준으로 잡혀 secure 쿠키 누락·rate-limit
+ * 키 왜곡·CSRF Origin 오판으로 번진다 — 직접 listen 배포면 무시해도 되는 안내성 경고다.
+ *
  * @param {any} server - `global.server` config(없으면 빈 객체).
+ * @param {{ logger?: { warn?: Function }, env?: Record<string, string|undefined> }} [opts] - warn 출력용
+ *   logger 와 환경(테스트 주입용, 기본 `process.env`).
  * @returns {{ trustProxy?: any, requestTimeout?: number, keepAliveTimeout?: number }}
  */
-export function serverFastifyOptions(server) {
+export function serverFastifyOptions(server, { logger, env = process.env } = {}) {
   const s = server ?? {}
   /** @type {any} */
   const out = {}
   const trust = s.trustedProxies !== undefined ? s.trustedProxies : s.trustProxy
   if (trust !== undefined) out.trustProxy = trust
+  else if (env.NODE_ENV === 'production') {
+    logger?.warn?.(
+      'server.trustProxy/trustedProxies not set in production — if this app runs behind a proxy/LB, req.protocol/req.ip will reflect the proxy (secure cookies, rate-limit keys and CSRF origin checks depend on them). Set server.trustProxy (ADR-181/186) or ignore if listening directly.',
+    )
+  }
   if (s.timeouts && s.timeouts.requestMs !== undefined) out.requestTimeout = s.timeouts.requestMs
   if (s.keepAliveMs !== undefined) out.keepAliveTimeout = s.keepAliveMs
   return out
@@ -229,19 +381,245 @@ async function startEmbeddedWsHub(cfg, logger) {
     logger,
   })
   const addr = await hub.start({ port: cfg.port, host: cfg.host })
-  MegaShutdown.register('mega-ws-hub-embedded', async () => hub.stop({ drain: true }))
+  // 'workers' stage — 앱(bridge) 정리 뒤·어댑터 disconnect 앞에 hub 를 drain 종료한다.
+  MegaShutdown.register('mega-ws-hub-embedded', async () => hub.stop({ drain: true }), { stage: 'workers' })
   logger?.debug?.({ host: addr.host, port: addr.port, hubId: hub.hubId }, 'boot.wsHub embedded started')
   return hub
 }
 
 /**
- * 프로젝트를 부팅한다 — config→어댑터→플러그인→앱→listen 을 §14 순서로 엮는다.
+ * 부트 step 들 — `bootApp` 의 시퀀스 정본(02-architecture §14 를 declarative 로 코드화).
+ * state 입력 = { projectRoot, ping, logger, listen, port, listenHost } + PREPARE 산출물.
+ * 전 step `onFail: 'abort'`(기본) — 어느 단계든 실패하면 throw 하고, 호출자(bin/mega.js M-1)가
+ * `MegaShutdown.now` 로 이미 등록된 hook(어댑터 disconnect 등)을 실행해 정리한다.
+ * @type {BootStep[]}
+ */
+const BOOT_STEPS = [
+  {
+    name: 'runtime',
+    run: async (st) => {
+      // 공통 토대(PREPARE_STEPS) — config → plugins → adapters → … → boot-context.
+      const prepared = await prepareRuntime(st.projectRoot, { ping: st.ping, logger: st.logger })
+      Object.assign(st, prepared)
+    },
+  },
+  {
+    name: 'before-boot-hook',
+    needs: ['host', 'ctx'],
+    run: async (st) => {
+      // beforeBoot hook(부팅 직전, fail-fast).
+      await st.host.runLifecycle('beforeBoot', st.ctx)
+    },
+  },
+  {
+    name: 'logger',
+    needs: ['global'],
+    run: (st) => {
+      // pino 로거(ADR-023/141) — global.logger 로 인스턴스를 한 번 만들어 모든 앱이 공유한다(worker thread·
+      // 파일 핸들 1벌). 비활성(logger 미설정/sinks 없음)이면 null → 앱은 logger:false(무로그). graceful shutdown
+      // 시 flush(버퍼·worker transport drain)는 'logs' stage — 종료 시퀀스의 마지막이라 어댑터 disconnect 등
+      // 종료 과정 자체의 로그까지 flush 된다(07-sequence §6 "로거는 항상 마지막").
+      const appLogger = buildLogger(/** @type {any} */ (st.global).logger)
+      st.appLogger = appLogger ?? null
+      if (appLogger) {
+        // 전역 에러 핸들러(unhandledRejection/uncaughtException, ADR-178)가 fatal 로그에 쓸 공유 로거를 주입한다.
+        // process 레벨 핸들러는 이 DI 그래프 밖이라 MegaShutdown 모듈 스코프로 넘긴다(globalThis 오염 회피).
+        MegaShutdown.setLogger(appLogger)
+        MegaShutdown.register('mega-logger', async () => {
+          await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
+        }, { stage: 'logs' })
+      }
+    },
+  },
+  {
+    name: 'server',
+    needs: ['global'],
+    run: (st) => {
+      // listen 포트·호스트 해석 — CLI 인자(`--port`/`--host`) 우선, 없으면 정본 server config
+      // (`global.server.port`/`host`, 04-data-models §183: port 기본 3000·host 기본 '0.0.0.0').
+      // boot 가 config→listen 의 유일한 배선 지점이라 여기서 읽지 않으면 `server.port`/`PORT` 가 죽는다.
+      // 최종 폴백(3000/'0.0.0.0')은 MegaServer.listen 이 가진다(여기선 undefined 면 그대로 위임).
+      const serverCfg = /** @type {any} */ (st.global).server ?? {}
+      st.resolvedPort = st.port ?? serverCfg.port
+      st.resolvedHost = st.listenHost ?? serverCfg.host
+      // server 운영 옵션 → Fastify 인스턴스 옵션(ADR-181). 앱 루프 밖에서 1회 — prod trustProxy 미설정
+      // warn(ADR-186)이 앱 수만큼 반복되지 않게 한다. 모든 앱에 동일 주입(Global-only).
+      st.fastifyOptions = serverFastifyOptions(serverCfg, { logger: st.appLogger ?? st.logger })
+      // logger 주입 — 미매핑 host 404·upgrade 소켓 에러 같은 vhost 레벨 이벤트가 pino 로 남는다.
+      st.server = new MegaServer({ port: st.resolvedPort, host: st.resolvedHost, logger: st.appLogger ?? st.logger })
+    },
+  },
+  {
+    name: 'apps',
+    needs: ['global', 'apps', 'host', 'server'],
+    run: async (st) => {
+      // 각 앱 Fastify 인스턴스 생성 + 라우트 자동 로딩 + 플러그인 주입 + vhost mount.
+      /** @type {MegaApp[]} */
+      const megaApps = []
+      for (const { name, config } of st.apps) {
+        const app = new MegaApp({
+          ...config,
+          name, // config.name(검증됨) 위에 폴더명을 확정(둘은 동일, ADR-067).
+          logger: st.appLogger ?? false, // pino 로거 주입(공유 인스턴스, ADR-141).
+          // ASP masterSecret 은 global 스코프(시크릿, scope-registry)라 앱 asp 옵트인에 합성한다(ADR-127).
+          // 앱 config.asp 가 http.enabledPaths/websocket 등 옵트인 범위를, global.asp 가 masterSecret 을 제공.
+          asp: composeAspConfig(/** @type {any} */ (st.global).asp, /** @type {any} */ (config).asp),
+          // 세션 쿠키 HMAC 시크릿은 global 스코프(server.sessionSecret, scope-registry)라 앱에 주입한다
+          // (ASP masterSecret 합성과 동일 패턴, ADR-129). 앱 session.secret 명시 시 그쪽이 우선(MegaApp).
+          sessionSecret: /** @type {any} */ (st.global).server?.sessionSecret,
+          // 운영 관측성 config 는 Global-only(ADR-072/131) — global `health` 블록을 모든 앱에 주입한다(/metrics
+          // 라우트 등록 + 보안 면제 + IP allowList). sessionSecret 주입과 동일 패턴.
+          health: /** @type {any} */ (st.global).health,
+          // server 운영 옵션(trustProxy/requestTimeout/keepAliveTimeout) → Fastify 인스턴스 옵션(ADR-181).
+          // Global-only 라 모든 앱에 동일 주입. MegaApp 이 Fastify({ ...fastifyOptions }) 로 전달.
+          fastifyOptions: st.fastifyOptions,
+          plugins: st.host.fastifyPlugins,
+          globalMiddlewares: st.host.globalMiddlewares,
+        })
+        // OpenAPI 옵트인 시 배리어(ADR-140): @fastify/swagger 의 onRoute 수집 훅은 plugin 로드 후 설치되므로,
+        // 라우트 동기 등록 전에 swagger 를 먼저 로드시켜야 라우트가 명세에 수집된다. `after()` 가 생성자에서 큐된
+        // 등록(swagger 포함)을 flush 한다. 비-openapi 앱은 timing 변경 없이 건너뜀(_openapiPath=null).
+        if (app._openapiPath) await app.fastify.after()
+        // 서비스 자동 로딩(ADR-148) — apps/<name>/services/*.js 를 name→Class 레지스트리로 만들어 앱에 주입한다.
+        // 라우트 등록 전에 채워 두면, 요청 ctx 의 ctx.services.<name> lazy DI 가 첫 요청부터 동작한다.
+        const servicesDir = join(st.projectRoot, 'apps', name, 'services')
+        const serviceRegistry = await loadServices({ servicesDir, appName: name })
+        app.setServiceRegistry(serviceRegistry)
+        st.logger?.debug?.({ app: name, services: serviceRegistry.size }, 'boot.services loaded')
+
+        const routesDir = join(st.projectRoot, 'apps', name, 'routes')
+        const { filesLoaded } = await loadRoutes({ fastify: app.fastify, appName: name, routesDir, app })
+        st.logger?.debug?.({ app: name, filesLoaded }, 'boot.routes loaded')
+        st.server.mount(app)
+        megaApps.push(app)
+      }
+      st.megaApps = megaApps
+    },
+  },
+  {
+    name: 'cluster-transport',
+    needs: ['global', 'apps', 'megaApps'],
+    run: async (st) => {
+      // 클러스터 전송 자동배선 (ADR-176) — 앱당 **하나**(상호배타, config-validator 가 충돌 fail-fast). config 로 선택:
+      //   - app.config `bridgeHub` → **WS Hub**(`app.connectHub`, 평문 12-타입). `mega ws-hub` 서버에 자동 연결.
+      //   - global `wsCluster.bus`(NATS) → **MegaWsCluster**(NATS pub/sub broadcast + roster 동기화).
+      // 둘 다 개발자가 connectHub 같은 코드를 쓰지 않고 config 만으로 동작한다(ADR-176 이 ADR-137 의 자동배선
+      // 거부를 **명시 config 가 있을 때만** 번복 — 설정이 곧 의도라 "추측 배선" 아님). megaApps[i] 와 apps[i] 동순서.
+      const wsClusterCfg = /** @type {any} */ (st.global).wsCluster
+      const wsClusterBus = wsClusterCfg?.bus ? getAdapter('bus', wsClusterCfg.bus) : null
+      for (let i = 0; i < st.megaApps.length; i++) {
+        const app = st.megaApps[i]
+        const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal.
+        const bridgeHub = /** @type {any} */ (st.apps[i].config).bridgeHub
+        if (bridgeHub?.url) {
+          // ⚠️ 클러스터 워커마다 별개 브릿지라 bridgeId 가 **워커별로 유일**해야 한다(허브 sessionId global-unique
+          // 계약). 모든 워커가 같은 bridgeId 면 bridge-subscriber sessionId(`bridge:<id>#<ch>`, ws-presence
+          // _resyncPresence)가 충돌해 허브가 계속 재할당(thrashing)한다(L-3). 설정 bridgeId 를 베이스로 워커
+          // 식별자(cluster.worker.id, 단일 프로세스면 pid)를 붙여 유일화한다. instanceId 도 동일하게 유일화
+          // (hub-link 는 instanceId 미지정 시 bridgeId 로 폴백하므로).
+          const baseId = bridgeHub.bridgeId ?? app.name
+          const workerTag = nodeCluster.worker?.id ?? process.pid
+          const uniqueBridgeId = `${baseId}-w${workerTag}`
+          // WS Hub 자동연결(ADR-065/176). connectHub 가 hub link 를 세워 app.broadcast/joinSession 의 hub 경로를
+          // 활성화한다(shutdown hook 도 connectHub 가 등록). 허브 다운이어도 boot 를 막지 않는다 — 초기 연결
+          // 실패는 warn 하고(retry 설정 시 백그라운드 재연결, ADR-098) 앱은 계속 뜬다(로컬 전달은 동작).
+          try {
+            await app.connectHub({ ...bridgeHub, bridgeId: uniqueBridgeId, instanceId: bridgeHub.instanceId ?? uniqueBridgeId })
+            st.logger?.debug?.({ app: app.name, url: bridgeHub.url, bridgeId: uniqueBridgeId }, 'boot.bridgeHub connected (ADR-176)')
+          } catch (err) {
+            st.logger?.warn?.({ err, app: app.name, url: bridgeHub.url }, 'boot.bridgeHub initial connect failed (retry if configured)')
+          }
+          // redis roster 자동배선(ADR-177) — `bridgeHub.roster.driver==='redis'` 면 **채널별 접속자 목록**을 redis HASH 로
+          // 관리한다(broadcast 와 별개 — 멀티 허브에서도 정합, 신규/재연결 브릿지가 즉시 전체 명단). 캐시 어댑터의 raw
+          // ioredis(`.native`)를 쓰고, heartbeat 로 crash 워커 stale 정리. hub 연결 성패와 무관(roster 는 redis 독립).
+          const rosterCfg = /** @type {any} */ (bridgeHub).roster
+          if (rosterCfg?.driver === 'redis') {
+            const cacheAdapter = /** @type {any} */ (getAdapter('cache', rosterCfg.cache))
+            const redis = cacheAdapter?.native
+            if (!redis || typeof redis.hset !== 'function') {
+              st.logger?.warn?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster: cache adapter has no native redis — roster disabled')
+            } else {
+              const roster = new MegaWsRedisRoster({ redis, getLocalMembers: () => a.localRosterMembers(), ttlMs: rosterCfg.ttlMs, keyPrefix: rosterCfg.keyPrefix, logger: st.logger })
+              roster.startHeartbeat()
+              a.setWsRoster(roster)
+              MegaShutdown.register(`mega-wsroster:${app.name}`, () => roster.stop())
+              st.logger?.debug?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster connected (ADR-177, redis)')
+            }
+          }
+        } else if (wsClusterBus) {
+          const cluster = new MegaWsCluster({
+            bus: /** @type {any} */ (wsClusterBus),
+            appName: app.name,
+            deliverBroadcast: (/** @type {any} */ p) => a._deliverBroadcast(p),
+            deliverDirect: (/** @type {any} */ p) => a._deliverDirect(p),
+            subjectPrefix: wsClusterCfg.subjectPrefix,
+            roster: wsClusterCfg.roster,
+            logger: /** @type {any} */ (app.fastify.log),
+          })
+          await cluster.start()
+          app.setWsCluster(cluster)
+          // 'app' stage(기본) — 어댑터 disconnect 보다 먼저 정리(graceful LEAVE 가 NATS 끊기기 전에 나가게).
+          MegaShutdown.register(`mega-ws-cluster:${app.name}`, async () => cluster.stop())
+        }
+      }
+      if (wsClusterBus) {
+        st.logger?.debug?.({ bus: wsClusterCfg.bus, roster: wsClusterCfg.roster?.driver ?? 'none' }, 'boot.wsCluster wired (ADR-176)')
+      }
+    },
+  },
+  {
+    name: 'listen',
+    needs: ['server'],
+    run: async (st) => {
+      // HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).
+      if (!st.listen) return
+      await st.server.listen({ port: st.resolvedPort, host: st.resolvedHost })
+      st.logger?.info?.({ hosts: st.server.hosts }, 'boot.listening')
+    },
+  },
+  {
+    name: 'after-boot-hook',
+    needs: ['host', 'ctx'],
+    run: async (st) => {
+      // afterBoot hook(부팅 완료).
+      await st.host.runLifecycle('afterBoot', st.ctx)
+    },
+  },
+  {
+    name: 'shutdown-bridge',
+    needs: ['host', 'ctx'],
+    run: (st) => {
+      // beforeShutdown hook 을 graceful 종료 경로에 브리지(per-hook catch — graceful 중 한 hook 실패가
+      // 나머지 정리를 막으면 안 됨, ADR-122). 'app' stage(기본)라 어댑터 disconnect 보다 먼저 실행된다
+      // (플러그인이 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
+      const shutdownHooks = st.host.lifecycleHooks('beforeShutdown')
+      if (shutdownHooks.length > 0) {
+        MegaShutdown.register('plugin:beforeShutdown', async () => {
+          for (const fn of shutdownHooks) {
+            try {
+              await fn(st.ctx)
+            } catch (err) {
+              st.logger?.warn?.({ err }, 'plugin beforeShutdown hook failed (continuing shutdown)')
+            }
+          }
+        })
+      }
+    },
+  },
+]
+
+/** bootApp step 이름 시퀀스(정본) — introspection·테스트용. */
+export const BOOT_STEP_NAMES = Object.freeze(BOOT_STEPS.map((s) => s.name))
+
+/**
+ * 프로젝트를 부팅한다 — {@link BOOT_STEPS}(runtime → before-boot-hook → logger → server → apps →
+ * cluster-transport → listen → after-boot-hook → shutdown-bridge)를 {@link runBootSteps} 로 실행한다.
  *
- * 어느 단계든 실패하면 그대로 throw(fail-fast). 어댑터 connect 실패는 매니저가 LIFO cleanup 하고,
- * 그 외 단계 실패(예: server.listen EADDRINUSE, beforeBoot hook throw)는 어댑터가 이미 connect 돼
- * `'adapters:disconnect'` MegaShutdown hook 이 등록된 상태라, 호출자가 `MegaShutdown.now` 로 그 hook 을
- * LIFO 실행해 정리해야 한다 — `bin/mega.js` 의 catch 가 이 정리 경로를 배선한다(M-1). 그러지 않으면
- * 연결된 어댑터가 이벤트루프를 살려 프로세스가 hang 한다.
+ * 어느 step 이든 실패하면 그대로 throw(fail-fast, 전 step onFail='abort'). 어댑터 connect 실패는
+ * 매니저가 LIFO cleanup 하고, 그 외 단계 실패(예: server.listen EADDRINUSE, beforeBoot hook throw)는
+ * 어댑터가 이미 connect 돼 `'adapters:disconnect'` MegaShutdown hook 이 등록된 상태라, 호출자가
+ * `MegaShutdown.now` 로 그 hook 을 실행해 정리해야 한다 — `bin/mega.js` 의 catch 가 이 정리 경로를
+ * 배선한다(M-1). 그러지 않으면 연결된 어댑터가 이벤트루프를 살려 프로세스가 hang 한다.
  *
  * @param {string} projectRoot - 프로젝트 루트 절대 경로(mega.config.js 가 있는 곳).
  * @param {Object} [opts]
@@ -254,168 +632,9 @@ async function startEmbeddedWsHub(cfg, logger) {
  */
 export async function bootApp(projectRoot, { listen = true, port, host: listenHost, ping = false, logger } = {}) {
   logger?.debug?.({ projectRoot }, 'boot.start')
-
-  // 1~5단계 + 어댑터 connect 공통 토대(config → 플러그인 install → 어댑터 build → connect → boot ctx).
-  const { global, apps, host, ctx, wsHub } = await prepareRuntime(projectRoot, { ping, logger })
-
-  // 7단계: beforeBoot hook(부팅 직전, fail-fast).
-  await host.runLifecycle('beforeBoot', ctx)
-
-  // pino 로거(ADR-023/141) — global.logger 로 인스턴스를 한 번 만들어 모든 앱이 공유한다(worker thread·
-  // 파일 핸들 1벌). 비활성(logger 미설정/sinks 없음)이면 null → 앱은 logger:false(무로그). graceful shutdown
-  // 시 flush(버퍼·worker transport drain). MegaShutdown LIFO 라 어댑터/앱보다 나중 등록 = 가장 먼저 정리되지
-  // 않게(로그가 종료 과정 끝까지 살아 있도록) — 마지막 flush 단계(07-sequence §6).
-  const appLogger = buildLogger(/** @type {any} */ (global).logger)
-  if (appLogger) {
-    // 전역 에러 핸들러(unhandledRejection/uncaughtException, ADR-178)가 fatal 로그에 쓸 공유 로거를 주입한다.
-    // process 레벨 핸들러는 이 DI 그래프 밖이라 MegaShutdown 모듈 스코프로 넘긴다(globalThis 오염 회피).
-    MegaShutdown.setLogger(appLogger)
-    MegaShutdown.register('mega-logger', async () => {
-      await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
-    })
-  }
-
-  // listen 포트·호스트 해석 — CLI 인자(`--port`/`--host`) 우선, 없으면 정본 server config
-  // (`global.server.port`/`host`, 04-data-models §183: port 기본 3000·host 기본 '0.0.0.0').
-  // boot 가 config→listen 의 유일한 배선 지점이라 여기서 읽지 않으면 `server.port`/`PORT` 가 죽는다.
-  // 최종 폴백(3000/'0.0.0.0')은 MegaServer.listen 이 가진다(여기선 undefined 면 그대로 위임).
-  const serverCfg = /** @type {any} */ (global).server ?? {}
-  const resolvedPort = port ?? serverCfg.port
-  const resolvedHost = listenHost ?? serverCfg.host
-
-  // 6단계: 각 앱 Fastify 인스턴스 생성 + 라우트 자동 로딩 + 플러그인 주입 + vhost mount.
-  const server = new MegaServer({ port: resolvedPort, host: resolvedHost })
-  /** @type {MegaApp[]} */
-  const megaApps = []
-  for (const { name, config } of apps) {
-    const app = new MegaApp({
-      ...config,
-      name, // config.name(검증됨) 위에 폴더명을 확정(둘은 동일, ADR-067).
-      logger: appLogger ?? false, // pino 로거 주입(공유 인스턴스, ADR-141).
-      // ASP masterSecret 은 global 스코프(시크릿, scope-registry)라 앱 asp 옵트인에 합성한다(ADR-127).
-      // 앱 config.asp 가 http.enabledPaths/websocket 등 옵트인 범위를, global.asp 가 masterSecret 을 제공.
-      asp: composeAspConfig(/** @type {any} */ (global).asp, /** @type {any} */ (config).asp),
-      // 세션 쿠키 HMAC 시크릿은 global 스코프(server.sessionSecret, scope-registry)라 앱에 주입한다
-      // (ASP masterSecret 합성과 동일 패턴, ADR-129). 앱 session.secret 명시 시 그쪽이 우선(MegaApp).
-      sessionSecret: /** @type {any} */ (global).server?.sessionSecret,
-      // 운영 관측성 config 는 Global-only(ADR-072/131) — global `health` 블록을 모든 앱에 주입한다(/metrics
-      // 라우트 등록 + 보안 면제 + IP allowList). sessionSecret 주입과 동일 패턴.
-      health: /** @type {any} */ (global).health,
-      // server 운영 옵션(trustProxy/requestTimeout/keepAliveTimeout) → Fastify 인스턴스 옵션(ADR-181).
-      // Global-only 라 모든 앱에 동일 주입. MegaApp 이 Fastify({ ...fastifyOptions }) 로 전달.
-      fastifyOptions: serverFastifyOptions(serverCfg),
-      plugins: host.fastifyPlugins,
-      globalMiddlewares: host.globalMiddlewares,
-    })
-    // OpenAPI 옵트인 시 배리어(ADR-140): @fastify/swagger 의 onRoute 수집 훅은 plugin 로드 후 설치되므로,
-    // 라우트 동기 등록 전에 swagger 를 먼저 로드시켜야 라우트가 명세에 수집된다. `after()` 가 생성자에서 큐된
-    // 등록(swagger 포함)을 flush 한다. 비-openapi 앱은 timing 변경 없이 건너뜀(_openapiPath=null).
-    if (app._openapiPath) await app.fastify.after()
-    // 서비스 자동 로딩(ADR-148) — apps/<name>/services/*.js 를 name→Class 레지스트리로 만들어 앱에 주입한다.
-    // 라우트 등록 전에 채워 두면, 요청 ctx 의 ctx.services.<name> lazy DI 가 첫 요청부터 동작한다.
-    const servicesDir = join(projectRoot, 'apps', name, 'services')
-    const serviceRegistry = await loadServices({ servicesDir, appName: name })
-    app.setServiceRegistry(serviceRegistry)
-    logger?.debug?.({ app: name, services: serviceRegistry.size }, 'boot.services loaded')
-
-    const routesDir = join(projectRoot, 'apps', name, 'routes')
-    const { filesLoaded } = await loadRoutes({ fastify: app.fastify, appName: name, routesDir, app })
-    logger?.debug?.({ app: name, filesLoaded }, 'boot.routes loaded')
-    server.mount(app)
-    megaApps.push(app)
-  }
-
-  // 클러스터 전송 자동배선 (ADR-176) — 앱당 **하나**(상호배타, config-validator 가 충돌 fail-fast). config 로 선택:
-  //   - app.config `bridgeHub` → **WS Hub**(`app.connectHub`, 평문 12-타입). `mega ws-hub` 서버에 자동 연결.
-  //   - global `wsCluster.bus`(NATS) → **MegaWsCluster**(NATS pub/sub broadcast + roster 동기화).
-  // 둘 다 개발자가 connectHub 같은 코드를 쓰지 않고 config 만으로 동작한다(ADR-176 이 ADR-137 의 자동배선
-  // 거부를 **명시 config 가 있을 때만** 번복 — 설정이 곧 의도라 "추측 배선" 아님). megaApps[i] 와 apps[i] 동순서.
-  const wsClusterCfg = /** @type {any} */ (global).wsCluster
-  const wsClusterBus = wsClusterCfg?.bus ? getAdapter('bus', wsClusterCfg.bus) : null
-  for (let i = 0; i < megaApps.length; i++) {
-    const app = megaApps[i]
-    const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
-    const bridgeHub = /** @type {any} */ (apps[i].config).bridgeHub
-    if (bridgeHub?.url) {
-      // ⚠️ 클러스터 워커마다 별개 브릿지라 bridgeId 가 **워커별로 유일**해야 한다(허브 sessionId global-unique
-      // 계약). 모든 워커가 같은 bridgeId 면 bridge-subscriber sessionId(`bridge:<id>#<ch>`, mega-app
-      // _resyncPresence)가 충돌해 허브가 계속 재할당(thrashing)한다(L-3). 설정 bridgeId 를 베이스로 워커
-      // 식별자(cluster.worker.id, 단일 프로세스면 pid)를 붙여 유일화한다. instanceId 도 동일하게 유일화
-      // (hub-link 는 instanceId 미지정 시 bridgeId 로 폴백하므로).
-      const baseId = bridgeHub.bridgeId ?? app.name
-      const workerTag = nodeCluster.worker?.id ?? process.pid
-      const uniqueBridgeId = `${baseId}-w${workerTag}`
-      // WS Hub 자동연결(ADR-065/176). connectHub 가 _hubLink 를 세워 app.broadcast/joinSession 의 hub 경로를
-      // 활성화한다(shutdown hook 도 connectHub 가 등록). 허브 다운이어도 boot 를 막지 않는다 — 초기 연결
-      // 실패는 warn 하고(retry 설정 시 백그라운드 재연결, ADR-098) 앱은 계속 뜬다(로컬 전달은 동작).
-      try {
-        await app.connectHub({ ...bridgeHub, bridgeId: uniqueBridgeId, instanceId: bridgeHub.instanceId ?? uniqueBridgeId })
-        logger?.debug?.({ app: app.name, url: bridgeHub.url, bridgeId: uniqueBridgeId }, 'boot.bridgeHub connected (ADR-176)')
-      } catch (err) {
-        logger?.warn?.({ err, app: app.name, url: bridgeHub.url }, 'boot.bridgeHub initial connect failed (retry if configured)')
-      }
-      // redis roster 자동배선(ADR-177) — `bridgeHub.roster.driver==='redis'` 면 **채널별 접속자 목록**을 redis HASH 로
-      // 관리한다(broadcast 와 별개 — 멀티 허브에서도 정합, 신규/재연결 브릿지가 즉시 전체 명단). 캐시 어댑터의 raw
-      // ioredis(`.native`)를 쓰고, heartbeat 로 crash 워커 stale 정리. hub 연결 성패와 무관(roster 는 redis 독립).
-      const rosterCfg = /** @type {any} */ (bridgeHub).roster
-      if (rosterCfg?.driver === 'redis') {
-        const cacheAdapter = /** @type {any} */ (getAdapter('cache', rosterCfg.cache))
-        const redis = cacheAdapter?.native
-        if (!redis || typeof redis.hset !== 'function') {
-          logger?.warn?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster: cache adapter has no native redis — roster disabled')
-        } else {
-          const roster = new MegaWsRedisRoster({ redis, getLocalMembers: () => a.localRosterMembers(), ttlMs: rosterCfg.ttlMs, keyPrefix: rosterCfg.keyPrefix, logger })
-          roster.startHeartbeat()
-          a.setWsRoster(roster)
-          MegaShutdown.register(`mega-wsroster:${app.name}`, () => roster.stop())
-          logger?.debug?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster connected (ADR-177, redis)')
-        }
-      }
-    } else if (wsClusterBus) {
-      const cluster = new MegaWsCluster({
-        bus: /** @type {any} */ (wsClusterBus),
-        appName: app.name,
-        deliverBroadcast: (/** @type {any} */ p) => a._deliverBroadcast(p),
-        deliverDirect: (/** @type {any} */ p) => a._deliverDirect(p),
-        subjectPrefix: wsClusterCfg.subjectPrefix,
-        roster: wsClusterCfg.roster,
-        logger: /** @type {any} */ (app.fastify.log),
-      })
-      await cluster.start()
-      app.setWsCluster(cluster)
-      // MegaShutdown LIFO — 어댑터 disconnect 보다 먼저 정리(graceful LEAVE 가 NATS 끊기기 전에 나가게).
-      MegaShutdown.register(`mega-ws-cluster:${app.name}`, async () => cluster.stop())
-    }
-  }
-  if (wsClusterBus) {
-    logger?.debug?.({ bus: wsClusterCfg.bus, roster: wsClusterCfg.roster?.driver ?? 'none' }, 'boot.wsCluster wired (ADR-176)')
-  }
-
-  // 9단계: HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).
-  if (listen) {
-    await server.listen({ port: resolvedPort, host: resolvedHost })
-    logger?.info?.({ hosts: server.hosts }, 'boot.listening')
-  }
-
-  // 10단계: afterBoot hook(부팅 완료).
-  await host.runLifecycle('afterBoot', ctx)
-
-  // beforeShutdown hook 을 graceful 종료 경로에 브리지(per-hook catch — graceful 중 한 hook 실패가
-  // 나머지 정리를 막으면 안 됨, ADR-122). MegaShutdown LIFO 라 어댑터 hook 보다 나중 등록 =
-  // 어댑터 disconnect 보다 먼저 실행(플러그인이 어댑터를 쓰는 정리를 어댑터 종료 전에 끝냄).
-  const shutdownHooks = host.lifecycleHooks('beforeShutdown')
-  if (shutdownHooks.length > 0) {
-    MegaShutdown.register('plugin:beforeShutdown', async () => {
-      for (const fn of shutdownHooks) {
-        try {
-          await fn(ctx)
-        } catch (err) {
-          logger?.warn?.({ err }, 'plugin beforeShutdown hook failed (continuing shutdown)')
-        }
-      }
-    })
-  }
-
+  /** @type {Record<string, any>} */
+  const st = { projectRoot, ping, logger, listen, port, listenHost }
+  await runBootSteps(BOOT_STEPS, st, logger)
   logger?.debug?.('boot.done')
-  return { server, host, config: global, apps, megaApps, ctx, wsHub, appLogger }
+  return { server: st.server, host: st.host, config: st.global, apps: st.apps, megaApps: st.megaApps, ctx: st.ctx, wsHub: st.wsHub, appLogger: st.appLogger }
 }