mega-framework 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/.env

@@ -1,27 +1,175 @@
+# =============================================================================
+# sample-crud 환경변수 (.env) — 프레임워크 전체 설정 참조
+# =============================================================================
+# CLI(`mega start`/`worker`/`scheduler`)가 부팅 전에 이 파일을 process.env 로
+# 자동 로드한다(Node `process.loadEnvFile`, 20.6+, ADR-152). 이미 설정된 실제
+# 환경변수는 덮어쓰지 않는다(실 env 우선 — `--env-file` 과 동일). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ 아래 시크릿/비밀번호는 로컬 도커 데모 전용. 운영 배포 전 반드시 교체할 것.
+# =============================================================================
+
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
-DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
-MEGA_CLUSTER_WORKERS=8
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
 SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+
+
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
+DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:dkTkqkfl12@localhost:3306/mega_test
+
+
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:dkTkqkfl12@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:dkTkqkfl12@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:dkTkqkfl12@localhost:6379/1
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
-MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/4
+
+
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
-ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
+
 
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/cli/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
 MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
-MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
 MEGA_WSHUB_PORT=3100
 MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+MEGA_WSHUB_HEARTBEAT_MS=25000
+MEGA_WSHUB_MAX_PAYLOAD=1048576
+MEGA_WSHUB_COMPRESSION=false
+MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
 MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
+
 
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=true
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
+
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
 
-BRIDGE_ID=crud-1
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=dkTkqkfl12
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=dkTkqkfl12
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=dkTkqkfl12
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string

package/sample/crud/.env.example

@@ -1,50 +1,175 @@
-# sample-crud 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+# =============================================================================
+# sample-crud 환경변수 (.env.example) — 프레임워크 전체 설정 참조
+# =============================================================================
+# 복사해서 `.env` 로 쓰고 시크릿/비밀번호를 실제 값으로 채운다. CLI(`mega start`/`worker`/
+# `scheduler`)가 부팅 전에 `.env` 를 process.env 로 자동 로드한다(Node `process.loadEnvFile`,
+# 20.6+, ADR-152). 이미 설정된 실제 환경변수는 덮어쓰지 않는다(실 env 우선). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ change-me 로 표시된 값은 반드시 교체할 것(시크릿은 32자 이상 랜덤 권장).
+# =============================================================================
 
-# HTTP 포트
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
+SESSION_SECRET=change-me-to-a-long-random-secret-at-least-32-chars
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
 
-# cluster 워커 프로세스 수(ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일 프로세스.
-# MEGA_CLUSTER_WORKERS=max
 
-# Postgres 연결 (필수) — services.databases.primary.url 이 읽는다.
-# 예: docker compose 의 postgres
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
 DATABASE_URL=postgres://mega:change-me@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:change-me@localhost:3306/mega_test
 
-# 세션 쿠키 HMAC 서명 시크릿 (필수, ADR-155) — server.sessionSecret 이 읽는다. 충분히 긴 랜덤 문자열.
-SESSION_SECRET=change-me-to-a-long-random-secret
 
-# Redis 연결 (필수, ADR-155/157) — 세션 store·brute-force·/demo/redis·cron·jobs 데모 캐시 + 분산 락(redlock).
-# DB 인덱스를 분리해 키 충돌을 피한다(/0 세션, /1 demo, /2 rate, /3 lock).
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:change-me@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:change-me@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:change-me@localhost:6379/1
-# 분산 락(redlock, ADR-113) — services.caches.lock 이 읽는다. /demo/cron 스케줄의 클러스터 중복방지(leader election).
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:change-me@localhost:6379/3
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:change-me@localhost:6379/4
+
 
-# NATS 연결 (필수, ADR-119) — services.buses.jobs.url 이 읽는다. /demo/jobs 잡 큐(EmailJob)의 JetStream 백엔드.
-# `mega worker` 프로세스가 소비하고 웹은 enqueue 한다. JetStream 활성 NATS 서버 필요(nats-server -js).
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
 
-# MongoDB 연결 (필수, ADR-157) — services.databases.mongo.url 이 읽는다. /demo/notes 데모 컬렉션의 백엔드.
-# url path 의 dbName(mega_test)을 어댑터가 추출한다. authSource 는 인증 DB(보통 admin).
-MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
 
-# ASP WebSocket 데모 masterSecret (필수, ADR-158) — asp.masterSecret 이 읽는다. /ws/chat 의 E:/P:
-# 프레임 키 유도에 쓰인다. ASP 는 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 만드는 공유-키
-# 구조라 데모 페이지가 이 값을 브라우저에 주입한다 — 운영 secret 과 섞이지 않게 데모 전용 값을 둔다.
-ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/cli/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
+MEGA_WSHUB_TOKENS=change-me-hub-token
+MEGA_WSHUB_PORT=3100
+MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+# MEGA_WSHUB_HEARTBEAT_MS=25000
+# MEGA_WSHUB_MAX_PAYLOAD=1048576
+# MEGA_WSHUB_COMPRESSION=false
+# MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
+MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=change-me-hub-token
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
 
-# OpenTelemetry 트레이싱 (선택, ADR-104/126/163) — /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 으로
-# 잇는다. 미설정/false 면 트레이싱 OFF(데모는 비활성 안내를 보여줌). docker 의 otel-collector(:4318 OTLP HTTP)·
-# zipkin(:9411) 가동 시 true 로 켠다. exporter otlp → collector → zipkin 경로로 span 이 전달된다.
+
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=false
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
-# Zipkin UI API base — /demo/tracing 이 trace 딥링크 base(.../api/v2 를 떼 UI 루트)로 쓴다.
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
 
-# 업로드 저장 디렉터리 (선택, ADR-163) — /demo/upload 이 파일을 저장할 위치. 상대경로는 프로젝트 루트
-# (cwd) 기준, 절대경로면 그대로. 미설정 시 var/uploads(.gitignore). 다운로드도 같은 위치에서 소스로 읽는다.
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
+
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=change-me
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=change-me
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=change-me
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=change-me
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=change-me
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string

