mega-framework 0.1.6 → 0.1.8

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
@@ -47,23 +74,30 @@ let uncaughtExceptionHandler = 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 수.
  */
@@ -99,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()
@@ -118,12 +156,23 @@ 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 err = reason instanceof Error ? reason : new Error(`unhandledRejection: ${String(reason)}`)
+    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) => {
+    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 })
   }
@@ -173,30 +222,49 @@ async function now({ signal, exitCode = 0 } = {}) {
   logShutdown('info', 'shutdown starting', { signal: signal ?? 'manual', handlers: handlers.length, graceMs: gracePeriodMs })
 
   // hardKill 보호 — hardKillMs 초과 시 강제 종료
+  const hardKillAt = Date.now() + hardKillMs
   const hardKillTimer = setTimeout(() => {
     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 {
-      logShutdown('info', `running hook '${name}'`, { hook: name })
-      await Promise.race([
-        Promise.resolve(fn()),
-        new Promise((_, reject) =>
-          setTimeout(() => reject(new Error('handler timeout')), gracePeriodMs).unref(),
-        ),
-      ])
-      exitedHandlers.add(i)
-      logShutdown('info', `hook '${name}' done`, { hook: name })
-    } catch (err) {
-      // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
-      logShutdown('warn', `hook '${name}' failed (continuing)`, { hook: name, err: /** @type {any} */ (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)
@@ -227,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
@@ -246,6 +320,7 @@ function _reset() {
  * docs/10·07 시퀀스가 `MegaShutdown.now()` 형태이므로 객체로 통일 (M-4).
  */
 export const MegaShutdown = {
+  STAGES: SHUTDOWN_STAGES,
   register,
   unregister,
   isShuttingDown,

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

@@ -16,7 +16,9 @@
  *     프로세스 메모리 격리), process=`child_process.fork`(완전 격리, 더 무거움). 둘 다 node 빌트인(의존성 0).
  *   - **풀 정책** — `static poolSize`(디폴트 `os.cpus().length - 1`, 최소 1). 작업 큐 + 가용 워커에 디스패치.
  *   - **crash 자동 재시작** — 워커가 예기치 않게 죽으면 in-flight task 를 `worker.crashed` 로 reject 하고
- *     `static maxRestarts`(디폴트 5)까지 교체 워커를 띄운다(MegaJobWorker M-1 패턴 정합).
+ *     `static maxRestarts`(디폴트 5)/`static restartWindowMs`(디폴트 60s) **슬라이딩 윈도우** 안에서만
+ *     교체 워커를 띄운다 — 윈도우 내 한도 초과 = crash-loop 으로 보고 포기(MegaCluster 정책 통일).
+ *     산발 crash(윈도우 밖)는 한도를 소모하지 않아 장수 프로세스의 풀이 영구 축소되지 않는다.
  *   - **graceful shutdown** — `stop()`: 새 `run()` 거부 + 큐 대기분 `worker.stopped` reject + in-flight 완료
  *     대기(allSettled) → 워커 terminate. `MegaShutdown` 통합은 workers-manager 가 배선.
  *
@@ -57,6 +59,14 @@ const DEFAULT_POOL_SIZE = Math.max(1, os.cpus().length - 1)
 /** crash 시 풀 전체에서 허용하는 교체 워커 재시작 총량 디폴트. */
 const DEFAULT_MAX_RESTARTS = 5
 
+/**
+ * crash 교체 판정 윈도우 기본값(ms) — 60초. `maxRestarts` 는 이 윈도우 **안의** 교체 횟수 상한이다
+ * (수명 누적이 아님). 누적 카운터면 몇 주 간격의 산발 crash 도 한도를 소모해 장수 프로세스의 풀이
+ * 영구 축소되다 `pool_exhausted` 로 죽는다 — crash-loop(즉시 연속 사망)만 막으면 되는 안전망이므로
+ * 시간 윈도우 판정이 맞다(MegaCluster 의 rapid-crash 슬라이딩 윈도우와 정책 통일).
+ */
+const DEFAULT_RESTART_WINDOW_MS = 60_000
+
 /**
  * @typedef {object} WorkerHandle - 풀 안의 워커 1개 핸들.
  * @property {number} id - 핸들 식별자(로그/디버그).
@@ -94,7 +104,8 @@ export class MegaWorker extends EventEmitter {
   /** @type {boolean} */ #stopping = false
   /** @type {number} */ #nextTaskId = 1
   /** @type {number} */ #nextHandleId = 1
-  /** @type {number} crash 교체 누적. */ #restarts = 0
+  /** @type {number[]} crash 교체 시각(epoch ms) 슬라이딩 윈도우 — restartWindowMs 밖은 판정 시 제거. */
+  #restartTimes = []
   /** @type {number} 진행 중인 교체 spawn 수(일시적 풀 0 상태에서 run 을 큐잉할지 판단). */ #pendingRespawns = 0
 
   /**
@@ -130,12 +141,18 @@ export class MegaWorker extends EventEmitter {
     return typeof p === 'number' ? p : DEFAULT_POOL_SIZE
   }
 
-  /** @returns {number} crash 교체 허용 총량. */
+  /** @returns {number} 윈도우({@link MegaWorker#restartWindowMs}) 내 crash 교체 허용 횟수. */
   get maxRestarts() {
     const r = /** @type {any} */ (this.constructor).maxRestarts
     return Number.isInteger(r) && r >= 0 ? r : DEFAULT_MAX_RESTARTS
   }
 
+  /** @returns {number} crash 교체 판정 슬라이딩 윈도우(ms). `static restartWindowMs` 로 조정. */
+  get restartWindowMs() {
+    const w = /** @type {any} */ (this.constructor).restartWindowMs
+    return Number.isInteger(w) && w > 0 ? w : DEFAULT_RESTART_WINDOW_MS
+  }
+
   /** @returns {boolean} start() 후 stop() 전이면 true. */
   get isStarted() {
     return this.#started
@@ -479,7 +496,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})`))
   }
 
@@ -507,8 +528,14 @@ export class MegaWorker extends EventEmitter {
    * @returns {void}
    */
   #scheduleRespawn() {
-    if (this.#stopping || this.#restarts >= this.maxRestarts) return
-    this.#restarts++
+    if (this.#stopping) return
+    // 슬라이딩 윈도우 판정 — 윈도우 밖 기록을 비우고 남은 횟수가 한도면 crash-loop 으로 보고 포기.
+    // (수명 누적이 아니라서 산발 crash 는 풀을 영구 축소시키지 않는다 — MegaCluster 정책 통일.)
+    const now = Date.now()
+    const windowStart = now - this.restartWindowMs
+    this.#restartTimes = this.#restartTimes.filter((t) => t >= windowStart)
+    if (this.#restartTimes.length >= this.maxRestarts) return
+    this.#restartTimes.push(now)
     this.#pendingRespawns++
     this.#spawn()
       .then((h) => {

package/src/lib/otel-resource.js

@@ -0,0 +1,36 @@
+// @ts-check
+/**
+ * OTel Resource 공유 빌더 — 트레이싱·메트릭 SDK 의 단일 출처 (ADR-196, F5 audit O-SDK 단일화).
+ *
+ * `MegaTracing.init`/`MegaMetrics.init` 이 각자 동일한 resource 조립 블록을 들고 있어 service.name 류
+ * 시맨틱 키 매핑이 두 곳에서 드리프트할 수 있었다. 본 모듈이 그 조립을 한 곳으로 모은다 — 두 SDK 가
+ * 같은 입력(`serviceName`/`version`/`environment`/`attributes`)에 항상 같은 resource 속성을 낸다.
+ * (전면 NodeSDK 채택은 자동 instrumentation 의존이 끌려와 zero-dep 방침과 충돌 — 자체 일원화로 결정.)
+ *
+ * @module lib/otel-resource
+ */
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
+} from '@opentelemetry/semantic-conventions'
+
+/**
+ * 공통 입력 → OTel Resource. 시크릿은 attributes 에 싣지 말 것(exporter 로 평문 전송됨).
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**(호출부가 선검증). `service.name` 속성.
+ * @param {string} [opts.version] - `service.version`.
+ * @param {string} [opts.environment] - `deployment.environment.name`.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지).
+ * @returns {import('@opentelemetry/resources').Resource}
+ */
+export function buildOtelResource({ serviceName, version, environment, attributes }) {
+  return resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: serviceName,
+    ...(typeof version === 'string' ? { [ATTR_SERVICE_VERSION]: version } : {}),
+    ...(typeof environment === 'string' ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: environment } : {}),
+    ...(attributes && typeof attributes === 'object' ? attributes : {}),
+  })
+}