mega-framework 0.1.5 → 0.1.7

package/src/lib/mega-plugin.js

@@ -53,11 +53,23 @@ const LIFECYCLE_EVENTS = /** @type {const} */ (['beforeBoot', 'afterBoot', 'befo
  */
 
 /**
+ * 플러그인 scaffold generator manifest(03-api-spec §11) — `mega g <name>` 이 소비한다(ADR-187/199).
+ * `dir` 는 프로젝트 루트 상대 출력 기준, `files[].path`/`files[].template` 의 `{{token}}` 은
+ * cli/generators 의 `SCAFFOLD_TOKENS` 계약(Name/name/camelName/snake/app)으로 치환된다.
  * @typedef {Object} MegaScaffoldDef
  * @property {string} dir
  * @property {Array<{ path: string, template: string }>} files
+ * @property {string} [description] - `mega help` 가 병기하는 한 줄 설명(선택).
  */
 
+/** 빌트인 generator 13종 이름 — 플러그인 scaffold 가 점유 금지(빌트인이 우선이라 silent shadow 가 됨).
+ * cli/generators 의 `GENERATOR_KINDS` 와 동일해야 한다(레이어 역전 회피를 위해 미러 — 동기화는
+ * mega-plugin 단위 테스트가 GENERATOR_KINDS 와 집합 비교로 강제한다). */
+export const RESERVED_GENERATOR_NAMES = new Set([
+  'app', 'controller', 'channel', 'service', 'model', 'middleware', 'route',
+  'schedule', 'job', 'worker', 'locale', 'adapter', 'migration',
+])
+
 /**
  * @typedef {Object} LoadedPluginMeta
  * @property {string} name
@@ -230,7 +242,8 @@ export class MegaPluginHost {
   }
 
   /**
-   * 스캐폴드 generator 등록. 같은 이름 재등록은 fail-fast.
+   * 스캐폴드 generator manifest 등록(ADR-199). 같은 이름 재등록·빌트인 13종 점유·파일 항목 모양 위반은
+   * **install 시점 fail-fast** — 첫 `mega g` 사용 때까지 잘못된 manifest 가 잠복하지 않게 한다.
    * @param {string} name
    * @param {MegaScaffoldDef} def
    * @returns {void}
@@ -239,15 +252,33 @@ export class MegaPluginHost {
     if (typeof name !== 'string' || name.length === 0) {
       throw new TypeError('mega.scaffold.register: name must be a non-empty string.')
     }
-    if (!def || typeof def.dir !== 'string' || !Array.isArray(def.files)) {
+    if (RESERVED_GENERATOR_NAMES.has(name)) {
+      // 빌트인 kind 는 `mega g` 디스패치에서 항상 우선이라, 등록을 허용하면 도달 불가(silent shadow)다.
+      throw new MegaConfigError('plugin.builtin_generator_conflict', `Plugin cannot register builtin generator "${name}" (reserved).`, {
+        details: { name },
+      })
+    }
+    if (!def || typeof def.dir !== 'string' || def.dir.length === 0 || !Array.isArray(def.files)) {
       throw new TypeError(`mega.scaffold.register('${name}'): def must be { dir: string, files: array }.`)
     }
+    for (const f of def.files) {
+      if (!f || typeof f.path !== 'string' || f.path.length === 0 || typeof f.template !== 'string') {
+        throw new TypeError(`mega.scaffold.register('${name}'): files entries must be { path: string, template: string }. Got ${JSON.stringify(f)}.`)
+      }
+    }
+    if (def.description !== undefined && typeof def.description !== 'string') {
+      throw new TypeError(`mega.scaffold.register('${name}'): description must be a string when given.`)
+    }
     if (this.#generators.has(name)) {
       throw new MegaConfigError('plugin.duplicate_generator', `Scaffold generator '${name}' is already registered.`, {
         details: { name },
       })
     }
-    this.#generators.set(name, { dir: def.dir, files: [...def.files] })
+    this.#generators.set(name, {
+      dir: def.dir,
+      files: def.files.map((f) => ({ path: f.path, template: f.template })),
+      ...(typeof def.description === 'string' ? { description: def.description } : {}),
+    })
   }
 
   /**

package/src/lib/mega-schedule.js

@@ -15,9 +15,10 @@
  *   먼저 잡은 1대만 실행하고, 못 잡은 나머지는 **조용히 건너뛴다**(skip). 락은 `ttl`(ms) 뒤 자동 만료돼
  *   다음 주기엔 다시 경쟁한다.
  *
- *   구현: `lock.acquire(key, { ttl, retryCount: 0 })` — **단 한 번** 시도하고 실패하면(이미 누가 잡음)
- *   즉시 skip 한다(retry 안 함 — retry+throw 는 "중복방지"가 아니라 "대기"라서 의미가 다름). 성공하면
- *   `run(ctx)` 실행 후 **반드시 release**(finally).
+ *   구현: `lock.withLock(key, { ttl, retryCount: 0 }, run)` — **단 한 번** 시도하고 실패하면(이미 누가
+ *   잡음) 즉시 skip 한다(retry 안 함 — retry+throw 는 "중복방지"가 아니라 "대기"라서 의미가 다름).
+ *   성공하면 임계구역 동안 락이 **자동 연장**되고(redlock `using`), 종료 시 자동 release 된다 —
+ *   run 이 ttl 을 넘겨도 락이 만료돼 다른 인스턴스가 끼어드는 중복 실행이 없다.
  *
  * # ⚠️ acquire 실패 = skip 의 한계 (ADR-118 기록)
  *   `acquire` 는 (a) 경합(다른 인스턴스가 보유)과 (b) 락 backend 장애(Redis 다운)를 **둘 다** throw 로
@@ -46,8 +47,10 @@ import { MegaCron } from './mega-cron.js'
  * @typedef {Object} MegaScheduleLock
  * @property {string} lock - lock 어댑터 별명(`ctx.lock(alias)` 로 해석). 03-api-spec 의 옛 `cache` 필드를
  *   대체한다(lock 이 독립 도메인이 된 뒤 정합 — ADR-118).
- * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). **작업 예상 소요보다 넉넉히** 잡아야
- *   한다 — 작업이 ttl 을 넘기면 락이 자동 만료돼 다른 인스턴스가 중복 실행할 수 있다(자동 연장 미사용).
+ * @property {number} ttl - 락 보유 시간(**밀리초**, 양의 정수). 임계구역 동안 **자동 연장**되므로
+ *   (redlock `using`) 작업이 ttl 을 넘겨도 중복 실행되지 않는다 — ttl 은 "연장 1회분 윈도우"다.
+ *   ⚠️ redlock 은 `ttl ≥ automaticExtensionThreshold(기본 500ms) + 100ms` 를 요구한다(기본 설정 기준
+ *   **600ms 이상**) — 미달이면 fire 시 skip(error 동봉)으로 표면화된다.
  * @property {string} [key] - 락 자원 키. 미지정 시 `mega:schedule:<클래스명>`.
  */
 
@@ -463,28 +466,43 @@ export class MegaScheduler extends EventEmitter {
     }
     const key = lock.key ?? `mega:schedule:${name}`
 
-    let held
+    // withLock(= redlock `using`, ADR-113) — 단 한 번 시도(retryCount: 0) + **자동 연장** + 자동 release.
+    // run 이 ttl 을 넘겨도 redlock 이 임계구역 동안 락을 연장해 다른 인스턴스의 중복 실행을 막는다
+    // (기존 acquire/release 는 "ttl 을 넉넉히" 라는 운영자 추측에 의존 — ADR-118 재평가 조건 충족으로 전환).
+    // 경합/backend 장애는 routine 진입 **전에** throw 되므로 acquired 플래그로 skip(미획득)과
+    // release 실패(획득 후)를 구분한다. run(ctx) 계약은 무변경 — 연장 실패(signal.aborted)는
+    // 스케줄러가 관찰해 fail(lock-extend) 로 표면화한다.
+    let acquired = false
+    /** @type {MegaScheduleFireResult|undefined} */
+    let outcome
     try {
-      // 단 한 번 시도(retryCount: 0). 실패=이미 누가 보유(또는 backend 장애) → skip.
-      held = await adapter.acquire(key, { ttl: lock.ttl, retryCount: 0 })
+      await adapter.withLock(key, { ttl: lock.ttl, retryCount: 0 }, async (/** @type {any} */ signal) => {
+        acquired = true
+        outcome = await this.#runBody(name, instance, ctx, key)
+        // 자동 연장 실패 = 임계구역 도중 배타성 상실(드묾 — lock backend 장애). run 결과와 별개로 표면화.
+        if (signal?.aborted) {
+          const cause = signal.error instanceof Error ? signal.error : undefined
+          const error = new Error(
+            `lock auto-extension failed for '${key}' — exclusivity may have been lost during run`,
+            cause ? { cause } : undefined,
+          )
+          this.emit('fail', { name, key, error, phase: 'lock-extend' })
+        }
+      })
     } catch (e) {
       const error = e instanceof Error ? e : new Error(String(e))
-      // 에러를 실어 관측 가능하게 — 인프라 장애도 여기로 오므로 소비자가 구분/경보(상단 docstring).
-      this.emit('skip', { name, key, reason: 'lock-not-acquired', error })
-      return { name, ran: false, skipped: true, ok: false, error }
-    }
-
-    try {
-      return await this.#runBody(name, instance, ctx, key)
-    } finally {
-      try {
-        await adapter.release(held)
-      } catch (e) {
-        // 락 해제 실패는 비치명적(ttl 로 자동 만료) — 다음 주기 재경쟁. 묵히지 않고 fail 로 표면화.
-        const error = e instanceof Error ? e : new Error(String(e))
-        this.emit('fail', { name, key, error, phase: 'release' })
+      if (!acquired) {
+        // 획득 실패 = 경합(다른 인스턴스 보유) 또는 backend 장애 — 구분 불가(상단 docstring).
+        // 에러를 실어 관측 가능하게 → 소비자가 로그/경보로 인프라 장애를 알아챈다.
+        this.emit('skip', { name, key, reason: 'lock-not-acquired', error })
+        return { name, ran: false, skipped: true, ok: false, error }
       }
+      // routine 진입 후 throw = release 경로 실패(#runBody 는 throw 안 함) — 비치명적(ttl 만료로
+      // 자동 해제, 다음 주기 재경쟁). run 결과는 보존해 반환한다.
+      this.emit('fail', { name, key, error, phase: 'release' })
+      return outcome ?? { name, ran: true, skipped: false, ok: false, error }
     }
+    return /** @type {MegaScheduleFireResult} */ (outcome)
   }
 
   /**

package/src/lib/mega-shutdown.js

@@ -3,33 +3,60 @@
 /**
  * MegaShutdown — graceful shutdown 시퀀스 + 사용자 cleanup hook 묶음.
  *
- * 시퀀스 (docs/10 §3):
- *   Running → DrainingReady (health 'ready' = 503)
- *   → ClosingHttp (Fastify close, 진행중 요청 grace)
- *   → ClosingWs (placeholder)
- *   → ClosingJobs / ClosingScheduler (placeholder)
- *   → DisconnectingAdapters (placeholder)
- *   → FlushingLogs (placeholder)
- *   → Exited (process.exit(0))
+ * 시퀀스 (docs/10 §3) — 명시 stage 로 코드화({@link SHUTDOWN_STAGES}):
+ *   Running → [server → jobs → app → workers → adapters → telemetry → logs] → Exited (process.exit)
  *
- * SIGTERM/SIGINT 캐치 + 사용자 hook 실행 (LIFO) + grace period + hardKill.
- * 후속 Phase 에서 단계 hook 자동 추가 (Fastify·어댑터·로거 등).
+ * SIGTERM/SIGINT 캐치 + stage 순서 실행(stage 안은 등록 역순 LIFO) + hook 별 grace + hardKill 데드라인.
+ * readiness 503 전환(DrainingReady)은 isShuttingDown() 을 MegaHealth.checkAll 이 읽어 즉시 반영된다.
  *
  * API 는 docs/10·07 시퀀스에 맞춰 `MegaShutdown` 객체로 통일 (ADR — M-4).
  *
  * 사용 예:
- *   MegaShutdown.register('http', async () => server.close())
- *   MegaShutdown.register('db', async () => pool.end())
+ *   MegaShutdown.register('my-queue', async () => consumer.stop())             // 기본 stage 'app'
+ *   MegaShutdown.register('db', async () => pool.end(), { stage: 'adapters' }) // 명시 stage
  *   MegaShutdown.setupSignals({ gracePeriodMs: 30_000, hardKillMs: 60_000 })
  *   await MegaShutdown.now()   // 수동 트리거
  */
 
-/** @type {Array<{ name: string, fn: () => Promise<void> | void }>} */
+/**
+ * 종료 stage 정본 순서 (docs/10 §3 의 단계를 코드로 명시) — `register(name, fn, { stage })` 가 이 중
+ * 하나를 지정하고, `now()` 는 이 배열 순서대로 stage 를 실행한다(stage 안에서는 등록 역순 LIFO).
+ *
+ *   server    — HTTP/WS 수용 종료(서버 close, 진행 중 요청 drain). ClosingHttp/ClosingWs.
+ *   jobs      — 잡 컨슈머·스케줄러 정지(새 잡 수신 중단, 진행 중 잡 완료). ClosingJobs/ClosingScheduler.
+ *   app       — 앱 레벨 정리(플러그인 beforeShutdown·세션 store·WS cluster/roster 등 어댑터를 **쓰는** 정리).
+ *               `stage` 미지정 기본값 — 사용자 cleanup 은 어댑터가 살아 있는 이 단계에서 돈다.
+ *   workers   — CPU 워커 풀·embedded wsHub 등 백그라운드 실행기 정지.
+ *   adapters  — 공유 어댑터 disconnect(DisconnectingAdapters, stage 안 LIFO = connect 역순).
+ *   telemetry — 메트릭·트레이싱 SDK flush/shutdown. 어댑터 **뒤** — disconnect 까지의 span/메트릭을 내보낸다.
+ *   logs      — 로거 flush(FlushingLogs). 항상 마지막 — 종료 시퀀스 자체의 로그가 유실되지 않게.
+ */
+export const SHUTDOWN_STAGES = Object.freeze(['server', 'jobs', 'app', 'workers', 'adapters', 'telemetry', 'logs'])
+
+/** `register` 가 stage 미지정일 때 들어가는 기본 stage — 사용자 cleanup 의 표준 위치(어댑터 종료 전). */
+const DEFAULT_STAGE = 'app'
+
+/** @type {Array<{ name: string, fn: () => Promise<void> | void, stage: string }>} */
 const handlers = []
 let signalsRegistered = false
+/** @type {Array<{ sig: string, fn: () => void }>} setupSignals 가 등록한 시그널 리스너(_reset 해제용). */
+let signalHandlers = []
 let isShuttingDownFlag = false
-let gracePeriodMs = 30_000
-let hardKillMs = 60_000
+
+/** hook 1개당 grace 기본값(ms) — 30초. `setupSignals({ gracePeriodMs })` 로 조정. */
+export const DEFAULT_GRACE_PERIOD_MS = 30_000
+
+/**
+ * graceful shutdown 전체 상한 기본값(ms) — 60초. 초과 시 hardKill(exit 1). 워커 프로세스의 종료 예산
+ * 상한이므로, 클러스터 마스터의 grace(`MegaCluster.gracePeriodMs`)는 **이 값 + 마진 이상**이어야
+ * 워커가 drain 을 끝내기 전에 마스터가 SIGKILL 하는 예산 역전이 없다(CLI 가 이 상수로 위계화).
+ */
+export const DEFAULT_HARD_KILL_MS = 60_000
+
+let gracePeriodMs = DEFAULT_GRACE_PERIOD_MS
+let hardKillMs = DEFAULT_HARD_KILL_MS
+/** hook 루프가 hardKill 직전에 끝나도록 남기는 여유(ms) — 루프가 hardKill 타이머를 clear 하고 정상 exit 한다. */
+const HARD_KILL_MARGIN_MS = 100
 let exitedHandlers = new Set()
 /** 전역 에러 핸들러 등록 여부 + 참조(reset 시 removeListener 용). @type {boolean} */
 let globalErrorsRegistered = false
@@ -37,25 +64,40 @@ let globalErrorsRegistered = false
 let unhandledRejectionHandler = null
 /** @type {((err: Error, origin?: string) => void) | null} */
 let uncaughtExceptionHandler = null
+/**
+ * 전역 에러 핸들러가 fatal 로그에 쓸 로거. boot 이 pino 공유 인스턴스(appLogger)를 주입한다(setLogger).
+ * 미설정(부팅 전 조기 크래시·로거 비활성 프로세스)이면 console.error 로 폴백한다. process 레벨 핸들러는
+ * bootApp 의 DI 그래프 밖이라 모듈 스코프 변수로 받아 둔다(전역 오염 회피, ADR-178).
+ * @typedef {{ info?: (...args: any[]) => void, warn?: (...args: any[]) => void, error?: (...args: any[]) => void, fatal?: (...args: any[]) => void }} ShutdownLogger
+ * @type {ShutdownLogger | null}
+ */
+let shutdownLogger = null
 
 /**
- * cleanup hook 등록. 순서는 등록 역순(LIFO)으로 실행.
- * @param {string} name - 식별자 (로그용)
+ * cleanup hook 등록. 실행 순서 = {@link SHUTDOWN_STAGES} 순서 → 같은 stage 안에서는 등록 역순(LIFO).
+ * `stage` 미지정이면 `'app'`(어댑터 종료 전, 사용자 cleanup 표준 위치) — 기존 2-인자 호출과 호환.
+ * @param {string} name - 식별자 (로그·unregister 용)
  * @param {() => Promise<void> | void} fn
+ * @param {{ stage?: string }} [opts] - 종료 stage({@link SHUTDOWN_STAGES} 중 하나).
  */
-function register(name, fn) {
+function register(name, fn, opts = {}) {
   if (typeof name !== 'string' || name.length === 0) {
     throw new Error('MegaShutdown.register: name is required (string)')
   }
   if (typeof fn !== 'function') {
     throw new Error('MegaShutdown.register: fn must be a function')
   }
-  handlers.push({ name, fn })
+  const stage = opts.stage ?? DEFAULT_STAGE
+  // stage 오타가 조용히 엉뚱한 순서로 실행되지 않게 등록 시점 fail-fast.
+  if (!SHUTDOWN_STAGES.includes(stage)) {
+    throw new Error(`MegaShutdown.register: unknown stage '${stage}' (valid: ${SHUTDOWN_STAGES.join(', ')})`)
+  }
+  handlers.push({ name, fn, stage })
 }
 
 /**
  * 등록된 cleanup hook 제거 (같은 name 전부). 런타임 중 동적으로 붙였다 떼는 hook(예: hub link)
- * 의 누수를 막는다(L1). shutdown 진행 중에는 인덱스 추적(exitedHandlers)과 충돌하므로 무시한다.
+ * 의 누수를 막는다(L1). shutdown 진행 중에는 실행 추적(exitedHandlers)과 충돌하므로 무시한다.
  * @param {string} name - register 시 쓴 식별자.
  * @returns {number} 제거된 hook 수.
  */
@@ -91,9 +133,13 @@ function setupSignals(opts = {}) {
   if (typeof opts.hardKillMs === 'number') hardKillMs = opts.hardKillMs
   const signals = opts.signals ?? ['SIGTERM', 'SIGINT']
   for (const sig of signals) {
-    process.on(sig, () => {
+    // 리스너 참조를 보관해 _reset 이 떼어낼 수 있게 한다 — reset 후 재-setup 시 리스너가 중복돼
+    // 시그널 1회에 now() 가 2회 불리면 두 번째가 M-3(즉시 force exit 1)로 오인된다.
+    const fn = () => {
       void now({ signal: sig, exitCode: 0 })
-    })
+    }
+    signalHandlers.push({ sig, fn })
+    process.on(sig, fn)
   }
   // 전역 에러 핸들러도 함께 등록(opt-out: globalErrorHandlers === false). REPL(console-cmd) 등은 끌 수 있다.
   if (opts.globalErrorHandlers !== false) setupGlobalErrorHandlers()
@@ -110,23 +156,52 @@ function setupSignals(opts = {}) {
 function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
   if (globalErrorsRegistered) return
   globalErrorsRegistered = true
+  // shutdown 진행 중의 에러는 now() 를 재호출하지 않는다 — teardown 구간(소켓·어댑터 정리)은 floating
+  // rejection 이 가장 나기 쉬운데, 여기서 now() 를 다시 부르면 "두 번째 시그널"(M-3)로 오인돼 남은
+  // hook(어댑터 disconnect·로그 flush)을 건너뛰고 즉시 exit(1) 된다. fatal 기록만 하고 정리를 계속한다.
   unhandledRejectionHandler = (reason) => {
-    const log = /** @type {any} */ (globalThis).logger
     const err = reason instanceof Error ? reason : new Error(`unhandledRejection: ${String(reason)}`)
-    if (log?.fatal) log.fatal({ err }, 'unhandledRejection — initiating graceful shutdown')
-    else console.error('[mega-shutdown] unhandledRejection — initiating graceful shutdown:', err)
+    if (isShuttingDownFlag) {
+      logShutdown('fatal', 'unhandledRejection during shutdown (continuing cleanup)', { err })
+      return
+    }
+    logShutdown('fatal', 'unhandledRejection — initiating graceful shutdown', { err })
     void now({ signal: 'unhandledRejection', exitCode })
   }
   uncaughtExceptionHandler = (err, origin) => {
-    const log = /** @type {any} */ (globalThis).logger
-    if (log?.fatal) log.fatal({ err, origin }, 'uncaughtException — initiating graceful shutdown')
-    else console.error('[mega-shutdown] uncaughtException — initiating graceful shutdown:', err, origin)
+    if (isShuttingDownFlag) {
+      logShutdown('fatal', 'uncaughtException during shutdown (continuing cleanup)', { err, origin })
+      return
+    }
+    logShutdown('fatal', 'uncaughtException — initiating graceful shutdown', { err, origin })
     void now({ signal: 'uncaughtException', exitCode })
   }
   process.on('unhandledRejection', unhandledRejectionHandler)
   process.on('uncaughtException', uncaughtExceptionHandler)
 }
 
+/**
+ * 종료 시퀀스 로깅 — 주입된 로거(setLogger)가 있으면 그 레벨 메서드로, 없으면 console 폴백.
+ * process 레벨 종료 경로라 로거 미주입(부팅 전·로거 비활성 프로세스)일 수 있어 항상 폴백을 갖춘다.
+ * `fatal` 은 console 에 없으므로 폴백에선 `console.error` 로 매핑한다. fields 는 구조적 로그의 payload
+ * (pino `log.level(fields, msg)`)이자 console 폴백의 보조 인자.
+ * @param {'info'|'warn'|'error'|'fatal'} level - 로그 레벨.
+ * @param {string} msg - 메시지.
+ * @param {Record<string, any>} [fields] - 구조적 필드(선택).
+ * @returns {void}
+ */
+function logShutdown(level, msg, fields) {
+  const log = shutdownLogger
+  if (log && typeof (/** @type {any} */ (log)[level]) === 'function') {
+    if (fields) /** @type {any} */ (log)[level](fields, msg)
+    else /** @type {any} */ (log)[level](msg)
+    return
+  }
+  const consoleFn = level === 'warn' ? console.warn : level === 'info' ? console.log : console.error
+  if (fields) consoleFn(`[mega-shutdown] ${msg}`, fields)
+  else consoleFn(`[mega-shutdown] ${msg}`)
+}
+
 /**
  * 즉시 graceful shutdown 트리거.
  *
@@ -138,46 +213,75 @@ function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
 async function now({ signal, exitCode = 0 } = {}) {
   // M-3 — 두 번째 shutdown 시그널: 이미 진행 중이면 grace 무시하고 즉시 force exit 1.
   if (isShuttingDownFlag) {
-    console.error('[mega-shutdown] MegaShutdown: second shutdown signal — force exit 1')
+    logShutdown('error', 'second shutdown signal — force exit 1')
     process.exit(1)
     return   // process.exit mock 시(테스트) 아래로 흐르지 않도록 가드
   }
   isShuttingDownFlag = true
 
-  console.log(`[mega-shutdown] starting (signal=${signal ?? 'manual'}, handlers=${handlers.length}, grace=${gracePeriodMs}ms)`)
+  logShutdown('info', 'shutdown starting', { signal: signal ?? 'manual', handlers: handlers.length, graceMs: gracePeriodMs })
 
   // hardKill 보호 — hardKillMs 초과 시 강제 종료
+  const hardKillAt = Date.now() + hardKillMs
   const hardKillTimer = setTimeout(() => {
-    console.error('[mega-shutdown] grace period exceeded, force exit(1)')
+    logShutdown('error', 'grace period exceeded — force exit(1)', { hardKillMs })
     process.exit(1)
   }, hardKillMs)
   hardKillTimer.unref()
 
-  // LIFO 순서로 hook 실행 (last registered runs first)
-  for (let i = handlers.length - 1; i >= 0; i--) {
-    const { name, fn } = handlers[i]
-    if (exitedHandlers.has(i)) continue
-    try {
-      console.log(`[mega-shutdown] running '${name}'`)
-      await Promise.race([
-        Promise.resolve(fn()),
-        new Promise((_, reject) =>
-          setTimeout(() => reject(new Error('handler timeout')), gracePeriodMs).unref(),
-        ),
-      ])
-      exitedHandlers.add(i)
-      console.log(`[mega-shutdown] '${name}' done`)
-    } catch (err) {
-      // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
-      console.warn(`[mega-shutdown] '${name}' failed (continuing):`, err?.message ?? err)
+  // stage 순서(SHUTDOWN_STAGES)대로 실행, 같은 stage 안에서는 등록 역순(LIFO).
+  // 실패 격리는 2단 — hook 실패는 warn 후 같은 stage 의 다음 hook 으로, stage 의 실패 수는
+  // stage done 로그에 집계된다(한 stage 가 망가져도 다음 stage 는 항상 진행).
+  for (const stage of SHUTDOWN_STAGES) {
+    /** @type {Array<{ name: string, fn: () => Promise<void> | void, stage: string }>} */
+    const staged = []
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      if (handlers[i].stage === stage && !exitedHandlers.has(handlers[i])) staged.push(handlers[i])
     }
+    if (staged.length === 0) continue
+    const stageStartedAt = Date.now()
+    logShutdown('info', `stage '${stage}' starting`, { stage, hooks: staged.length })
+    let failed = 0
+    for (const entry of staged) {
+      const { name, fn } = entry
+      // hook 별 대기 예산 — gracePeriodMs 를 기본으로 하되 hardKill 데드라인을 넘기지 않게 남은
+      // 시간으로 캡한다(여유 HARD_KILL_MARGIN_MS). 앞 hook/stage 들이 grace 를 소진해도 뒤 hook 이
+      // "시작조차 못 한 채" hardKill 로 잘리지 않고, 루프가 데드라인 전에 끝나 정상 exit 한다.
+      const budgetMs = Math.max(0, Math.min(gracePeriodMs, hardKillAt - HARD_KILL_MARGIN_MS - Date.now()))
+      try {
+        logShutdown('info', `running hook '${name}'`, { hook: name, stage })
+        await Promise.race([
+          Promise.resolve(fn()),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('handler timeout')), budgetMs).unref(),
+          ),
+        ])
+        exitedHandlers.add(entry)
+        logShutdown('info', `hook '${name}' done`, { hook: name, stage })
+      } catch (err) {
+        // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
+        failed++
+        logShutdown('warn', `hook '${name}' failed (continuing)`, { hook: name, stage, err: /** @type {any} */ (err)?.message ?? err })
+      }
+    }
+    logShutdown('info', `stage '${stage}' done`, { stage, tookMs: Date.now() - stageStartedAt, failed })
   }
 
   clearTimeout(hardKillTimer)
