mega-framework 0.1.7 → 0.1.9

package/src/cli/index.js

@@ -19,26 +19,20 @@
  *
  * @module cli/index
  */
+// 무거운 런타임 그래프(boot→fastify·OTel·pino·ejs·보안 플러그인, 클러스터, 마이그레이션 러너)는
+// 정적 import 하지 않는다 — `mega help`/`g`/`new` 같은 비부팅 명령이 전체 그래프를 평가해 4배
+// 느려지는 것을 막기 위해, 각 런타임 명령의 action/호스트 함수 내부에서 dynamic import 한다.
+// 모듈 레벨 싱글톤(adapter-manager·MegaShutdown 등)은 dynamic import 도 같은 인스턴스를 본다.
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import os from 'node:os'
 import { spawn as nodeSpawn } from 'node:child_process'
-import { bootApp, prepareRuntime } from '../core/boot.js'
-import { MegaCluster } from '../core/mega-cluster.js'
-import { installPrimaryAggregator, installWorkerResponder } from '../core/cluster-metrics.js'
 import { loadAndValidateConfig } from '../core/config-loader.js'
-import { migrateUp, migrateDown, migrateStatus } from '../core/migration-runner.js'
-import { withMigrationLock } from '../core/migration-lock.js'
-import { runMigrateGenerate } from '../core/migration/generate.js'
 import { buildFromGlobalConfig, connectAll, disconnectAll, get as getAdapter } from '../adapters/adapter-manager.js'
 import { MegaDbAdapter } from '../adapters/mega-db-adapter.js'
 import { MegaConfigError } from '../errors/config-error.js'
 import { MegaPluginHost, loadPlugins } from '../lib/mega-plugin.js'
-import { MegaJobWorker } from '../lib/mega-job-worker.js'
-import { MegaScheduler } from '../lib/mega-schedule.js'
 import { MegaShutdown, DEFAULT_HARD_KILL_MS } from '../lib/mega-shutdown.js'
-import { buildLogger } from '../lib/mega-logger.js'
-import * as MegaMetrics from '../lib/mega-metrics.js'
 import { Command } from 'commander'
 import { registerScaffoldCommands, commanderErrorToExitCode } from './commands/scaffold.js'
 
@@ -240,37 +234,35 @@ export function shouldReexecForWatch(flags, env) {
 }
 
 /**
- * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ * `mega start --watch` supervisor 의 **자식 인자**를 빌드한다 (ADR-220, ADR-182 개정).
  *
- * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - `--watch`/`--watch-ignore`(값 포함)는 부모(supervisor) 전용 — 자식 인자에서 제거한다
+ *   (가드 env 와 이중 안전으로 무한재귀 방지).
  * - **단일 프로세스 강제**(`--cluster 1`) — 멀티워커 watch 카오스 방지(기존 `--cluster` 값은 무시).
- * - watchPaths 가 있으면 `--watch-path=…`(이게 모듈 그래프 watch 를 **대체**하므로 앱 소스·전역설정 경로를
- *   명시해야 한다 — 실측 확인). 없으면 plain `--watch`(모듈 그래프 폴백).
  *
- * @param {Object} o
- * @param {string[]} o.argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
- * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만).
- * @param {string} o.selfPath - mega 진입 스크립트(`process.argv[1]`).
- * @param {string} o.execPath - node 바이너리(`process.execPath`).
- * @returns {{ command: string, args: string[] }}
+ * @param {string[]} argv - 원본 mega argv(예: `['start','--watch','--port','3000']`).
+ * @returns {string[]} 자식 `mega` 인자(예: `['start','--port','3000','--cluster','1']`).
  */