package/sample/crud/mega.config.js

@@ -15,6 +15,13 @@ export default {
     port: Number(process.env.PORT ?? 3000),
     // 세션 쿠키 HMAC 서명 시크릿(global 스코프, ADR-129). boot 이 앱에 주입한다. .env 의 SESSION_SECRET.
     sessionSecret: process.env.SESSION_SECRET,
+    // (예시·미사용) listen 호스트 — 기본 '0.0.0.0'. `mega start --host H`(CLI)가 우선.
+    // host: '0.0.0.0',
+    // (예시·미사용) cluster 워커 수 — CLI `--cluster` > .env MEGA_CLUSTER_WORKERS > 이 값(ADR-154). 정수 N | 'max'.
+    // cluster: 'max',
+    // (예시·미사용) 메트릭/트레이싱 resource 의 service.name·version(health.serviceName 미지정 시 폴백).
+    // serviceName: 'sample-crud',
+    // version: '0.1.0',
   },
 
   // ASP(Application-layer Secure Protocol) masterSecret — global 스코프 시크릿(ADR-127, scope-registry).
@@ -24,6 +31,8 @@ export default {
   // 이 값을 브라우저에 주입한다 — 그래서 운영 secret 과 분리된 데모 전용 값을 .env 의 ASP_MASTER_SECRET 에 둔다.
   asp: {
     masterSecret: process.env.ASP_MASTER_SECRET,
+    // (예시·미사용) HTTP body/query 암호화 옵션(enabledPaths·driftMs·nonceCache 등)은 **앱 스코프** —
+    //   apps/<app>/app.config.js 의 asp.http 에 둔다. 여기 global 블록엔 masterSecret 만(scope-registry).
   },
 
   // 전역 어댑터(ADR-102/106/109) — globalKey 로 선언, 앱은 app.config.js 의 별명으로 참조.
@@ -33,6 +42,11 @@ export default {
       primary: {
         driver: 'postgres',
         url: process.env.DATABASE_URL,
+        // (예시·미사용) url 대신 discrete 도 가능: { host, port, user, password, database } (url 과 상호배타).
+        // (예시·미사용) 공통 풀 인터페이스 — 드라이버별 키로 자동 매핑(ADR-109). 단위 *Ms=밀리초.
+        // pool: { min: 0, max: 10, idleTimeoutMs: 10_000 },
+        // (예시·미사용) 드라이버 네이티브 옵션 passthrough(pg=snake_case).
+        // options: { ssl: false, statement_timeout: 30_000 },
       },
       // DB 'mongo' — Document DB 어댑터(ADR-108). notes 데모 컬렉션(Note 모델 static adapter='mongo')의 공유
       // 인스턴스. url path 의 dbName(mega_test)을 어댑터가 추출한다. .env 의 MONGO_URL(authSource=admin).
@@ -40,6 +54,12 @@ export default {
         driver: 'mongodb',
         url: process.env.MONGO_URL,
       },
+      // (예시·미사용) MariaDB 어댑터(ADR-105). 쓰려면 주석 해제 + .env 의 MARIA_URL 설정.
+      // 모델은 static adapter='maria'(globalKey)로 닿고, app.config.js databases 에 별명 추가.
+      // maria: {
+      //   driver: 'mariadb',
+      //   url: process.env.MARIA_URL,
+      // },
     },
     caches: {
       // redis 캐시 'rate' — brute-force(ctx.bruteForce, ADR-049/130)의 원자적 INCR 백엔드. .env 의 REDIS_RATE_URL(db 2).
@@ -60,6 +80,12 @@ export default {
         driver: 'redis',
         url: process.env.REDIS_LOCK_URL,
       },
+      // (예시·미사용) 범용 캐시 — 일반 키/값 캐싱이 필요하면 주석 해제 + .env 의 REDIS_CACHE_URL 설정.
+      // 기존 캐시(rate/demo/lock)와 키 충돌을 피해 별도 논리 DB(/4 등)를 권장. app.config.js caches 에 별명 추가.
+      // cache: {
+      //   driver: 'redis',
+      //   url: process.env.REDIS_CACHE_URL,
+      // },
     },
     // NATS 버스 'jobs' — 잡 큐(EmailJob, ADR-119)의 JetStream 백엔드. producer(웹)는 ctx.bus('jobs').native(nc)로
     // enqueue, consumer(`mega worker`)는 같은 버스로 소비한다. .env 의 NATS_JOBS_URL.
@@ -68,6 +94,11 @@ export default {
         driver: 'nats',
         url: process.env.NATS_JOBS_URL,
       },
+      // (예시·미사용) 이벤트 버스 — pub/sub 등 두 번째 NATS 버스가 필요하면 주석 해제 + .env 의 NATS_EVENTS_URL.
+      // events: {
+      //   driver: 'nats',
+      //   url: process.env.NATS_EVENTS_URL,
+      // },
     },
     // 분산 락 'main' — redlock(ADR-113). caches.lock(Redis) 을 빌려 단일 노드 redlock 을 구성한다. /demo/cron
     // 스케줄(CronCounterSchedule.static lock)의 클러스터 중복방지(leader election)에 쓰인다.
@@ -79,6 +110,17 @@ export default {
     },
   },
 
+  // (예시·미사용) Embedded WS Hub(ADR-137) — `mega ws-hub` 별도 프로세스 대신 같은 프로세스에 허브를 띄움
+  //   (single-node). 켜면 app.config.js bridgeHub.url 을 이 host:port 로 맞춘다. acceptedTokens 필수(빈 값=throw).
+  // wsHub: {
+  //   enabled: true,
+  //   port: 3100,
+  //   host: '127.0.0.1',
+  //   acceptedTokens: (process.env.MEGA_WSHUB_TOKENS ?? '').split(',').filter(Boolean),
+  //   heartbeatMs: 25_000,
+  //   // compression: { enabled: false },
+  // },
+
   // ── 클러스터 전송 선택(ADR-176, 앱당 하나·상호배타) ───────────────────────────────────────────
   // 이 샘플은 현재 **WS Hub**(app.config 의 bridgeHub → `mega ws-hub` 서버, localhost:3100)로 채팅을
   // 클러스터 전파한다. boot 가 bridgeHub 를 보고 app.connectHub 를 자동 호출한다(개발자 배선 불요).