-  console.log(`[mega-shutdown] complete, exit(${exitCode})`)
+  logShutdown('info', `shutdown complete — exit(${exitCode})`, { exitCode })
   process.exit(exitCode)
 }
 
+/**
+ * 전역 에러 핸들러(unhandledRejection/uncaughtException)가 fatal 로그에 쓸 로거를 주입한다(ADR-178).
+ * boot 이 pino 공유 인스턴스(appLogger)를 만들 때 호출한다. 미호출이면 핸들러는 console.error 로 폴백한다.
+ * @param {ShutdownLogger | null | undefined} logger - pino 호환 로거(info/warn/error/fatal 사용) 또는 null.
+ * @returns {void}
+ */
+function setLogger(logger) {
+  shutdownLogger = logger ?? null  
+}
+
 /**
  * 테스트용 — 등록된 hook 수 (디버그).
  * @returns {number}
@@ -191,6 +295,12 @@ function registeredCount() {
  */
 function _reset() {
   handlers.length = 0
+  // 시그널 리스너도 떼어낸다 — 남겨두면 reset 후 재-setup 시 리스너가 누적돼 시그널 1회에
+  // now() 가 2회 불리고, 두 번째가 M-3(즉시 force exit 1)로 처리된다.
+  for (const { sig, fn } of signalHandlers) {
+    process.removeListener(/** @type {any} */ (sig), fn)
+  }
+  signalHandlers = []
   signalsRegistered = false
   isShuttingDownFlag = false
   gracePeriodMs = 30_000
@@ -202,6 +312,7 @@ function _reset() {
   unhandledRejectionHandler = null
   uncaughtExceptionHandler = null
   globalErrorsRegistered = false
+  shutdownLogger = null
 }
 
 /**
@@ -209,11 +320,13 @@ function _reset() {
  * docs/10·07 시퀀스가 `MegaShutdown.now()` 형태이므로 객체로 통일 (M-4).
  */
 export const MegaShutdown = {
+  STAGES: SHUTDOWN_STAGES,
   register,
   unregister,
   isShuttingDown,
   setupSignals,
   setupGlobalErrorHandlers,
+  setLogger,
   now,
   registeredCount,
   _reset,

package/src/lib/mega-tracing.js

@@ -21,14 +21,23 @@
  *   `enterWith` 방식이 공유 동기 실행을 오염시켜 sibling 을 잘못 묶던 문제(스모크로 확인)를 구조적으로
  *   제거한다. 이 seam 은 ADR-077 의 `_instrument` 에 추가된 **단 한 줄(run 위임)** 이다(ADR-114, 오너 결정).
  *
- * # 신규 의존성 (ADR-114 + ADR-126 보강)
+ * # W3C trace context 전파 (ADR-196 — F5 audit O-1)
+ *   서비스 경계를 넘는 분산 추적: inbound 는 {@link extractRemoteContext} 가 `traceparent`/`tracestate`
+ *   헤더를 부모 컨텍스트로 복원해 HTTP 루트 span 이 게이트웨이/업스트림 trace 에 이어지고, outbound 는
+ *   {@link propagationHeaders}(= `ctx.tracer.propagationHeaders()`)가 현재 활성 span 을 헤더로 직렬화해
+ *   하류 HTTP 호출(fetch 등)에 싣는다. 포맷·파싱은 검증된 `W3CTraceContextPropagator`(@opentelemetry/core)
+ *   에 위임한다(P1 — 직접 파싱 금지). 무효 헤더는 무시(새 루트 — fail-safe), 옵트인 OFF 면 0 비용.
+ *
+ * # 신규 의존성 (ADR-114 + ADR-126 보강 + ADR-196)
  *   `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, `@opentelemetry/resources`,
  *   `@opentelemetry/semantic-conventions`, `@opentelemetry/exporter-trace-otlp-http`(OTLP exporter),
- *   `@opentelemetry/exporter-zipkin`(Zipkin exporter, ADR-126 보강 — 사용자 승인). audit 신규 0건.
+ *   `@opentelemetry/exporter-zipkin`(Zipkin exporter, ADR-126 보강 — 사용자 승인),
+ *   `@opentelemetry/core`(W3C propagator, ADR-196 — 사용자 승인. 기존 2.x 라인 transitive 의 직접 승격).
  *
  * @module lib/mega-tracing
  */
-import { trace, ROOT_CONTEXT, SpanKind, SpanStatusCode } from '@opentelemetry/api'
+import { trace, ROOT_CONTEXT, SpanKind, SpanStatusCode, isSpanContextValid, defaultTextMapGetter, defaultTextMapSetter } from '@opentelemetry/api'
+import { W3CTraceContextPropagator } from '@opentelemetry/core'
 import {
   BasicTracerProvider,
   SimpleSpanProcessor,
@@ -40,14 +49,8 @@ import {
   TraceIdRatioBasedSampler,
   ParentBasedSampler,
 } from '@opentelemetry/sdk-trace-base'
-import { resourceFromAttributes } from '@opentelemetry/resources'
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-  ATTR_DB_SYSTEM_NAME,
-  ATTR_DB_QUERY_TEXT,
-  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
-} from '@opentelemetry/semantic-conventions'
+import { ATTR_DB_SYSTEM_NAME, ATTR_DB_QUERY_TEXT } from '@opentelemetry/semantic-conventions'
+import { buildOtelResource } from './otel-resource.js'
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 import { ZipkinExporter } from '@opentelemetry/exporter-zipkin'
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -80,6 +83,48 @@ function getActiveContext() {
   return activeContextStore.getStore() ?? ROOT_CONTEXT
 }
 
+/** W3C trace context propagator(무상태) — traceparent/tracestate 파싱·직렬화 정본 구현(ADR-196). */
+const w3cPropagator = new W3CTraceContextPropagator()
+
+/**
+ * inbound 헤더의 `traceparent`(/`tracestate`)를 부모 OTel Context 로 복원한다(ADR-196, W3C trace context).
+ *
+ * 게이트웨이/업스트림이 보낸 trace 에 HTTP 루트 span 을 잇는 입구다 — {@link enterHttpSpan} 의 `headers`
+ * 옵션이 이 함수를 거친다. 헤더가 없거나 형식이 무효면 `undefined`(호출부가 새 루트로 시작 — fail-safe,
+ * 잘못된 외부 입력이 추적을 깨지 않게). 옵트인 OFF 면 `undefined`(0 비용).
+ *
+ * 비율 샘플링(`traceidratio`)은 `ParentBasedSampler` 라 복원된 원격 부모의 sampled flag 를 따른다 —
+ * 업스트림이 샘플한 trace 는 여기서도 기록되고, 버린 trace 는 여기서도 버려져 trace 가 반토막 나지 않는다.
+ *
+ * @param {Record<string, string | string[] | undefined>} headers - `req.headers`(대소문자 무관 키).
+ * @returns {import('@opentelemetry/api').Context | undefined} 유효한 원격 부모 컨텍스트, 없으면 undefined.
+ */
+export function extractRemoteContext(headers) {
+  if (state === null) return undefined
+  if (!headers || typeof headers !== 'object') return undefined
+  const ctx = w3cPropagator.extract(ROOT_CONTEXT, headers, defaultTextMapGetter)
+  const sc = trace.getSpanContext(ctx)
+  if (!sc || !isSpanContextValid(sc)) return undefined // 무효 traceparent — 새 루트로(fail-safe).
+  return ctx
+}
+
+/**
+ * 현재 활성 span 을 outbound 헤더(`traceparent`/`tracestate`)로 직렬화해 carrier 에 채운다(ADR-196).
+ *
+ * 하류 HTTP 호출에 trace 를 잇는 출구다 — `fetch(url, { headers: ctx.tracer.propagationHeaders() })`.
+ * 활성 span 이 없거나 옵트인 OFF 면 carrier 를 그대로 반환(주입 없음 — 헤더 오염 없음).
+ *
+ * @param {Record<string, string>} [carrier={}] - 채울 헤더 객체(기존 키 보존, traceparent/tracestate 만 추가).
+ * @returns {Record<string, string>} carrier(체이닝용 동일 객체).
+ * @example
+ *   const res = await fetch(downstreamUrl, { headers: MegaTracing.propagationHeaders({ accept: 'application/json' }) })
+ */
+export function propagationHeaders(carrier = {}) {
+  if (state === null) return carrier
+  w3cPropagator.inject(getActiveContext(), carrier, defaultTextMapSetter)
+  return carrier
+}
+
 /**
  * 비활성(옵트인 OFF) 시 사용자 코드에 넘길 **no-op span** — 메서드는 다 있지만 아무것도 기록 안 함.
  * `ctx.tracer.span(name, (span) => span.setAttribute(...))` 가 OFF 에서도 깨지지 않게 한다.
@@ -169,12 +214,8 @@ export function init(opts = /** @type {any} */ ({})) {
   const { exporter, processorKind } = buildExporter(opts)
   const SpanProcessor = processorKind === 'batch' ? BatchSpanProcessor : SimpleSpanProcessor
 
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: serviceName,
-    ...(typeof opts.version === 'string' ? { [ATTR_SERVICE_VERSION]: opts.version } : {}),
-    ...(typeof opts.environment === 'string' ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: opts.environment } : {}),
-    ...(opts.attributes && typeof opts.attributes === 'object' ? opts.attributes : {}),
-  })
+  // resource 조립은 메트릭과 공유하는 단일 출처(otel-resource.js, ADR-196) — 두 SDK 간 드리프트 방지.
+  const resource = buildOtelResource({ serviceName, version: opts.version, environment: opts.environment, attributes: opts.attributes })
 
   const provider = new BasicTracerProvider({
     resource,
@@ -411,13 +452,17 @@ export function enterSpan(name, opts = {}) {
  * 기록(`setError`), `onResponse` 에서 상태코드와 함께 닫는다(`finish`). HTTP 시맨틱(5xx=ERROR)을 한곳에
  * 모아 배선 코드(mega-app)가 OTel enum 을 안 만지게 한다. 옵트인 OFF 면 no-op 핸들.
  *
- * @param {{ method: string, route: string, path: string, host?: string, app: string }} info
+ * `headers` 를 주면 inbound `traceparent` 를 부모로 복원해({@link extractRemoteContext}, ADR-196) 루트
+ * span 이 업스트림 trace 에 이어진다 — 무효/부재면 종전대로 새 루트.
+ *
+ * @param {{ method: string, route: string, path: string, host?: string, app: string, headers?: Record<string, string | string[] | undefined> }} info
  * @returns {{ span: import('@opentelemetry/api').Span, setError: (err: unknown) => void, finish: (statusCode: number) => void }}
  */
-export function enterHttpSpan({ method, route, path, host, app }) {
+export function enterHttpSpan({ method, route, path, host, app, headers }) {
   if (state === null) return /** @type {any} */ (NOOP_HTTP_HANDLE)
   const handle = enterSpan(`http.${method} ${route}`, {
     kind: SpanKind.SERVER,
+    parent: extractRemoteContext(headers ?? {}),
     attributes: {
       'http.request.method': method,
       'http.route': route,
@@ -476,6 +521,8 @@ export function logMixin() {
  */
 export const tracer = Object.freeze({
   span,
+  /** outbound 헤더에 traceparent/tracestate 주입(ADR-196) — `fetch(url, { headers: ctx.tracer.propagationHeaders() })`. */
+  propagationHeaders,
   /** @returns {import('@opentelemetry/api').Span | undefined} 현재 활성 span(없으면 undefined — 03-api-spec §10). */
   activeSpan() {
     if (state === null) return undefined

package/src/lib/mega-worker.js

@@ -479,7 +479,11 @@ export class MegaWorker extends EventEmitter {
 
   /** 비정상 exit 처리(정상 종료 code 0 는 stop 경로에서만 기대). @param {WorkerHandle} handle @param {number|null} code */
   #onExit(handle, code) {
-    if (this.#stopping || handle.down) return // 종료 중 terminate 로 인한 exit 은 정상.
+    if (handle.down) return // terminate 로 인한 exit 은 정상(이중 발화 가드).
+    // stop() 진행 중 crash 도 #onWorkerDown 으로 보낸다 — in-flight task 를 reject(→ _notify)해야
+    // stop() 의 완료 대기(allSettled)가 풀린다. 예전엔 #stopping 이면 통째로 무시해 그 task 가 영영
+    // settle 되지 않아 stop() 이 hang 했다(상위 MegaShutdown 타임아웃으로만 회수). respawn/drain 은
+    // #scheduleRespawn/#drainIfDead 의 자체 #stopping 가드가 막으므로 종료 중 부작용이 없다.
     this.#onWorkerDown(handle, new Error(`worker exited unexpectedly (code ${code})`))
   }