-export function buildWatchCommand({ argv, watchPaths, selfPath, execPath }) {
-  const nodeFlags =
-    Array.isArray(watchPaths) && watchPaths.length > 0 ? watchPaths.map((p) => `--watch-path=${p}`) : ['--watch']
-  /** @type {string[]} mega 인자 — `--watch` 제거 + `--cluster`(값 포함) 제거. */
+export function buildWatchChildArgs(argv) {
+  /** @type {string[]} */
   const megaArgs = []
   for (let i = 0; i < argv.length; i++) {
     const tok = argv[i]
     if (tok === '--watch' || tok.startsWith('--watch=')) continue
-    if (tok === '--cluster') {
+    if (tok === '--watch-ignore') {
       if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) i++ // 값 토큰도 건너뜀.
       continue
     }
+    if (tok.startsWith('--watch-ignore=')) continue
+    if (tok === '--cluster') {
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) i++
+      continue
+    }
     if (tok.startsWith('--cluster=')) continue
     megaArgs.push(tok)
   }
   megaArgs.push('--cluster', '1') // 단일 프로세스 강제.
-  return { command: execPath, args: [...nodeFlags, selfPath, ...megaArgs] }
+  return megaArgs
 }
 
 /**
@@ -338,38 +330,47 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
 
 /**
  * `mega start`/`serve` 본체 — dev watch 재실행 또는 부팅+listen(단일/클러스터).
- * @param {{ port?: string, host?: string, cluster?: string | boolean, watch?: boolean }} opts - commander 옵션.
+ * @param {{ port?: string, host?: string, cluster?: string | boolean, watch?: boolean, watchIgnore?: string }} opts - commander 옵션.
  * @param {{ argv: string[], out: (msg: string) => void, projectRoot: string, logger?: { debug?: Function, info?: Function, warn?: Function }, spawn: Function, selfPath: string }} ctx
  * @returns {Promise<number>} exit code.
  */
 async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath }) {
   {
-    // dev watch (ADR-182) — `--watch` 면 자신을 `node --watch` 로 재실행한다. 부모는 부팅하지 않고 watcher
-    // 자식만 띄운 뒤 그 exit code 를 그대로 반영한다(가드 env 로 무한재귀 방지). 단일 프로세스 강제 +
-    // NODE_ENV 미설정 시 development 기본. 시그널은 자식으로 전달해 Ctrl+C 가 watcher 까지 닿게 한다.
+    // dev watch (ADR-220, ADR-182 개정) — `--watch` 면 자체 supervisor 가 자식(`mega start`)을 띄우고
+    // fs.watch(recursive) + ignore 패턴 + debounce 로 재시작을 조율한다. node 내장 --watch 는 ignore 가
+    // 없어 런타임 산출물(locales saveMissing·업로드·journal)이 재시작 루프를 만들었다. 단일 프로세스
+    // 강제 + NODE_ENV 미설정 시 development 기본 + 가드 env 로 무한재귀 방지는 기존과 동일.
     if (shouldReexecForWatch({ watch: opts.watch === true }, process.env)) {
-      const watchPaths = [join(projectRoot, 'apps'), join(projectRoot, 'mega.config.js')].filter(existsSync)
-      const { command: cmd, args } = buildWatchCommand({ argv, watchPaths, selfPath, execPath: process.execPath })
-      out(`mega: watch mode (single process) — restarting on changes in [${watchPaths.length ? watchPaths.join(', ') : 'module graph'}]`)
-      const child = spawn(cmd, args, {
-        stdio: 'inherit',
-        env: { ...process.env, MEGA_WATCH_REEXEC: '1', NODE_ENV: process.env.NODE_ENV ?? 'development' },
-      })
-      /** @type {NodeJS.Signals[]} */
-      const sigs = ['SIGINT', 'SIGTERM']
-      const forward = (/** @type {NodeJS.Signals} */ sig) => {
-        try {
-          child.kill(sig)
-        } catch {
-          // 자식이 이미 종료 중이면 kill 은 무의미 — 무시(비치명적).
-        }
+      const { mergeWatchIgnore, startWatchSupervisor, defaultWatchPaths } = await import('./watch.js')
+      // config 의 watch.ignore 는 best-effort — dev 루프는 config 가 깨진 동안에도 살아 있어야
+      // 하므로(고치면 재시작) 로드 실패 시 디폴트 ignore 로 진행하고 이유를 알린다.
+      /** @type {{ ignore?: unknown, ignoreDefaults?: unknown }} */
+      let watchConfig = {}
+      try {
+        const { global } = await loadAndValidateConfig(projectRoot)
+        watchConfig = /** @type {any} */ (global).watch ?? {}
+      } catch (e) {
+        out(`mega: watch — mega.config.js 를 읽지 못해 디폴트 ignore 로 감시합니다(${/** @type {any} */ (e).message?.split('\n')[0] ?? e}).`)
+      }
+      const ignore = mergeWatchIgnore(watchConfig, typeof opts.watchIgnore === 'string' ? opts.watchIgnore : undefined)
+      const watchPaths = defaultWatchPaths(projectRoot)
+      const childArgs = buildWatchChildArgs(argv)
+      out(`mega: watch mode (single process) — watching [${watchPaths.join(', ')}], ignore ${ignore.length} patterns`)
+      if (ignore.length === 0) {
+        // 숨은 디폴트가 없으므로(ADR-220) 미설정은 "모든 변경이 재시작" — locales(saveMissing 자동
+        // 기입)·업로드 같은 런타임 쓰기 영역이 있으면 루프가 날 수 있어 가시화한다(P4).
+        out('mega: watch ignore 가 비어 있습니다 — locales/업로드 등 런타임 쓰기 폴더가 있으면 .env 의 WATCH_IGNORE(또는 config watch.ignore) 설정을 권장합니다.')
       }
-      for (const s of sigs) process.on(s, forward)
-      return await new Promise((resolve) => {
-        child.on('exit', (/** @type {number|null} */ code) => {
-          for (const s of sigs) process.removeListener(s, forward)
-          resolve(typeof code === 'number' ? code : 0)
-        })
+      return await startWatchSupervisor({
+        projectRoot,
+        watchPaths,
+        ignore,
+        out,
+        spawnChild: () =>
+          spawn(process.execPath, [selfPath, ...childArgs], {
+            stdio: 'inherit',
+            env: { ...process.env, MEGA_WATCH_REEXEC: '1', NODE_ENV: process.env.NODE_ENV ?? 'development' },
+          }),
       })
     }
 
@@ -394,6 +395,15 @@ async function runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath
       else out(`mega: ${msg}`)
     }
 
+    // 런타임 그래프 lazy 로드 — 부팅 명령에서만 프레임워크 전체를 지불한다(모듈 상단 주석).
+    const [{ bootApp }, { MegaCluster }, { installPrimaryAggregator, installWorkerResponder }, { buildLogger }] =
+      await Promise.all([
+        import('../core/boot.js'),
+        import('../core/mega-cluster.js'),
+        import('../core/cluster-metrics.js'),
+        import('../lib/mega-logger.js'),
+      ])
+
     // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
     const bootListen = async () => {
       const { server, appLogger } = await bootApp(projectRoot, { listen: true, port, host, logger })
@@ -485,7 +495,8 @@ function buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, se
       '--cluster [n]',
       "워커 프로세스 수 — 정수 N 또는 'max'(CPU 코어 수, 베어 플래그도 max). 우선순위: 플래그 > MEGA_CLUSTER_WORKERS env > server.cluster config. 1/미지정 = 단일 프로세스",
     )
-    .option('--watch', 'dev watch — 파일 변경 시 자동 재시작(node 내장 --watch 재실행, 단일 프로세스 강제)')
+    .option('--watch', 'dev watch — 파일 변경 시 자동 재시작(단일 프로세스 강제). locales/views/public/uploads/var/.mega/.env* 등은 디폴트 ignore')
+    .option('--watch-ignore <globs>', 'watch 추가 ignore(콤마 구분 glob, 디폴트에 더해짐). config watch.ignore 와 병합')
     .action(async (/** @type {any} */ opts) => {
       setExit(await runStart(opts, { argv, out, projectRoot, logger, spawn, selfPath }))
     })
@@ -539,6 +550,7 @@ function buildProgram({ argv, out, err, projectRoot, logger, spawn, selfPath, se
     .option('--adapter <key>', '특정 adapter(services.databases 키)만 처리(기본: 전부)')
     .option('--app <name>', '마이그레이션 파일을 둘 앱(기본: main)', 'main')
     .action(async (/** @type {string | undefined} */ name, /** @type {any} */ opts) => {
+      const { runMigrateGenerate } = await import('../core/migration/generate.js')
       const r = await runMigrateGenerate(projectRoot, {
         name,
         renames: opts.renames,
@@ -662,10 +674,11 @@ export function collectRegistrations(global, host, kind) {
  * 주입(테스트)이 있으면 그쪽을 그대로 쓰고 pino 는 만들지 않는다(side-effect 회피).
  * @param {Object} global - global config(`logger` 보유 가능).
  * @param {{ info?: Function, warn?: Function } | undefined} injectedLogger - 주입 로거(테스트) 또는 undefined.
- * @returns {{ info?: Function, warn?: Function } | null} 호스트 로그에 쓸 로거(없으면 null).
+ * @returns {Promise<{ info?: Function, warn?: Function } | null>} 호스트 로그에 쓸 로거(없으면 null).
  */
-function wireHostLogger(global, injectedLogger) {
+async function wireHostLogger(global, injectedLogger) {
   if (injectedLogger) return injectedLogger
+  const { buildLogger } = await import('../lib/mega-logger.js') // pino 그래프 — 호스트 경로에서만 로드.
   const appLogger = buildLogger(/** @type {any} */ (global).logger)
   if (appLogger) {
     // 종료 시퀀스 로그를 pino 로(ADR-178) + graceful 시 로그 버퍼 flush. 'logs' stage 라 종료
@@ -683,12 +696,17 @@ function wireHostLogger(global, injectedLogger) {
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaJobWorker>}
+ * @returns {Promise<import('../lib/mega-job-worker.js').MegaJobWorker>}
  */
 export async function runWorkerHost(projectRoot, logger) {
-  // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx).
+  // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx). 런타임 그래프는 lazy.
+  const [{ prepareRuntime }, { MegaJobWorker }, MegaMetrics] = await Promise.all([
+    import('../core/boot.js'),
+    import('../lib/mega-job-worker.js'),
+    import('../lib/mega-metrics.js'),
+  ])
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
-  const log = wireHostLogger(global, logger)
+  const log = await wireHostLogger(global, logger)
   const worker = new MegaJobWorker({ ctx })
   // 잡 메트릭 (ADR-132) — prepareRuntime 이 health.exposeMetrics 시 이미 MegaMetrics.init 했고,
   // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
@@ -712,11 +730,15 @@ export async function runWorkerHost(projectRoot, logger) {
  * `mega scheduler` 호스트 골격 — config + 어댑터 connect + ctx + `MegaScheduler` 인스턴스 + graceful.
  * @param {string} projectRoot
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [logger]
- * @returns {Promise<MegaScheduler>}
+ * @returns {Promise<import('../lib/mega-schedule.js').MegaScheduler>}
  */
 export async function runSchedulerHost(projectRoot, logger) {
+  const [{ prepareRuntime }, { MegaScheduler }] = await Promise.all([
+    import('../core/boot.js'),
+    import('../lib/mega-schedule.js'),
+  ])
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
-  const log = wireHostLogger(global, logger)
+  const log = await wireHostLogger(global, logger)
   const scheduler = new MegaScheduler({ ctx })
   // 등록 소스(ADR-123) = config.schedules(정적) + 플러그인 host.listSchedules()(동적). register 가
   // cron 미선언·중복을 부팅 시 fail-fast.
@@ -807,6 +829,13 @@ export async function runMigrateHost(projectRoot, { direction = 'up', dbKey, log
       info: (/** @type {any} */ o, /** @type {string} */ msg) => out(`[migrate] ${fmt(o, msg)}`),
       warn: (/** @type {any} */ o, /** @type {string} */ msg) => out(`[migrate] 경고: ${fmt(o, msg)}`),
     }
+  // 빌트인 어댑터 배럴을 명시 로드(ADR-150) — migrate 는 boot.js 를 거치지 않고 buildFromGlobalConfig
+  // 를 직접 부르므로, boot 정적 import 가 사라진 lazy CLI 에선 여기서 driver 자기등록을 보장해야 한다.
+  const [{ migrateUp, migrateDown, migrateStatus }, { withMigrationLock }] = await Promise.all([
+    import('../core/migration-runner.js'),
+    import('../core/migration-lock.js'),
+    import('../adapters/index.js'),
+  ])
   const { global, apps } = await loadAndValidateConfig(projectRoot)
   // 플러그인 install 을 어댑터 build 보다 먼저(config-driven driver 제약, boot.js 주석 참조).
   const host = new MegaPluginHost({ logger })

package/src/cli/watch.js

@@ -0,0 +1,188 @@
+// @ts-check
+/**
+ * `mega start --watch` 의 dev watch supervisor (ADR-220, ADR-182 개정).
+ *
+ * Node 내장 `--watch-path` 재실행(구 ADR-182)은 **ignore 패턴이 없어** 런타임이 쓰는 파일까지
+ * 재시작을 유발했다 — dev 의 i18n saveMissing 이 `locales/*.json` 자동 기입(재시작 무한 루프),
+ * 업로드가 `uploads/`/`var/` 에 파일 저장(사용자 입력이 서버를 재시작), 마이그레이션 generate 가
+ * `.mega/` journal 갱신. 본 모듈이 그 재실행을 **자체 supervisor**(fs.watch recursive + 미니 glob
+ * ignore + debounce + SIGTERM respawn)로 대체한다 — 신규 dep 0(chokidar 미도입: 필요한 매칭이
+ * `**`/`*`/`?` 수준이라 풀스펙 glob 라이브러리가 과함).
+ *
+ * ignore 합성 = config `watch.ignore` + CLI `--watch-ignore`. **숨은 코드 디폴트는 없다**(사용자
+ * 결정 — 개발자가 보지 못하는 목록은 폴더명이 다른 프로젝트에서 오히려 혼란) — 권장 목록은 스캐폴드
+ * `.env` 의 `WATCH_IGNORE` 가 실값으로 명시하고 `mega.config.js` 가 읽어 `watch.ignore` 로 넘긴다.
+ * ignore 0 이면 supervisor 가 기동 시 경고 1줄을 낸다(locales saveMissing 루프 등 위험 가시화).
+ *
+ * @module cli/watch
+ */
+import { watch as fsWatch, existsSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/**
+ * 미니 glob → RegExp. 지원: 더블스타+슬래시(0개 이상의 디렉토리), 더블스타(경로 전체), `*`(세그먼트
+ * 내), `?`(1글자). 그 외 문자는 리터럴(정규식 특수문자 escape). 매칭 대상은 루트 상대 POSIX 경로
+ * 전체(^…$). 패턴 예시는 스캐폴드 `.env` 의 `WATCH_IGNORE` 참조 — JS 블록 주석 안에는
+ * 더블스타+슬래시 시퀀스를 쓸 수 없어(주석 조기 종료) 여기 직접 못 적는다.
+ *
+ * @param {string} pattern - glob 패턴(예 `.env.*`).
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern) {
+  let re = ''
+  let i = 0
+  while (i < pattern.length) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**/` 는 0개 이상의 디렉토리(루트 레벨 포함), 그 외 `**` 는 임의 문자열.
+        if (pattern[i + 2] === '/') {
+          re += '(?:.*/)?'
+          i += 3
+        } else {
+          re += '.*'
+          i += 2
+        }
+      } else {
+        re += '[^/]*'
+        i += 1
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+      i += 1
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      i += 1
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+/**
+ * ignore 패턴 합성 — config(`watch.ignore`) + CLI(`--watch-ignore a,b`). 숨은 디폴트 없음(모듈
+ * docstring 참조). 잘못된 모양은 fail-fast(silent 무시 금지).
+ *
+ * @param {{ ignore?: unknown }} [watchConfig] - mega.config.js 의 `watch`.
+ * @param {string | undefined} [cliIgnore] - `--watch-ignore` 값(콤마 구분).
+ * @returns {string[]}
+ * @throws {TypeError} config `watch.ignore` 가 문자열 배열이 아닐 때.
+ */
+export function mergeWatchIgnore(watchConfig = {}, cliIgnore = undefined) {
+  /** @type {string[]} */
+  const merged = []
+  if (watchConfig.ignore !== undefined) {
+    if (!Array.isArray(watchConfig.ignore) || watchConfig.ignore.some((p) => typeof p !== 'string' || p.length === 0)) {
+      throw new TypeError('config watch.ignore 는 비어있지 않은 문자열 배열이어야 합니다.')
+    }
+    merged.push(...watchConfig.ignore)
+  }
+  if (typeof cliIgnore === 'string' && cliIgnore.length > 0) {
+    merged.push(...cliIgnore.split(',').map((p) => p.trim()).filter((p) => p.length > 0))
+  }
+  return merged
+}
+
+/**
+ * 루트 상대 경로가 ignore 에 걸리는지 (Boolean — `is*`).
+ * @param {string} rel - 루트 상대 POSIX 경로(예 `apps/main/locales/ko.json`).
+ * @param {RegExp[]} regexps - {@link globToRegExp} 컴파일 결과.
+ * @returns {boolean}
+ */
+export function isIgnoredPath(rel, regexps) {
+  return regexps.some((r) => r.test(rel))
+}
+
+/**
+ * watch supervisor — 감시 경로의 변경(ignore 통과분)을 debounce 후 자식(`mega start`)을
+ * SIGTERM → respawn 한다. 자식이 스스로 죽으면(crash) 재시작하지 않고 다음 변경을 기다린다
+ * (crash-loop 방지 — nodemon 의 "app crashed - waiting for file changes" 와 동형).
+ *
+ * @param {object} o
+ * @param {string} o.projectRoot
+ * @param {string[]} o.watchPaths - 감시할 절대경로(존재하는 것만 — 호출측이 필터).
+ * @param {string[]} o.ignore - glob 패턴 목록.
+ * @param {() => import('node:child_process').ChildProcess} o.spawnChild - 자식 기동 팩토리(주입 — 테스트).
+ * @param {(msg: string) => void} o.out
+ * @param {number} [o.debounceMs=500] - 연속 변경 디바운스.
+ * @param {(dir: string, opts: object, cb: (event: string, filename: string | Buffer | null) => void) => { close(): void }} [o.watchFn] -
+ *   fs.watch 주입(테스트). 기본 node:fs watch.
+ * @returns {Promise<number>} 부모(supervisor)의 exit code — SIGINT/SIGTERM 수신 시 자식 정리 후 0.
+ */
+export function startWatchSupervisor({ projectRoot, watchPaths, ignore, spawnChild, out, debounceMs = 500, watchFn = /** @type {any} */ (fsWatch) }) {
+  const regexps = ignore.map(globToRegExp)
+  /** @type {import('node:child_process').ChildProcess | null} */
+  let child = null
+  /** @type {NodeJS.Timeout | null} */
+  let pending = null
+  let shuttingDown = false
+  let restarting = false
+
+  const start = () => {
+    child = spawnChild()
+    child.on('exit', (code, signal) => {
+      if (shuttingDown) return
+      if (restarting) {
+        restarting = false
+        start()
+        return
+      }
+      // 자식이 스스로 종료(crash/정상) — 재시작 폭주 대신 다음 변경 대기(P4: 이유 출력).
+      out(`mega: app exited (code=${code ?? `signal:${signal}`}) — waiting for file changes before restart`)
+      child = null
+    })
+  }
+
+  const scheduleRestart = (/** @type {string} */ rel) => {
+    if (pending) clearTimeout(pending)
+    pending = setTimeout(() => {
+      pending = null
+      out(`mega: restarting due to changes (${rel})`)
+      if (child && child.exitCode === null && !child.killed) {
+        restarting = true
+        child.kill('SIGTERM') // graceful — exit 핸들러가 respawn.
+      } else {
+        start() // crash 후 대기 상태 — 변경으로 재기동.
+      }
+    }, debounceMs)
+  }
+
+  /** @type {Array<{ close(): void }>} */
+  const watchers = []
+  for (const abs of watchPaths) {
+    const isDir = statSync(abs).isDirectory()
+    const watcher = watchFn(abs, { recursive: isDir }, (_event, filename) => {
+      // filename 은 감시 루트 상대(파일 watch 면 basename) — 루트 상대로 정규화해 ignore 매칭.
+      const name = typeof filename === 'string' ? filename : (filename ? String(filename) : '')
+      const rel = relative(projectRoot, isDir ? join(abs, name) : abs).split(sep).join('/')
+      if (isIgnoredPath(rel, regexps)) return
+      scheduleRestart(rel)
+    })
+    watchers.push(watcher)
+  }
+
+  start()
+
+  return new Promise((resolve) => {
+    /** @type {NodeJS.Signals[]} */
+    const sigs = ['SIGINT', 'SIGTERM']
+    const onSignal = () => {
+      shuttingDown = true
+      if (pending) clearTimeout(pending)
+      for (const w of watchers) w.close()
+      for (const s of sigs) process.removeListener(s, onSignal)
+      if (child && child.exitCode === null && !child.killed) {
+        child.once('exit', () => resolve(0))
+        child.kill('SIGTERM')
+      } else {
+        resolve(0)
+      }
+    }
+    for (const s of sigs) process.on(s, onSignal)
+  })
+}
+
+/** {@link startWatchSupervisor} 의 watchPaths 기본 집합 — 존재하는 것만.
+ * @param {string} projectRoot @returns {string[]} */
+export function defaultWatchPaths(projectRoot) {
+  return [join(projectRoot, 'apps'), join(projectRoot, 'shared'), join(projectRoot, 'mega.config.js')].filter(existsSync)
+}

package/src/core/ajv-mapper.js

@@ -74,7 +74,9 @@ function ajvItemToDetail(e) {
   if (e.keyword === 'required' && missing) {
     field = field ? `${field}.${missing}` : missing
   }
-  const isSensitive = SENSITIVE_FIELD_RE.test(field) || SENSITIVE_FIELD_RE.test(missing)
+  // 정규식 1회 실행 (G1 M-2, ADR-214) — field·missingProperty 를 합쳐 한 번만 검사한다. allErrors
+  // (ADR-193) 이후 400 1건당 detail × 2회 실행되던 비용 절반화. 매칭 의미는 동일(부분 일치 OR).
+  const isSensitive = SENSITIVE_FIELD_RE.test(missing ? `${field} ${missing}` : field)
   return {
     field,
     rule: e.keyword || 'unknown',

package/src/core/ctx-builder.js

@@ -37,6 +37,9 @@ function passthroughT(key, defaultValue) {
 /** 요청당 ctx 를 캐싱하는 비열거 키. 글로벌 미들웨어와 라우트 핸들러가 같은 ctx 를 공유하도록 한다. */
 const HTTP_CTX_KEY = Symbol('mega.httpCtx')
 
+/** 요청당 lazy ctx 프록시 캐싱 키 — 미들웨어·핸들러가 같은 프록시 객체를 받도록 한다 (ADR-214). */
+const LAZY_CTX_KEY = Symbol('mega.lazyHttpCtx')
+
 /**
  * `ctx.services.<name>` lazy DI proxy (ADR-148) — 요청별 서비스 인스턴스화·캐시.
  *
@@ -252,6 +255,61 @@ export function getHttpCtx({ app, req, reply }) {
   const cached = /** @type {any} */ (req)[HTTP_CTX_KEY]
   if (cached) return cached
   const ctx = buildHttpCtx({ app, req, reply })
-  Object.defineProperty(req, HTTP_CTX_KEY, { value: ctx, enumerable: false, configurable: true })
+  // 심볼 직접 대입 (G1 H-2, ADR-214) — 심볼 키는 어차피 Object.keys/spread/JSON 에 안 잡히므로
+  // 비열거 defineProperty 의 실익이 없고, defineProperty 는 hidden class 전이를 유발해 17배 비싸다(실측).
+  ;/** @type {any} */ (req)[HTTP_CTX_KEY] = ctx
   return ctx
 }
+
+/**
+ * **lazy** HTTP ctx — 실제 ctx 빌드를 첫 속성 접근 시점까지 미루는 요청당 프록시 (G1 H-1, ADR-214).
+ *
+ * hot path 단일 최대 프레임워크 비용이 "핸들러가 ctx 를 안 써도 매 요청 무조건 buildHttpCtx"
+ * (1,615 B + ≈0.7 µs/req, CPU 2.3% — audit-G1 실측)였다. 이 프록시는 생성 비용이 객체 1개 수준이고,
+ * 핸들러·미들웨어가 ctx 의 속성을 **처음 만질 때만** {@link getHttpCtx} 로 실 ctx 를 만든다(이후 캐시).
+ *
+ * 호환성: canonical 시그니처 `(req, reply, ctx)` 는 그대로 — 모든 핸들러가 여전히 3번째 인자를 받고,
+ * 참조하는 순간부터는 기존과 동일한 실 ctx 표면(ADR-134 요청당 공유 포함)이다. 프록시 자체도 요청당
+ * 1개로 캐시되어 미들웨어와 핸들러가 **동일 객체**(`===`)를 받는다. 모든 트랩이 실 ctx 로 위임되므로
+ * `in`/spread/`Object.keys`/getter·setter(`ctx.user=`) 동작이 보존된다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getLazyHttpCtx({ app, req, reply }) {
+  const cached = /** @type {any} */ (req)[LAZY_CTX_KEY]
+  if (cached) return cached
+  /** 첫 트랩에서 실 ctx 를 만들고 이후 재사용 (getHttpCtx 가 req 단위 캐시를 겸한다). */
+  const real = () => getHttpCtx({ app, req, reply })
+  const proxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        return Reflect.get(real(), prop)
+      },
+      set(_t, prop, value) {
+        return Reflect.set(real(), prop, value)
+      },
+      has(_t, prop) {
+        return Reflect.has(real(), prop)
+      },
+      ownKeys() {
+        return Reflect.ownKeys(real())
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        return Object.getOwnPropertyDescriptor(real(), prop)
+      },
+      defineProperty(_t, prop, desc) {
+        return Reflect.defineProperty(real(), prop, desc)
+      },
+      deleteProperty(_t, prop) {
+        return Reflect.deleteProperty(real(), prop)
+      },
+    },
+  )
+  ;/** @type {any} */ (req)[LAZY_CTX_KEY] = proxy
+  return proxy
+}

package/src/core/envelope.js

@@ -22,13 +22,20 @@ export const REPLY_START_SYMBOL = Symbol('mega.reply.start')
 export const ENVELOPE_MARK = Symbol('mega.envelope')
 
 /**
- * envelope 객체에 비열거 마킹을 부착한다.
+ * envelope 객체에 마킹을 부착한다.
+ *
+ * 심볼 **직접 대입** (G1 M-1, ADR-214) — `Object.defineProperty` 대비 17배 빠르고(136→8 ns/op 실측)
+ * allocation 도 작다. 심볼 키는 어차피 `JSON.stringify`/`Object.keys` 에 안 나오므로 와이어·열거
+ * 동작은 동일하다. 의미 차이는 하나 — spread 복사(`{...env}`)가 마크를 함께 복사한다. 복사본도
+ * "이미 envelope" 로 취급되는데, 이는 이중 wrap 방지(ADR-184)에 오히려 부합한다(복사 후 필드를
+ * 고쳐 재전송하는 패턴도 envelope 그대로 나간다 — 의도된 동작으로 확정, ADR-214).
+ *
  * @template {Record<string, any>} T
  * @param {T} env
  * @returns {T} 같은 객체 (마킹됨).
  */
 function markEnvelope(env) {
-  Object.defineProperty(env, ENVELOPE_MARK, { value: true, enumerable: false })
+  ;/** @type {any} */ (env)[ENVELOPE_MARK] = true
   return env
 }
 

package/src/core/hub-link.js

@@ -189,7 +189,9 @@ export class MegaHubLink {
   /**
    * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
    *
-   * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+   * 초기 연결은 retry 유무와 무관하게 **단 1회** 시도한다. `retry` 옵션이 있으면 실패 시 백그라운드
+   * 재연결(지수 백오프)로 전환하고 reject 한다 — 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+   * 호출부(boot)는 reject 를 warn 으로 받고 부팅을 계속한다(허브 다운이 부팅을 막지 않는 계약).
    *
    * @param {Object} [opts]
    * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에
@@ -214,19 +216,27 @@ export class MegaHubLink {
         throw err
       }
     }
-    // retry 활성 — 최초 연결도 백오프 재시도. AbortError(인증 실패 등) 는 재시도하지 않는다.
-    this._abort = new AbortController()
-    return withRetry(() => this._connectOnce({ connectTimeoutMs: timeout }), {
-      ...this._retry,
-      signal: this._abort.signal,
-      shouldRetry: retryUnlessFatal,
-      onFailedAttempt: (ctx) => {
-        this._log?.warn?.(
-          { bridgeId: this._bridgeId, attempt: ctx.attemptNumber, retriesLeft: ctx.retriesLeft },
-          'hub-link connect attempt failed — backing off',
-        )
-      },
-    })
+    // retry 활성 — 초기 연결은 **단 1회**만 시도하고, 실패하면 백그라운드 재연결로 전환한 뒤 throw 한다.
+    // 예전엔 withRetry 가 최초 연결까지 백오프 전체를 await 해 호출부(boot 의 cluster-transport step)가
+    // 분 단위로 블로킹됐다(crud retry 기준 약 4.7분) — "허브 다운이어도 boot 를 막지 않는다" 는 호출부
+    // 계약과 정반대 동작. 이제 호출부는 즉시 실패를 보고(warn) 부팅을 계속하고, 백그라운드 _reconnect 가
+    // 같은 retry 백오프로 재시도한다 — 성공 시 RECONNECTED 이벤트가 presence 재동기화를 트리거하고,
+    // 소진 시 RECONNECT_FAILED 를 emit 한다. 치명 에러(인증 거부 등 fatal)는 재시도 무의미라 그대로 전파.
+    try {
+      return await this._connectOnce({ connectTimeoutMs: timeout })
+    } catch (err) {
+      // 레거시 hub 폴백(1회) — protocolVersion 필드 거부 판정 후 v1 register 로 즉시 재시도.
+      if (err instanceof Error && err.message === 'hub.legacy_register_fallback') {
+        try {
+          return await this._connectOnce({ connectTimeoutMs: timeout })
+        } catch (err2) {
+          if (retryUnlessFatal({ error: err2 })) void this._reconnect()
+          throw err2
+        }
+      }
+      if (retryUnlessFatal({ error: err })) void this._reconnect()
+      throw err
+    }
   }
 
   /**

package/src/core/index.js

@@ -16,7 +16,7 @@ export { buildErrorHandler } from './error-mapper.js'
 export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from './ajv-mapper.js'
 export { loadAndValidateConfig } from './config-loader.js'
 // 요청 ctx 빌더 — db/cache/bus 접근자 배선 (ADR-102)
-export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
+export { buildHttpCtx, getHttpCtx, getLazyHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
 // WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)
 export {
   createWsMessage,