@@ -101,11 +143,20 @@ export default {
   // CPU 워커 풀(ADR-124) — `mega start`(boot)가 ctx.workers['hash'] 로 배선한다(config.workers).
   workers: [HashWorker],
 
+  // (예시·미사용) 플러그인 — 명시 등록만(auto-discovery 없음, ADR-079). 문자열 또는 { name, options }.
+  // plugins: [{ name: 'my-plugin', options: {} }],
+
   // pino 로깅(ADR-023/141) — console sink, dev pretty. redact 로 민감필드를 sink 출력 전 메인스레드에서
   // 마스킹한다(token/password/secret/authorization). /demo/logs 데모가 이 마스킹을 시연한다(ADR-163).
   logger: {
-    level: 'debug',
-    sinks: [{ type: 'console', pretty: true }],
+    level: process.env.LOG_LEVEL ?? 'info',
+    // sinks — 출력처 배열. console(dev pretty) 외에 file(pino-roll)·telegram sink 지원.
+    sinks: [
+      { type: 'console', pretty: true },
+      // (예시·미사용) 파일 sink — 날짜 로테이션 + keep N.
+      // { type: 'file', path: './logs/app.log', rotation: 'daily', keep: 14 },
+      // (예시·미사용) telegram sink — warn 이상 알림. botToken/chatId 는 .env 등 시크릿으로 주입(코드·git 직접 X).
+    ],
     redact: ['*.password', '*.token', '*.secret', '*.authorization', 'password', 'token', 'secret'],
   },
 
@@ -114,5 +165,13 @@ export default {
     exposeMetrics: true,
     metricsPath: '/metrics',
     metricsAllowList: ['127.0.0.1', '::1'],
+    // (예시·미사용) liveness/readiness 경로 — 기본 '/health' · '/health/ready'.
+    // paths: { live: '/health', ready: '/health/ready' },
+    // (예시·미사용) 메트릭 resource service.name — 미지정 시 server.serviceName → MEGA_OTEL_SERVICE_NAME 폴백.
+    // serviceName: 'sample-crud',
   },
+
+  // OpenTelemetry 분산 트레이싱 — **config 블록이 아니라 .env 의 MEGA_OTEL_\*** 로 설정한다
+  //   (MegaTracing.fromEnv, boot.js). MEGA_OTEL_ENABLED='true' + MEGA_OTEL_SERVICE_NAME 필수.
+  //   (`tracing` 키는 스키마엔 있으나 현재 부팅이 소비하지 않음 — 죽은 설정 회피 위해 블록을 두지 않음.)
 }

package/sample/crud/package.json

@@ -7,7 +7,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "dev": "NODE_ENV=development mega start",
+    "dev": "mega start --watch",
     "start": "NODE_ENV=production mega start",
     "migrate": "mega migrate",
     "migrate:down": "mega migrate:down",
@@ -25,4 +25,4 @@
     "concurrently": "^9.0.0",
     "vitest": "^4.0.0"
   }
-}
+}

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.4"
+  version "0.1.5"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

package/src/cli/index.js

@@ -21,6 +21,7 @@
 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'
@@ -32,6 +33,7 @@ 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 } from '../lib/mega-shutdown.js'
+import { buildLogger } from '../lib/mega-logger.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
 import { SCAFFOLD_COMMANDS, runScaffoldCommand } from './commands/scaffold.js'
 
@@ -39,7 +41,7 @@ import { SCAFFOLD_COMMANDS, runScaffoldCommand } from './commands/scaffold.js'
 export const USAGE = `mega — MEGA-FRAMEWORK CLI
 
 Usage:
-  mega start [--port N] [--host H] [--cluster N|max] [--root DIR]   앱 부팅 + HTTP listen (별칭: serve)
+  mega start [--port N] [--host H] [--cluster N|max] [--watch] [--root DIR]   앱 부팅 + HTTP listen (별칭: serve)
   mega worker [--root DIR]                         잡 소비 워커 런타임 호스트
   mega scheduler [--root DIR]                      분산 스케줄러 호스트
   mega migrate [--db KEY] [--root DIR]             pending 마이그레이션 일괄 적용(up)
@@ -63,6 +65,8 @@ Options:
   --host H      listen 호스트(start)
   --cluster X   워커 프로세스 수(start). 정수 N 또는 max(CPU 코어 수). 우선순위:
                 --cluster > MEGA_CLUSTER_WORKERS env > server.cluster config. 1/미지정=단일 프로세스.
+  --watch       dev watch 모드(start). 파일 변경 시 자동 재시작 — node 내장 --watch 로 자신을 재실행한다
+                (nodemon 불요). 단일 프로세스 강제 + NODE_ENV 미설정 시 development. apps/·mega.config.js 감시.
 `
 
 /** 프로젝트 `.env` 를 로드하지 않는 명령 — 스캐폴드 생성(new/g)·도움말. 그 외 런타임/부팅 명령은 로드. */
@@ -202,6 +206,51 @@ export function resolveHost(setting) {
   return setting
 }
 
+/**
+ * `mega start --watch` 가 자신을 `node --watch` 로 재실행해야 하는지 (ADR-182). `--watch` 플래그가 있고
+ * 아직 watch 하에 재실행되지 않았을 때만 true — 가드 env(`MEGA_WATCH_REEXEC`)로 무한재귀를 막는다.
+ * @param {Record<string, string|boolean>} flags
+ * @param {Record<string, string|undefined>} env
+ * @returns {boolean}
+ */
+export function shouldReexecForWatch(flags, env) {
+  return flags.watch === true && env.MEGA_WATCH_REEXEC !== '1'
+}
+
+/**
+ * `mega start --watch` → `node --watch … <self> start … --cluster 1` 재실행 명령을 빌드한다 (ADR-182).
+ *
+ * - `--watch` 인자는 **node 플래그**로 옮기고 mega 인자에선 제거한다.
+ * - **단일 프로세스 강제**(`--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[] }}
+ */
+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`(값 포함) 제거. */
+  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 (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] }
+}
+
 /**
  * `mega` CLI 진입점. 파싱 → 명령 분기. **이 함수는 process.exit 를 호출하지 않는다**(테스트 가능) —
  * exit code 를 반환하고, bin 래퍼가 `process.exitCode` 로 반영한다.
@@ -212,9 +261,11 @@ export function resolveHost(setting) {
  * @param {(msg: string) => void} [deps.err] - stderr writer(기본 console.error).
  * @param {string} [deps.cwd] - 기본 projectRoot(기본 process.cwd()).
  * @param {{ debug?: Function, info?: Function, warn?: Function }} [deps.logger]
+ * @param {Function} [deps.spawn] - child_process.spawn 주입(기본 node:child_process). `--watch` 재실행 테스트용.
+ * @param {string} [deps.selfPath] - mega 진입 스크립트 경로(기본 `process.argv[1]`). `--watch` 재실행 대상.
  * @returns {Promise<number>} exit code(0=성공, 1=실패/미지정 명령).
  */
-export async function runCli(argv, { out = console.log, err = console.error, cwd, logger } = {}) {
+export async function runCli(argv, { out = console.log, err = console.error, cwd, logger, spawn = nodeSpawn, selfPath = process.argv[1] } = {}) {
   const { _, flags } = parseArgs(argv)
   const command = _[0]
   const projectRoot = typeof flags.root === 'string' ? flags.root : (cwd ?? process.cwd())
@@ -232,6 +283,35 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
   }
 
   if (command === 'start' || command === 'serve') {
+    // dev watch (ADR-182) — `--watch` 면 자신을 `node --watch` 로 재실행한다. 부모는 부팅하지 않고 watcher
+    // 자식만 띄운 뒤 그 exit code 를 그대로 반영한다(가드 env 로 무한재귀 방지). 단일 프로세스 강제 +
+    // NODE_ENV 미설정 시 development 기본. 시그널은 자식으로 전달해 Ctrl+C 가 watcher 까지 닿게 한다.
+    if (shouldReexecForWatch(flags, 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 은 무의미 — 무시(비치명적).
+        }
+      }
+      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)
+        })
+      })
+    }
+
     // listen 포트/호스트는 부팅(어댑터 connect) 전에 fail-closed 검증한다 — 잘못된 값을 늦게(listen 시점)
     // cryptic 에러로 만나거나 silent 강등(특권/랜덤 포트)하지 않도록(per ADR-167 후속).
     const port = resolvePort(flags.port)
@@ -246,35 +326,51 @@ export async function runCli(argv, { out = console.log, err = console.error, cwd
     }
     const workers = resolveClusterWorkers(clusterSetting)
 
+    // 시작 확인 메시지 — pino 로거가 있으면 그쪽 info 로(구조적·sink 라우팅, ADR-180), 없으면 CLI stdout
+    // (`out`)으로 폴백한다. listen/forked 는 운영 라이프사이클 이벤트라 로그로 남기는 게 정합.
+    const announce = (/** @type {any} */ lg, /** @type {string} */ msg) => {
+      if (lg && typeof lg.info === 'function') lg.info(msg)
+      else out(`mega: ${msg}`)
+    }
+
     // 워커 부팅 함수 — 단일/클러스터 모드 공통. 클러스터에선 각 워커 프로세스가 이 함수를 실행한다.
     const bootListen = async () => {
-      const { server } = await bootApp(projectRoot, { listen: true, port, host, logger })
+      const { server, appLogger } = await bootApp(projectRoot, { listen: true, port, host, logger })
       MegaShutdown.register('mega-cli:server', async () => server.close())
       MegaShutdown.setupSignals()
       // 클러스터 워커면 메트릭 collect 응답기 설치(ADR-163) — 마스터의 집계 요청에 자기 메트릭 회신.
       // 단일 프로세스면 no-op(cluster.isWorker=false).
       installWorkerResponder()
-      return server
+      return { server, appLogger }
     }
 
     if (workers === null) {
       // 단일 프로세스(클러스터 비활성) — 기존 경로 유지.
-      const server = await bootListen()
-      out(`mega: listening on [${server.hosts.join(', ')}]`)
+      const { server, appLogger } = await bootListen()
+      announce(appLogger, `listening on [${server.hosts.join(', ')}]`)
       return 0
     }
 
     // 클러스터 모드 — 마스터는 워커 N개 fork·respawn·graceful 협응(MegaCluster), 각 워커가 bootApp+listen.
     // Node cluster 가 마스터의 공유 listen 소켓을 워커들에 분배하므로 SO_REUSEPORT 불필요(ADR-030/154).
     const mega = new MegaCluster({ instances: workers })
+    // 마스터 조율 로그(SIGINT 수신·워커 종료/respawn 등)를 pino 로(ADR-180). 마스터는 bootApp 을 안 해
+    // pino 인스턴스가 없으므로 config 로 직접 만든다. 워커는 bootApp 의 appLogger 를 쓰니 primary 에서만
+    // 만들어(워커당 중복 transport worker 회피) start 전에 주입한다.
+    /** @type {any} */ let masterLogger = null
+    if (mega.isPrimary()) {
+      const { global: masterGlobal } = await loadAndValidateConfig(projectRoot)
+      masterLogger = buildLogger(/** @type {any} */ (masterGlobal).logger)
+      mega.setLogger(masterLogger)
+    }
     await mega.start(async () => {
-      const server = await bootListen()
-      out(`mega: worker ${process.pid} listening on [${server.hosts.join(', ')}]`)
+      const { server, appLogger } = await bootListen()
+      announce(appLogger, `worker ${process.pid} listening on [${server.hosts.join(', ')}]`)
     })
     if (mega.isPrimary()) {
       // 마스터에 메트릭 집계기 설치(ADR-163) — 워커의 /metrics 요청을 받아 전 워커 합산해 회신.
       installPrimaryAggregator()
-      out(`mega: cluster master ${process.pid} forked ${workers} worker(s)`)
+      announce(masterLogger, `cluster master ${process.pid} forked ${workers} worker(s)`)
     }
     return 0
   }
@@ -352,6 +448,29 @@ export function collectRegistrations(global, host, kind) {
   return [...staticPart, ...dynamicPart]
 }
 
+/**
+ * CLI 호스트(worker/scheduler) 로거 배선 — `bin/mega.js` 는 `runCli` 에 logger 를 주입하지 않으므로
+ * (undefined), config 의 pino 로거를 만들어 종료 로그(`MegaShutdown.setLogger`)·flush 훅에 쓴다. 이로써
+ * `mega worker`/`mega scheduler` 의 자기 로그·종료 로그가 console 이 아니라 pino 로 나간다(ADR-180).
+ * 주입(테스트)이 있으면 그쪽을 그대로 쓰고 pino 는 만들지 않는다(side-effect 회피).
+ * @param {Object} global - global config(`logger` 보유 가능).
+ * @param {{ info?: Function, warn?: Function } | undefined} injectedLogger - 주입 로거(테스트) 또는 undefined.
+ * @returns {{ info?: Function, warn?: Function } | null} 호스트 로그에 쓸 로거(없으면 null).
+ */
+function wireHostLogger(global, injectedLogger) {
+  if (injectedLogger) return injectedLogger
+  const appLogger = buildLogger(/** @type {any} */ (global).logger)
+  if (appLogger) {
+    // 종료 시퀀스 로그를 pino 로(ADR-178) + graceful 시 로그 버퍼 flush. flush 훅은 LIFO 상 가장 먼저
+    // 등록 = 가장 나중 실행이라, 다른 hook 들이 로그를 남긴 뒤 마지막에 drain 된다.
+    MegaShutdown.setLogger(appLogger)
+    MegaShutdown.register('mega-logger', async () => {
+      await new Promise((resolve) => appLogger.flush(() => resolve(undefined)))
+    })
+  }
+  return appLogger
+}
+
 /**
  * `mega worker` 호스트 골격 — config + 어댑터 connect + ctx + `MegaJobWorker` 인스턴스 + graceful.
  * 등록 소스 = `config.jobs` + 플러그인 `mega.jobs.register` 분(`collectRegistrations`, ADR-123).
@@ -362,6 +481,7 @@ export function collectRegistrations(global, host, kind) {
 export async function runWorkerHost(projectRoot, logger) {
   // bootApp 과 같은 토대(config → 플러그인 install → 어댑터 connect → ctx).
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const log = wireHostLogger(global, logger)
   const worker = new MegaJobWorker({ ctx })
   // 잡 메트릭 (ADR-132) — prepareRuntime 이 health.exposeMetrics 시 이미 MegaMetrics.init 했고,
   // 옵트인 OFF 면 subscribeJobs 는 no-op() 을 반환한다. start 전에 구독해 enqueue(dispatch)부터 잡는다. 구독은
@@ -371,7 +491,7 @@ export async function runWorkerHost(projectRoot, logger) {
   // 미선언·중복을 부팅 시 fail-fast.
   const jobs = collectRegistrations(global, host, 'jobs')
   for (const JobClass of jobs) worker.register(/** @type {any} */ (JobClass))
-  logger?.info?.({ count: jobs.length }, 'worker.jobs registered')
+  log?.info?.({ count: jobs.length }, 'worker.jobs registered')
   await worker.start()
   MegaShutdown.register('mega-worker', async () => {
     await worker.stop()
@@ -388,12 +508,13 @@ export async function runWorkerHost(projectRoot, logger) {
  */
 export async function runSchedulerHost(projectRoot, logger) {
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
+  const log = wireHostLogger(global, logger)
   const scheduler = new MegaScheduler({ ctx })
   // 등록 소스(ADR-123) = config.schedules(정적) + 플러그인 host.listSchedules()(동적). register 가
   // cron 미선언·중복을 부팅 시 fail-fast.
   const schedules = collectRegistrations(global, host, 'schedules')
   for (const TaskClass of schedules) scheduler.register(/** @type {any} */ (TaskClass))
-  logger?.info?.({ count: schedules.length }, 'scheduler.schedules registered')
+  log?.info?.({ count: schedules.length }, 'scheduler.schedules registered')
   scheduler.start()
   MegaShutdown.register('mega-scheduler', async () => {
     await scheduler.stop()

package/src/core/boot.js

@@ -66,6 +66,7 @@ import { MegaWsHub } from '../cli/ws-hub.js'
  * @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('pino').Logger | null} appLogger - 공유 pino 로거(ADR-141, logger 비활성이면 null). CLI 시작 메시지 등에 재사용.
  */
 
 /**
@@ -188,6 +189,28 @@ export async function prepareRuntime(projectRoot, { ping = false, logger } = {})
   return { global, apps, host, ctx, wsHub }
 }
 
+/**
+ * `global.server` 의 운영 옵션을 각 앱 Fastify 인스턴스 옵션으로 매핑한다(ADR-181, 04-data-models
+ * §MegaServerConfig). 미지정 키는 생략해 Fastify 기본값을 따른다. boot 가 모든 MegaApp 에 동일 주입한다
+ * (port/host 는 MegaServer.listen 이, 아래 런타임 옵션은 Fastify 인스턴스가 소비).
+ *   - trustProxy / trustedProxies → Fastify `trustProxy`(프록시/LB 뒤 req.ip·X-Forwarded-* 신뢰).
+ *     trustedProxies(목록)가 있으면 그것을, 없으면 trustProxy(boolean/number/string)를 그대로 넘긴다.
+ *   - timeouts.requestMs → Fastify `requestTimeout`(요청 수신 제한, slow-loris 보호).
+ *   - keepAliveMs       → Fastify `keepAliveTimeout`(keep-alive 소켓 idle 제한, ALB 정합).
+ * @param {any} server - `global.server` config(없으면 빈 객체).
+ * @returns {{ trustProxy?: any, requestTimeout?: number, keepAliveTimeout?: number }}
+ */
+export function serverFastifyOptions(server) {
+  const s = server ?? {}
+  /** @type {any} */
+  const out = {}
+  const trust = s.trustedProxies !== undefined ? s.trustedProxies : s.trustProxy
+  if (trust !== undefined) out.trustProxy = trust
+  if (s.timeouts && s.timeouts.requestMs !== undefined) out.requestTimeout = s.timeouts.requestMs
+  if (s.keepAliveMs !== undefined) out.keepAliveTimeout = s.keepAliveMs
+  return out
+}
+
 /**
  * embedded wsHub 기동 (ADR-137) — `cfg.enabled === true` 일 때만 `MegaWsHub` 를 같은 프로세스에 띄우고
  * `MegaShutdown` 에 drain 종료 hook 을 등록한다. 아니면 `null`(미기동). 검증(빈 토큰 등)은 MegaWsHub
@@ -244,6 +267,9 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
   // 않게(로그가 종료 과정 끝까지 살아 있도록) — 마지막 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)))
     })
@@ -275,6 +301,9 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
       // 운영 관측성 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,
     })
@@ -388,5 +417,5 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
   }
 
   logger?.debug?.('boot.done')
-  return { server, host, config: global, apps, megaApps, ctx, wsHub }
+  return { server, host, config: global, apps, megaApps, ctx, wsHub, appLogger }
 }

package/src/core/config-validator.js

@@ -94,6 +94,31 @@ export function validateGlobalConfig(globalConfig) {
   //    앱에서 registerSession 이 fail-fast 로 잡으므로(여긴 server.sessionSecret 가 "정의됐을 때만"
   //    강도를 검증) — 정의됐다면 (a) 기본 placeholder 거부, (b) ≥32자 강제(부팅 fail-fast, ADR-062).
   validateSessionSecret(globalConfig.server?.sessionSecret)
+
+  // 7) server 런타임 타임아웃(ADR-181) — 정의됐다면 음 아닌 정수만(Fastify requestTimeout/keepAliveTimeout).
+  validateServerTimeouts(globalConfig.server)
+}
+
+/**
+ * `server.timeouts.requestMs` · `server.keepAliveMs` 검증(ADR-181, Fastify 인스턴스 옵션으로 매핑).
+ * 정의됐다면 음 아닌 정수(ms)만 허용 — 잘못된 값은 부팅 fail-fast. `trustProxy`/`trustedProxies` 는
+ * 타입 유연(boolean/number/string/array)이라 Fastify 에 위임(여기서 검증 안 함). 미정의는 통과(선택 키).
+ * @param {any} server - `globalConfig.server`.
+ * @throws {MegaConfigError} `server.invalid_timeout`.
+ */
+function validateServerTimeouts(server) {
+  const s = server ?? {}
+  /** @param {string} name @param {unknown} v */
+  const check = (name, v) => {
+    if (v === undefined) return
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+      throw new MegaConfigError('server.invalid_timeout', `${name} must be a non-negative integer (ms). Got ${JSON.stringify(v)}.`, {
+        details: { value: v },
+      })
+    }
+  }
+  check('server.timeouts.requestMs', s.timeouts?.requestMs)
+  check('server.keepAliveMs', s.keepAliveMs)
 }
 
 /** sessionSecret 강도 검증의 최소 길이(바이트 수가 아닌 문자 길이 — base64url 32바이트 ≈ 43자). */

package/src/core/mega-app.js

@@ -403,36 +403,40 @@ export class MegaApp {
     // onRoute 훅 등록 이후라 자동 envelope 적용됨. config.skip{Asp,Csrf,RateLimit} 3종이 각 보안 hook 의
     // 면제 신호다(ADR-072 면제 실효, ADR-127): ASP onRequest·CSRF preHandler·rate-limit allowList 가 검사.
     const HEALTH_EXEMPT = { skipAsp: true, skipCsrf: true, skipRateLimit: true }
-
-    // /health — liveness (항상 200)
-    this.fastify.get('/health', { config: HEALTH_EXEMPT }, async () => ({
-      status: 'ok',
-      app: this.name,
-      uptime_ms: Math.floor(process.uptime() * 1000),
-      ts: Date.now(),
-    }))
-
-    // /health/ready — readiness (checkAll 후 200 or 503)
-    this.fastify.get('/health/ready', { config: HEALTH_EXEMPT }, async (req, reply) => {
-      const snapshot = await MegaHealth.checkAll()
-      if (!snapshot.ok) reply.code(503)
-      return {
+    const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
+    // 헬스 경로(ADR-072/181) — 설정 가능. 미지정/빈 문자열이면 기본 /health · /health/ready.
+    const livePath = typeof healthCfg.paths?.live === 'string' && healthCfg.paths.live.length > 0 ? healthCfg.paths.live : '/health'
+    const readyPath = typeof healthCfg.paths?.ready === 'string' && healthCfg.paths.ready.length > 0 ? healthCfg.paths.ready : '/health/ready'
+
+    // health 라우트 등록 — `health.enabled:false` 면 생략(ADR-181). 기본(미지정/true)은 등록한다.
+    if (healthCfg.enabled !== false) {
+      // liveness (항상 200)
+      this.fastify.get(livePath, { config: HEALTH_EXEMPT }, async () => ({
+        status: 'ok',
         app: this.name,
-        ...snapshot,
         uptime_ms: Math.floor(process.uptime() * 1000),
         ts: Date.now(),
-      }
-    })
+      }))
+
+      // readiness (checkAll 후 200 or 503)
+      this.fastify.get(readyPath, { config: HEALTH_EXEMPT }, async (req, reply) => {
+        const snapshot = await MegaHealth.checkAll()
+        if (!snapshot.ok) reply.code(503)
+        return {
+          app: this.name,
+          ...snapshot,
+          uptime_ms: Math.floor(process.uptime() * 1000),
+          ts: Date.now(),
+        }
+      })
+    }
 
     // /metrics — Prometheus 옵트인 (ADR-072/131). exposeMetrics:true 일 때만 등록 →
     // 디폴트(미등록)는 Fastify 가 404(roadmap 검증 기준). /health 와 동일 보안 면제(HEALTH_EXEMPT).
     // 접근 제어 = IP allowList(ADR-131) — 빈 list 면 메인 포트 전체 노출(운영자 결정).
-    const healthCfg = opts.health && typeof opts.health === 'object' ? opts.health : {}
     if (healthCfg.exposeMetrics === true) {
       const metricsPath = typeof healthCfg.metricsPath === 'string' && healthCfg.metricsPath.length > 0 ? healthCfg.metricsPath : '/metrics'
-      // metricsPath 충돌 검증(ADR-072/04-data-models) — health 경로와 겹치면 부팅 throw(fail-fast).
-      const livePath = healthCfg.paths?.live ?? '/health'
-      const readyPath = healthCfg.paths?.ready ?? '/health/ready'
+      // metricsPath 충돌 검증(ADR-072/04-data-models) — health 경로(위에서 해석)와 겹치면 부팅 throw(fail-fast).
       if (metricsPath === livePath || metricsPath === readyPath) {
         throw new MegaConfigError(
           'health.metrics_path_conflict',

package/src/core/mega-cluster.js

@@ -35,6 +35,8 @@ export class MegaCluster {
    * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기
    * @param {import('node:cluster').Cluster} [opts._cluster] - 테스트용 cluster 주입(기본 node:cluster). per ADR-165
    * @param {NodeJS.Process} [opts._proc] - 테스트용 process 주입(기본 전역 process). per ADR-165
+   * @param {{ info?: Function, warn?: Function, error?: Function } | null} [opts.logger] - 조율 로그용 pino 로거.
+   *   미설정이면 console 폴백(마스터는 bootApp 을 안 해 pino 인스턴스가 없을 수 있다, ADR-180).
    */
   constructor(opts = {}) {
     this._instances = resolveInstances(opts.instances)
@@ -45,6 +47,8 @@ export class MegaCluster {
     // cluster/process 를 주입 seam 으로 분리해 fake 로 in-process 단위 검증한다. per ADR-165
     this._cluster = opts._cluster ?? cluster
     this._proc = opts._proc ?? process
+    /** @type {{ info?: Function, warn?: Function, error?: Function } | null} 조율 로그용 로거(없으면 console). */
+    this._logger = opts.logger ?? null
     /** @type {Set<MegaWorker>} */
     this._workers = new Set()
     /** @type {(() => Promise<void>) | null} */
@@ -92,12 +96,43 @@ export class MegaCluster {
     return !this._cluster.isPrimary
   }
 
+  /**
+   * 조율 로그용 로거 주입(생성 후, start 전에 호출). 마스터는 bootApp 을 안 해 pino 가 없으므로 CLI 가
+   * config 로 만든 인스턴스를 넘긴다(ADR-180). 미주입이면 console 폴백.
+   * @param {{ info?: Function, warn?: Function, error?: Function } | null | undefined} logger
+   * @returns {void}
+   */
+  setLogger(logger) {
+    this._logger = logger ?? null
+  }
+
+  /**
+   * @private 조율 로그 — 주입 로거가 있으면 그 레벨로, 없으면 console 폴백(`[mega-cluster]` 접두).
+   * @param {'info'|'warn'|'error'} level @param {string} msg
+   */
+  _log(level, msg) {
+    const log = this._logger
+    const text = `[mega-cluster] ${msg}`
+    if (log && typeof (/** @type {any} */ (log)[level]) === 'function') /** @type {any} */ (log)[level](text)
+    else (level === 'warn' ? console.warn : level === 'error' ? console.error : console.log)(text)
+  }
+
   /**
    * @private 마스터 프로세스 부팅 시퀀스.
    * @param {() => Promise<void>} workerFn
    */
   async _startPrimary(workerFn) {
     this._workerFn = workerFn
+    // 멀티워커 + watch 방어(ADR-182) — 워커는 마스터의 `execArgv` 를 상속하므로, `--watch*` 가 있으면
+    // 제거해 각 워커가 자기-watch 로 폭주(파일 변경 시 제각각 재시작)하는 것을 막는다. dev 권장 경로는
+    // 단일 프로세스(`mega start --watch`)라 보통 안 타지만, 수동 `node --watch … mega start --cluster N`
+    // 케이스의 방어 가드다. 단언이 아닌 setupPrimary 로 fork 전에 1회 적용.
+    const execArgv = this._proc.execArgv ?? []
+    const cleaned = execArgv.filter((a) => !a.startsWith('--watch'))
+    if (cleaned.length !== execArgv.length && typeof this._cluster.setupPrimary === 'function') {
+      this._cluster.setupPrimary({ execArgv: cleaned })
+      this._log('warn', 'stripped --watch* from worker execArgv (multi-worker watch chaos guard, ADR-182)')
+    }
     // workerFn 은 마스터에서 사용 안 함 (정보 전달용 placeholder)
     for (let i = 0; i < this._instances; i++) {
       this._forkWorker()
@@ -107,13 +142,13 @@ export class MegaCluster {
     const onSignal = (/** @type {string} */ sig) => {
       if (this._shuttingDown) return
       this._shuttingDown = true
-      console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
+      this._log('info', `received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
       this._broadcastShutdown()
       // grace 초과 시 강제 kill. 핸들을 보관해 전원 정상종료(exit 핸들러) 시 취소 — 정상 종료가 이 타이머의
       // exit(1) 과 경합해 exit code 가 흔들리지 않게 한다(k8s/systemd 종료 판정 노이즈 제거).
       this._graceTimer = setTimeout(() => {
         for (const w of this._workers) {
-          try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
+          try { w.kill('SIGKILL') } catch (err) { this._log('warn', `SIGKILL failed: ${err.message}`) }
         }
         this._proc.exit(1)
       }, this._gracePeriodMs)
@@ -134,7 +169,7 @@ export class MegaCluster {
         if (this._workers.size === 0) {
           if (this._graceTimer) clearTimeout(this._graceTimer) // 전원 정상종료 — 강제-kill 타이머 취소(exit code 경합 제거).
           this._graceTimer = null
-          console.log('[mega-cluster] all workers exited, primary exiting 0')
+          this._log('info', 'all workers exited, primary exiting 0')
           this._proc.exit(0)
         }
         return
@@ -152,19 +187,21 @@ export class MegaCluster {
           if (this._rapidCrashTimes.length >= this._maxRapidRespawn) {
             // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로 보인다 →
             //   systemd/k8s 가 "정상 종료" 로 오판. 명시적 exit 1 로 비정상 종료를 알려 재시작을 유도한다.
-            console.error(
-              `[mega-cluster] rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+            this._log(
+              'error',
+              `rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
             )
             this._proc.exit(1)
             return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
           }
         }
-        console.warn(
-          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
+        this._log(
+          'warn',
+          `worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
         )
         this._forkWorker()
       } else {
-        console.warn(`[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}), respawn disabled`)
+        this._log('warn', `worker ${worker.process.pid} died (code=${code}, signal=${signal}), respawn disabled`)
       }
     })
   }
@@ -176,7 +213,7 @@ export class MegaCluster {
         w.send({ type: SHUTDOWN_MSG })
       } catch (err) {
         // 워커가 이미 disconnected — 무시 + 로그 (silent 금지)
-        console.warn(`[mega-cluster] failed to send shutdown to worker ${w.process.pid}:`, err.message)
+        this._log('warn', `failed to send shutdown to worker ${w.process.pid}: ${err.message}`)
       }
     }
   }
@@ -199,8 +236,9 @@ export class MegaCluster {
         //   핸들러가 있었으면 true, 없으면 false → 무핸들러 경고.
         const hadListener = this._proc.emit('SIGTERM')
         if (!hadListener) {
-          console.warn(
-            `[mega-cluster] worker ${this._proc.pid} has no SIGTERM handler registered. Will be force-killed by master after grace period. ` +
+          this._log(
+            'warn',
+            `worker ${this._proc.pid} has no SIGTERM handler registered. Will be force-killed by master after grace period. ` +
               `Register a SIGTERM handler (or use MegaShutdown.setupSignals) to enable graceful shutdown.`,
           )
         }
@@ -211,7 +249,7 @@ export class MegaCluster {
     try {
       await workerFn()
     } catch (err) {
-      console.error(`[mega-cluster] worker ${this._proc.pid} workerFn failed:`, err)
+      this._log('error', `worker ${this._proc.pid} workerFn failed: ${/** @type {any} */ (err)?.stack ?? err}`)
       this._proc.exit(1)
     }
   }

package/src/core/scope-registry.js

@@ -16,7 +16,6 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'apps', // 활성 앱 whitelist (ADR-066)
   'asp', // masterSecret 등 시크릿
   'health', // /health, /health/ready
-  'tracing', // OpenTelemetry (ADR-077)
   'plugins', // 명시 등록 배열 (ADR-079)
   'jobs', // MegaJob 서브클래스 배열 — mega worker 가 소비 (ADR-123)
   'schedules', // MegaSchedule 서브클래스 배열 — mega scheduler 가 소비 (ADR-123)

package/src/lib/mega-logger.js

@@ -133,7 +133,7 @@ function mergeRedact(userRedact) {
 /**
  * `logger` config → pino 옵션(또는 비활성 시 `null`). Fastify `logger` 또는 `pino()` 에 그대로 전달 가능.
  *
- * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact?, includeRequestId? }`).
+ * @param {unknown} config - `MegaLoggerConfig`(`{ level, sinks, redact? }`).
  * @returns {{ level: string, mixin: Function, redact: { paths: string[] }, transport: { targets: any[] } } | null}
  */
 export function buildLoggerOptions(config) {

package/src/lib/mega-shutdown.js

@@ -37,6 +37,14 @@ 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)으로 실행.
@@ -111,22 +119,40 @@ function setupGlobalErrorHandlers({ exitCode = 1 } = {}) {
   if (globalErrorsRegistered) return
   globalErrorsRegistered = true
   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)
+    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)
+    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,17 +164,17 @@ 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 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()
@@ -158,7 +184,7 @@ async function now({ signal, exitCode = 0 } = {}) {
     const { name, fn } = handlers[i]
     if (exitedHandlers.has(i)) continue
     try {
-      console.log(`[mega-shutdown] running '${name}'`)
+      logShutdown('info', `running hook '${name}'`, { hook: name })
       await Promise.race([
         Promise.resolve(fn()),
         new Promise((_, reject) =>
@@ -166,18 +192,28 @@ async function now({ signal, exitCode = 0 } = {}) {
         ),
       ])
       exitedHandlers.add(i)
-      console.log(`[mega-shutdown] '${name}' done`)
+      logShutdown('info', `hook '${name}' done`, { hook: name })
     } catch (err) {
       // silent 금지. 핸들러 실패 시 warn 로그 + 다음 hook 진행.
-      console.warn(`[mega-shutdown] '${name}' failed (continuing):`, err?.message ?? err)
+      logShutdown('warn', `hook '${name}' failed (continuing)`, { hook: name, err: /** @type {any} */ (err)?.message ?? err })
     }
   }
 
   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}
@@ -202,6 +238,7 @@ function _reset() {
   unhandledRejectionHandler = null
   uncaughtExceptionHandler = null
   globalErrorsRegistered = false
+  shutdownLogger = null
 }
 
 /**
@@ -214,6 +251,7 @@ export const MegaShutdown = {
   isShuttingDown,
   setupSignals,
   setupGlobalErrorHandlers,
+  setLogger,
   now,
   registeredCount,
   _reset,