mega-framework 0.1.9 → 0.1.11

package/sample/crud/apps/main/views/lock/index.ejs

@@ -0,0 +1,99 @@
+<% layout('layouts/main') %>
+
+<div class="mb-4">
+  <h1 class="h3 mb-1"><%= t('lock_title', { defaultValue: '분산 락 데모' }) %></h1>
+  <p class="text-body-secondary small mb-0">
+    <%= t('lock_subtitle', { defaultValue: 'ctx.lock.with / tryAcquire 로 임계구역을 보호합니다. 두 탭에서 같은 키로 동시에 실행하면 한 번에 하나만 들어가고(상호배제), FIFO 면 도착 순서대로 깨어납니다.' }) %>
+    <a href="/guide" class="ms-1">ADR-226 · 가이드</a>
+  </p>
+</div>
+
+<div class="row g-3">
+  <!-- 실행 폼 -->
+  <div class="col-lg-7">
+    <div class="card h-100">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('lock_run_title', { defaultValue: '임계구역 실행' }) %></h2>
+        <p class="card-text text-body-secondary small"><%= t('lock_run_desc', { defaultValue: '키를 잡고 holdMs 동안 점유한 뒤 자동 해제합니다(ctx.lock.with). 다른 시도는 waitMs 까지 대기합니다.' }) %></p>
+
+        <div class="row g-2">
+          <div class="col-12">
+            <label class="form-label small mb-1" for="lk-key"><%= t('lock_f_key', { defaultValue: '자원 키' }) %></label>
+            <input id="lk-key" class="form-control form-control-sm" value="demo:resource" maxlength="80">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-ttl">ttl (ms)</label>
+            <input id="lk-ttl" type="number" class="form-control form-control-sm" value="5000" min="100" max="60000">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-wait">waitMs</label>
+            <input id="lk-wait" type="number" class="form-control form-control-sm" value="3000" min="0" max="30000">
+          </div>
+          <div class="col-6 col-md-3">
+            <label class="form-label small mb-1" for="lk-hold">holdMs</label>
+            <input id="lk-hold" type="number" class="form-control form-control-sm" value="2500" min="0" max="15000">
+          </div>
+        </div>
+
+        <div class="d-flex flex-wrap gap-3 mt-3">
+          <div class="form-check form-switch">
+            <input id="lk-fifo" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-fifo">fifo <span class="text-body-secondary"><%= t('lock_f_fifo', { defaultValue: '(도착 순서 보장)' }) %></span></label>
+          </div>
+          <div class="form-check form-switch">
+            <input id="lk-fence" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-fence">fence <span class="text-body-secondary"><%= t('lock_f_fence', { defaultValue: '(단조 토큰)' }) %></span></label>
+          </div>
+          <div class="form-check form-switch">
+            <input id="lk-ext" class="form-check-input" type="checkbox">
+            <label class="form-check-label small" for="lk-ext">extendable <span class="text-body-secondary"><%= t('lock_f_ext', { defaultValue: '(watchdog 자동연장)' }) %></span></label>
+          </div>
+        </div>
+
+        <div class="d-flex gap-2 mt-3">
+          <button id="lk-run" class="btn btn-primary btn-sm"><%= t('lock_btn_run', { defaultValue: '실행 (with)' }) %></button>
+          <button id="lk-try" class="btn btn-outline-secondary btn-sm"><%= t('lock_btn_try', { defaultValue: 'tryAcquire' }) %></button>
+        </div>
+
+        <div id="lk-result" class="mt-3 small"></div>
+        <div class="mt-3"><code class="small">ctx.lock.with(key, { ttl, waitMs, fifo, fence, extendable }, fn)</code></div>
+      </div>
+    </div>
+  </div>
+
+  <!-- 상태 패널 -->
+  <div class="col-lg-5">
+    <div class="card h-100">
+      <div class="card-body">
+        <h2 class="h5 card-title"><%= t('lock_status_title', { defaultValue: '현재 상태' }) %></h2>
+        <div class="d-flex gap-4 mb-2">
+          <div>
+            <div class="h4 fw-bold mb-0" id="lk-active"><%= stats ? stats.active : '–' %></div>
+            <div class="text-body-secondary small"><%= t('lock_active', { defaultValue: '보유 중' }) %></div>
+          </div>
+          <div>
+            <div class="h4 fw-bold mb-0" id="lk-waiting"><%= stats ? stats.waiting : '–' %></div>
+            <div class="text-body-secondary small"><%= t('lock_waiting', { defaultValue: '대기 중' }) %></div>
+          </div>
+          <div>
+            <div class="h6 fw-bold mb-0"><span class="badge text-bg-secondary" id="lk-driver"><%= stats ? stats.driver : '?' %></span></div>
+            <div class="text-body-secondary small">driver</div>
+          </div>
+        </div>
+        <p class="text-body-secondary small mb-2">
+          <%= t('lock_worker_pid', { defaultValue: '이 페이지를 처리한 워커 PID' }) %>: <code><%= pid %></code>
+        </p>
+        <hr>
+        <h3 class="h6"><%= t('lock_log_title', { defaultValue: '최근 실행 (이 워커)' }) %></h3>
+        <div class="table-responsive" style="max-height: 320px; overflow-y: auto;">
+          <table class="table table-sm small mb-0">
+            <thead><tr><th>at</th><th>key</th><th>pid</th><th><%= t('lock_log_result', { defaultValue: '결과' }) %></th><th>wait</th></tr></thead>
+            <tbody id="lk-log"></tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script src="/static/js/lock-demo.js"></script>

package/sample/crud/docs/guide/03-service-model-db.md

@@ -636,6 +636,54 @@ caches: {
 
 이 셋은 본 문서(Service+Model+DB) 범위 밖이라 이름만 짚는다.
 
+### 분산 락 사용자 API — `ctx.lock.with/.acquire` (ADR-226)
+
+여러 인스턴스가 같은 자원을 동시에 건드리면 안 될 때(재고 차감, 1회성 작업 등) **분산 락**으로 임계구역을
+보호한다. 위 `redlock`(`ctx.lock('main')`, 스케줄 leader election)과 **별개 하위시스템**으로, 별명 선언 없이
+컨트롤러·서비스에서 바로 쓴다.
+
+```js
+// 권장 — 잠그고, 끝나면(성공/예외 무관) 자동 해제
+await ctx.lock.with('stock:sku-42', { ttl: 5000 }, async () => {
+  const row = await stock.byId(42)
+  await stock.update(42, { qty: row.qty - 1 })   // 이 블록은 노드를 넘어 한 번에 하나만 실행
+})
+
+// 즉시 1회 시도(대기 없음) — 못 잡으면 null
+const lock = await ctx.lock.tryAcquire('job:nightly')
+if (lock) { try { /* ... */ } finally { await lock.release() } }
+```
+
+- **옵션**: `ttl`(보유 ms) · `waitMs`(획득 대기 ms, 0=즉시) · `fifo`(도착 순서 보장) · `fence`(단조 토큰
+  `lock.fence`) · `extendable`(긴 작업 자동 연장). `acquire` 는 못 잡으면 `lock.not_acquired`(409) throw,
+  `tryAcquire` 는 `null`.
+- **driver 자동 폴백**: `mega.config.js` 의 `lock` 블록(주석 처리됨 — 풀어서 `cache: 'lock'` 지정)이 있으면
+  **redis**(진짜 분산), 없고 클러스터 워커면 **cluster**(단일 노드), 그 외엔 **memory**(단일 프로세스, 부팅 경고).
+  redis 활성에 **추가 .env 는 불필요** — 기존 `caches.lock`(`REDIS_LOCK_URL`)을 재사용한다.
+
+### 메시지 버스 사용자 API — `ctx.bus.emit/.on/.request` (ADR-227)
+
+서비스끼리 이벤트로 느슨하게 결합할 때(주문 생성 → 이메일·분석 각각 반응) **메시지 버스**를 쓴다. 위
+`services.buses`(`ctx.bus('jobs')`, 잡 큐)와 **별개 하위시스템**으로, 별명 선언 없이 발행/구독한다.
+
+```js
+// fan-out — 구독자 전원 수신 (핸들러는 payload, meta)
+ctx.bus.emit('order.created', { orderId: 42 }, { meta: { traceId } })
+ctx.bus.on('order.created', async (payload) => { await emailService.sendReceipt(payload.orderId) })
+ctx.bus.on('order.*', async (payload, meta) => { /* order.created/updated 등 — '*' 는 한 토큰 */ })
+
+// request/reply — 핸들러 '반환값'이 응답
+ctx.bus.on('catalog.product', async ({ id }) => ({ id, name: 'widget' }))
+const product = await ctx.bus.request('catalog.product', { id: 1 }, { timeout: 1000 })
+```
+
+- **wildcards**(NATS 식): `order.*` = 한 토큰(`order.created` O, `order.created.eu` X), `order.>` = 꼬리 전체.
+- **옵트인**: `{ persist: true }`(JetStream 영속 — nats driver 만; 그 외엔 경고 후 비영속) · `{ ordered: true }`(순서 보장).
+  한 구독자가 throw 해도 다른 구독자·다음 메시지엔 영향 없다(매니저가 잡아 로깅).
+- **driver 자동 폴백**: `mega.config.js` 의 `bus` 블록(주석 처리됨 — 풀어서 `nats: 'jobs'` 지정)이 있으면
+  **nats**(진짜 분산), 없고 클러스터 워커면 **cluster**(단일 노드), 그 외엔 **memory**(단일 프로세스, 부팅 경고).
+  nats 활성에 **추가 .env 는 불필요** — 기존 `buses.jobs`(`NATS_JOBS_URL`)을 재사용한다.
+
 ---
 
 ## 5. mega migrate — 스키마 마이그레이션 (ADR-149)

package/sample/crud/docs/guide/05-scheduler-job-worker.md

@@ -139,12 +139,17 @@ export class EmailJob extends MegaJob {
   static concurrency = 2
   static retries = 2                                       // 추가 재시도 2회 (첫 시도 포함 최대 3회)
   static backoff = { type: 'exponential', initial: 500, max: 2000 }
+  static timeoutMs = 5000                                  // run 전체 상한 — 초과 시 timeout → DLQ (2-6)
 
   async run(payload, ctx) {
     const { id, to, mode } = payload
     const redis = ctx.cache('demo').native
     const attempt = await redis.incr(`demo:jobs:attempt:${id}`)
 
+    if (mode === 'hang') {
+      await new Promise((r) => setTimeout(r, payload.delayMs ?? 8000))           // 5s(timeoutMs) 초과 → timeout
+      return { id, status: 'sent', attempt }                                     // timeout 후 백그라운드에서 늦게 완료
+    }
     if (mode === 'flaky' && attempt < 2) {
       throw new Error(`transient failure on attempt ${attempt} (will retry)`)   // 재시도 트리거
     }
@@ -163,6 +168,7 @@ export class EmailJob extends MegaJob {
 | `concurrency` | `1` | 동시 처리 메시지 수(consumer `max_ack_pending`). **양의 정수만** — 0/음수는 NATS 가 "무제한" 으로 해석하는 풋건이라 거부. ⚠️ **워커 그룹(전 인스턴스) 합산 상한** — 인스턴스를 늘려도 합산 in-flight 가 이 값을 못 넘으므로 처리량 증설 시 함께 키울 것 |
 | `retries` | `3` | run 실패 시 **추가** 재시도 횟수(첫 시도 제외) |
 | `backoff` | `{ type:'exponential', initial:1000, max:30000 }` | 지수 백오프. **현재 `'exponential'` 만 지원**, `initial`/`max` 는 ms |
+| `timeoutMs` | 큐 디폴트(30분) | run 전체(재시도 포함) 실행 상한(ms). 초과 시 timeout 실패 → DLQ. `0` = 무제한. 행(hang)된 잡이 lease 를 영구 갱신하며 메시지를 점유하는 것을 막는 backstop (2-6) |
 
 > **핵심**: 일시·영구 오류는 그냥 `throw` 하면 된다. `MegaJobQueue` 가 `static retries`/`static backoff` 만큼 인프로세스 지수 백오프(p-retry, factor=2·jitter on 고정)로 재시도하고, 모두 실패하면 DLQ 로 보낸다.
 
@@ -219,11 +225,32 @@ MegaShutdown.register('worker', async () => { await worker.stop() })
 DLQ 상태를 읽는 쪽 예시(`jobs-demo-service.js`):
 
 ```js
-const jsm = await this.ctx.bus('jobs').native.jetstreamManager()
+// nats v3(ADR-225): jetstreamManager 는 nc 메서드가 아니라 @nats-io/jetstream 의 함수다.
+import { jetstreamManager } from '@nats-io/jetstream'
+const jsm = await jetstreamManager(this.ctx.bus('jobs').native)
 const info = await jsm.streams.info('MEGA_JOBS_demo_email_DLQ')   // count = info.state.messages
 const msg = await jsm.streams.getMessage(DLQ_STREAM, { last_by_subj: 'demo.email.dlq' })
 ```
 
+### 2-6. timeoutMs — 행(hang)된 잡 backstop
+
+`run()` 이 실패(throw)는 안 하는데 **끝나지도 않으면**(외부 호출이 hang, 무한 루프 등) `working()` 하트비트가 ack lease 를 영원히 갱신해 메시지가 재전달도 DLQ 도 못 가는 **영구 점유**가 된다. `static timeoutMs`(또는 큐 디폴트 30분)가 이 backstop이다 — run 전체(재시도 포함)에 상한을 걸어 초과하면 잡을 **실패로 판정**해 DLQ 로 라우팅한다.
+
+`/demo/jobs` 의 **`hang` 모드**가 이를 시연한다. `delayMs`(기본 8000ms)만큼 자는 잡을 enqueue하면, EmailJob 의 `static timeoutMs = 5000` 을 넘는 순간 큐가 timeout으로 판정한다:
+
+```
+WARN  job ... (없음 — hang 은 throw 안 함, retry 이벤트 없음)
+ERROR job failed     subject=demo.email phase=run  err=… exceeded run timeout (5000ms) …
+WARN  job routed to DLQ   subject=demo.email dlqSubject=demo.email.dlq
+```
+
+- DLQ 봉투의 `error.message` = `exceeded run timeout (5000ms)` — 페이지 DLQ 카드에 표시된다.
+- **⚠️ timeout 후에도 진행 중 run 은 중단되지 않는다**(abort 없음 — JS 는 협조적 취소만 가능). hang 잡은 백그라운드에서 `delayMs` 뒤 끝까지 흘러 'sent' 이벤트를 **뒤늦게** 남긴다. 그래서 **run 은 멱등(idempotent)하게 설계**해야 한다 — 같은 잡이 timeout 후 백그라운드 완료 + (max_deliver 재전달 시) 재실행돼도 안전하도록.
+- 진짜 backstop은 `static timeoutMs` 가 아니라도 큐 디폴트(30분)로 항상 걸려 있다. 데모는 체감을 위해 5s 로 줄였을 뿐이다(`0` = 무제한으로 끌 수 있으나 행 잡 점유 위험을 떠안는다).
+- 만약 abandoned된(timeout 패배) run 이 나중에 **throw** 하면, 그 늦은 실패는 `fail(phase:'abandoned-run')` 이벤트로 별도 표면화된다(잡은 이미 DLQ 라우팅됐으므로 처리 흐름엔 영향 없음).
+
+위 워커 로그는 호스트(`mega worker`)가 잡 이벤트를 구독해 남긴 것이다(ADR-223) — `fail`=error, `dlq`/`retry`=warn, `start`/`done`=debug.
+
 ---
 
 ## 3. Worker (worker_threads, MegaWorker, ADR-124)
@@ -337,7 +364,7 @@ module.exports = {
 }
 ```
 
-잡 메트릭(ADR-132)은 `mega worker` 호스트가 `MegaMetrics.subscribeJobs(worker)` 로 구독한다 — `health.exposeMetrics` 옵트인 시 enqueue(dispatch)부터 done/retry/fail/dlq 까지 Prometheus 로 집계되고, 옵트인 OFF 면 no-op 이다.
+잡 메트릭(ADR-132)은 `mega worker` 호스트가 `MegaMetrics.subscribeJobs(worker)` 로 구독한다 — `health.exposeMetrics` 옵트인 시 enqueue(dispatch)부터 done/retry/fail/dlq 까지 Prometheus 로 집계되고, 옵트인 OFF 면 no-op 이다. 메트릭과 **독립적으로**, 호스트는 같은 이벤트를 **로그로도** 남긴다(ADR-223) — `fail`=error, `dlq`/`retry`=warn, `start`/`done`=debug. 메트릭을 꺼도 잡 실패·DLQ 격리는 로그에 남는다.
 
 ---
 

package/sample/crud/docs/guide/09-distributed-lock-and-bus.md

@@ -0,0 +1,224 @@
+# 분산 락 · 메시지 버스
+
+여러 인스턴스(클러스터 워커·여러 노드)가 같은 자원을 동시에 건드리거나, 모듈끼리 이벤트로 느슨하게
+결합해야 할 때 쓰는 두 사용자 API다. 둘 다 **별명 선언 없이** `ctx.lock` / `ctx.bus` 로 바로 쓰고, 환경에
+맞춰 driver 가 자동으로 골라진다(redis/nats 있으면 진짜 분산, 없으면 cluster, 그것도 없으면 단일 프로세스).
+
+- 실제 동작: `/demo/lock`(분산 락) · `/demo/bus`(메시지 버스) — 두 탭을 띄워 워커 PID·순서·fan-out 을 눈으로 본다.
+- 정본: 분산 락 = ADR-226, 메시지 버스 = ADR-227.
+
+---
+
+## 1. 분산 락 — `ctx.lock`
+
+### 언제 쓰나
+
+- **race condition 방지**: 재고 차감, 좌석 예약 등 "읽고-고치고-쓰기"를 한 번에 하나만.
+- **단일 실행 보장**: 클러스터에서 정기 작업을 한 인스턴스만(스케줄러 leader election — 단, 스케줄 중복방지는
+  `static lock`(ADR-118)이 따로 있다).
+- **외부 호출 직렬화**: 같은 리소스에 대한 외부 API 호출이 겹치지 않게.
+
+### API — `with` 권장
+
+```js
+// 권장 — 잠그고, 끝나면(성공/예외 무관) 자동 해제
+await ctx.lock.with('stock:42', { ttl: 5000 }, async (lock) => {
+  const row = await stock.byId(42)
+  await stock.update(42, { qty: row.qty - 1 })   // 이 블록은 노드를 넘어 한 번에 하나만 실행
+})
+
+// 수동 — try/finally
+const lock = await ctx.lock.acquire('order:99', { ttl: 5000, waitMs: 1000 })
+try { /* ... */ } finally { await lock.release() }
+
+// 즉시 1회(대기 없음) — 못 잡으면 null
+const got = await ctx.lock.tryAcquire('job:nightly')
+if (got) { try { /* ... */ } finally { await got.release() } }
+```
+
+### 옵션
+
+| 옵션 | 뜻 |
+| --- | --- |
+| `ttl` | 락 보유 시간(ms). 이 시간이 지나면 자동 만료(보유자 crash 안전망). |
+| `waitMs` | 경합 시 획득 대기 상한(ms). `0` = 즉시 실패(tryAcquire 와 동일). |
+| `fifo` | `true` 면 대기자를 **도착 순서**대로 깨운다(기아 방지). |
+| `fence` | `true` 면 단조 증가 토큰(`lock.fence`)을 함께 준다 — 외부 시스템이 stale-writer 를 거를 때. |
+| `extendable` | `true` 면 watchdog 이 ttl 절반마다 자동 연장(긴 작업). |
+
+`acquire`/`with` 는 못 잡으면 `lock.not_acquired`(409) throw, `tryAcquire` 는 `null`.
+
+### driver 자동 폴백 + config
+
+```js
+// mega.config.js (전역)
+lock: { driver: 'auto', cache: 'lock', ttl: 5000, waitMs: 1000, fifo: false }
+```
+
+| driver | 보장 범위 | 전제 |
+| --- | --- | --- |
+| `redis` | 멀티 프로세스·멀티 노드(진짜 분산) | `lock.cache` = redis 캐시 별명 |
+| `cluster` | 같은 노드 워커 간 | `mega start --cluster=N` 워커 |
+| `memory` | 단일 프로세스만 | 없음(개발용) |
+
+`auto`(기본)는 redis 가용 시 redis, 클러스터 워커면 cluster, 그 외 memory + 부팅 경고. 명시 driver 의 전제가
+없으면 부팅 fail-fast. 이 데모(crud)는 `cache: 'lock'`(기존 `caches.lock`)로 redis 분산 락을 켜 둔다.
+
+### 함정
+
+- **ttl 을 임계구역보다 짧게 잡으면** 작업 도중 락이 만료돼 다른 인스턴스가 들어온다 → ttl 을 넉넉히, 긴
+  작업은 `extendable: true`(watchdog).
+- 외부 시스템(DB·파일)에 쓰기를 보호할 땐, 락 만료와 쓰기 사이의 경합을 막으려 **fence 토큰**을 외부에 같이
+  넘겨 stale-writer 를 거르는 패턴을 권장한다.
+- `ctx.lock(alias)`(설정형 redlock, ADR-113)와 `ctx.lock.with(...)`(자동폴백)는 **별개**다. TTL 단위는 둘 다 ms.
+
+---
+
+## 2. 메시지 버스 — `ctx.bus`
+
+### 언제 쓰나
+
+- **도메인 이벤트**: "주문 생성됨" → 이메일·분석·재고가 각각 반응(발행자는 구독자를 모름).
+- **fan-out**: 한 이벤트를 여러 구독자가 동시에 받는다.
+- **느슨한 결합**: 모듈이 서로 직접 호출하지 않고 이벤트로만 연결.
+
+### API
+
+핸들러 시그니처는 **`(payload, meta, subject)`** 다 — 3번째 `subject` 는 메시지가 도착한 **구체** subject
+(wildcard 가 아닌 실제 발행 subject)다. `meta.subject` 에도 같은 값이 담긴다(정본 위치). 기존 `(payload, meta)`
+2-인자 핸들러는 그대로 동작한다(3번째 인자를 안 받아도 무방 — 호환).
+
+```js
+// fan-out — 구독자 전원 수신
+ctx.bus.emit('order.created', { orderId: 42 }, { meta: { traceId } })
+ctx.bus.on('order.created', async (payload, meta) => { await email.sendReceipt(payload.orderId) })
+
+// request/reply — 핸들러 '반환값'이 응답
+ctx.bus.on('catalog.product', async ({ id }) => ({ id, name: 'widget' }))
+const product = await ctx.bus.request('catalog.product', { id: 1 }, { timeout: 1000 })
+
+// 구독 해제 / 요청 단위 meta 바인딩
+const sub = await ctx.bus.on('topic', handler); await sub.unsubscribe()   // 또는 ctx.bus.off('topic', handler)
+const scoped = ctx.bus.with({ traceId }); await scoped.emit('x', payload)  // 이후 emit/request 에 meta 자동 병합
+```
+
+### Wildcards (NATS 식)
+
+구독 subject 에 wildcard 를 쓴다(발행 subject 는 구체적이어야 한다):
+
+- `*` = **정확히 한 토큰**. `order.*` → `order.created`(O), `order.created.eu`(X)
+- `>` = **한 토큰 이상(꼬리 전체)**, 맨 끝에만. `order.>` → `order.created`, `order.created.eu`(둘 다 O)
+
+wildcard 로 구독하면 **3번째 인자 `subject`** 로 어느 구체 subject 가 매칭됐는지 안다:
+
+```js
+ctx.bus.on('order.>', async (payload, meta, subject) => {
+  // subject === 'order.created' | 'order.created.eu' | ... (실제 발행 subject)
+  if (subject === 'order.created') await onCreate(payload)
+  else if (subject.endsWith('.eu')) await onEu(payload)
+})
+```
+
+### 옵션
+
+| 옵션 | 뜻 |
+| --- | --- |
+| `persist`(emit/on) | `true` 면 JetStream 영속(저장 + 재전달). **nats driver 만**; 그 외엔 경고 후 비영속. |
+| `ordered`(on) | `true` 면 같은 구독을 도착 순서대로 1건씩 직렬 처리. |
+| `timeout`(request) | 응답 대기 상한(ms). 초과 시 `bus.request_timeout`, 응답자 없으면 `bus.no_responders`. |
+
+한 구독자가 throw 해도 다른 구독자·다음 메시지엔 영향 없다(매니저가 잡아 로깅 — fan-out 격리).
+
+### driver 자동 폴백 + config
+
+```js
+// mega.config.js (전역)
+bus: { driver: 'auto', nats: 'jobs', prefix: 'app.', defaultPersist: false, requestTimeoutMs: 5000 }
+```
+
+| driver | 보장 범위 | persist | 전제 |
+| --- | --- | --- | --- |
+| `nats` | 멀티 프로세스·멀티 노드 | O(JetStream) | `bus.nats` = NATS 버스 별명 |
+| `cluster` | 같은 노드 워커 간 | X(경고 후 비영속) | `mega start --cluster=N` 워커 |
+| `memory` | 단일 프로세스만 | X | 없음(개발용) |
+
+`prefix`(예: `app.`)는 모든 subject 에 자동으로 붙어 네임스페이스를 격리한다. nats driver 는 기존 잡 큐
+(ADR-119)·클러스터 broadcast(ADR-176)와 **같은 NATS 연결**을 빌려 쓴다(새 연결 X). 이 데모는 `nats: 'jobs'`로
+NATS 버스를 켜 둔다.
+
+### 함정
+
+- **구독하기 전에 발행된 이벤트는 비영속(core)에선 유실된다.** 늦게 붙은 구독자도 받아야 하면 `persist: true`
+  (JetStream 이 저장했다가 전달) — 단 nats driver 필요.
+- subject 는 `.` 으로 나뉜 토큰열이고 공백/wildcard 규칙이 있다(NATS 제약). 발행 subject 에 `*`/`>` 는 금지.
+- `ctx.bus(alias)`(설정형 NATS 어댑터, ADR-110)와 `ctx.bus.emit(...)`(자동폴백)은 **별개** 하위시스템이다.
+
+---
+
+## 3. ctx 없는 곳에서 — `getApp()` (ADR-228)
+
+`ctx.lock`/`ctx.bus` 는 요청 ctx 에만 있다. 요청 흐름 **밖**(백그라운드 타이머·외부 SDK 콜백·테스트)에서는
+`getApp()` 으로 booted 앱을 잡아 **같은 표면**으로 쓴다. lock/bus manager 는 process 싱글톤이라 `app.lock` 은
+`ctx.lock` 과 같은 객체다.
+
+```js
+import { getApp } from 'mega-framework'
+
+// 백그라운드 하트비트 — 요청 ctx 가 없는 setInterval 콜백
+setInterval(async () => {
+  const app = getApp()
+  await app.bus.emit('heartbeat', { ts: Date.now() })
+}, 60_000)
+
+// 외부 SDK 콜백에서 분산 락
+stripe.webhooks.on('charge.succeeded', async (event) => {
+  await getApp().lock.with(`charge:${event.id}`, { ttl: 5000 }, async () => { /* 멱등 처리 */ })
+})
+```
+
+- **표면**: `app.lock` / `app.bus`(ctx 와 동일 API) · `app.db(alias)` / `app.cache(alias)` · `app.log` / `app.name`.
+  요청-스코프(`req`/`user`/`session`/요청 locale `t`)는 **없다** — 그건 ctx 전용이다.
+- **부팅 전 호출은 fail-fast**: 아직 부팅이 안 끝났으면 `app.not_initialized` throw(타이밍 버그를 조용히 넘기지
+  않음). `afterBoot` hook 이후·listen 이후의 백그라운드에서 호출한다. 부팅 여부만 보려면 `hasApp()`.
+- **멀티앱 프로세스**: 앱이 둘 이상이면 `getApp('<name>')` 로 이름을 준다(생략 시 `app.ambiguous`).
+- **권장**: ctx 가 **있는** 곳(라우트·서비스·잡/스케줄 `run(ctx)`)은 여전히 `ctx.lock`/`ctx.bus` 를 쓴다 — 요청
+  로거·user·session 이 함께 묶여 추적이 쉽다. `getApp()` 은 ctx 가 **없을 때만**.
+
+---
+
+## 4. 앱별 lock/bus 분리 — 멀티앱 (ADR-229)
+
+한 프로세스에 여러 앱을 vhost 로 띄울 때(`apps/<name>/`), 앱마다 **다른** lock/bus 를 쓸 수 있다 — `admin` 은
+격리된 NATS·redis, `public` 은 공용처럼. `lock`/`bus` 는 글로벌(`mega.config.js`)·앱(`apps/<name>/app.config.js`)
+**양쪽**에 둘 수 있고(dual-scope), 우선순위는 **앱별 > 글로벌 > 기본값**(앱이 정의하면 글로벌과 합쳐 그 앱 전용
+manager, 미정의면 글로벌 그대로).
+
+```js
+// mega.config.js (글로벌 = fallback)
+lock: { cache: 'lockMain' },
+bus:  { nats: 'natsMain', prefix: 'app.' },
+
+// apps/admin/app.config.js — admin 전용 backend
+lock: { cache: 'lockAdmin' },          // admin 만 다른 redis
+bus:  { nats: 'natsAdmin', prefix: 'admin.' },
+
+// apps/public/app.config.js — bus 만 prefix 분리(같은 NATS, 가벼운 격리)
+bus: { prefix: 'public.' },
+```
+
+- `ctx.lock`/`ctx.bus`(요청은 vhost 로 앱에 라우팅됨)와 `getApp('admin').lock`/`bus`(ctx 없는 영역, ADR-228)는
+  **그 앱의 manager** 를 가리킨다.
+- `lock.cache`/`bus.nats` 는 앱 config 에서도 **글로벌 `services`** 의 키를 참조한다(services 는 글로벌 정의).
+- **한계**: 같은 프로세스라 메모리·CPU·이벤트루프는 공유된다. 강한 격리(다른 스케일·장애 격리)가 필요하면
+  **process-per-app + mega-bus(NATS)** 로 프로세스 간 통신하는 쪽이 정답이다.
+
+---
+
+## 데모로 확인하기
+
+- `/demo/lock` — 키·ttl·waitMs·holdMs 와 fifo/fence/extendable 토글로 임계구역을 실행한다. **두 탭에서 같은
+  키로 동시에 "실행"** 하면 한 쪽은 즉시, 다른 쪽은 대기 후 실행되고(상호배제), fifo 면 도착 순서가 보인다.
+  상태 패널의 보유/대기 수와 워커 PID 로 분산 동작이 드러난다.
+- `/demo/bus` — subject·payload 를 발행하면 페이지가 `demo.>` 구독으로 받아 표시한다. **여러 워커가 받는
+  fan-out**, `order.created`/`order.created.eu`/`user.login` 의 wildcard 매칭, `demo.echo` request/reply(어느
+  워커가 답했는지 PID), persist 배지로 영속 이벤트를 구분해 본다.

package/sample/crud/docs/guide/10-multi-app.md

@@ -0,0 +1,74 @@
+# 멀티앱 — 한 프로세스 vhost
+
+한 프로세스에 **여러 앱**을 띄우고 `Host` 헤더로 라우팅하는 vhost 모델(ADR-063)과, 앱별 lock/bus 분리
+(ADR-229)·cross-app 호출(ADR-228)을 설명합니다. 실동작은 `sample/multi`(web=a.com, admin=b.com)에서 봅니다.
+
+## vhost 모델 — 한 포트, Host 라우팅
+
+`mega.config.js` 의 `apps` 배열에 앱 폴더 이름을 나열하면, 각 `apps/<name>/app.config.js` 의 `hosts` 로 도메인이
+매핑됩니다. boot 는 앱마다 **별도 Fastify 인스턴스**를 만들고 하나의 서버에 vhost 마운트해 **한 포트로 한 번
+listen** 합니다. 매 요청은 `Host` 헤더의 hostname 으로 해당 앱에 라우팅됩니다.
+
+```js
+// mega.config.js
+export default { apps: ['web', 'admin'], server: { port: 3000 }, /* ... */ }
+
+// apps/web/app.config.js   → hosts: ['a.com']
+// apps/admin/app.config.js → hosts: ['b.com']
+```
+
+- **host_collision**: 같은 host 를 두 앱에 매핑하면 부팅 시 `config.host_collision` 로 **fail-fast**(ADR-067) —
+  요청이 어느 앱으로 갈지 모호해지는 것을 부팅에서 막습니다.
+
+## 앱별 lock/bus 분리 (ADR-229)
+
+`lock`/`bus` 는 글로벌(`mega.config.js`)·앱(`apps/<name>/app.config.js`) 양쪽에 둘 수 있습니다(dual-scope). 앱이
+정의하면 글로벌과 합쳐 **그 앱 전용 manager**, 미정의면 글로벌 fallback. `sample/multi` 예:
+
+```js
+// mega.config.js — 글로벌(fallback): bus는 NATS(glob.), lock은 생략 → memory
+bus: { nats: 'events', prefix: 'glob.' },
+
+// apps/web/app.config.js — 앱 전용: redis 락 + web. 버스
+lock: { cache: 'webLock' },         // admin 의 memory 락과 다른 backend
+bus:  { nats: 'events', prefix: 'web.' },
+
+// apps/admin/app.config.js — lock/bus 미정의 → 글로벌(memory 락 + glob. 버스)
+```
+
+확인:
+
+- `a.com/whoami` → `lock: redis`, `b.com/whoami` → `lock: memory` (앱별 backend 분리).
+- web 의 `web.` 발행은 admin(`glob.`)이 **못 받음** (prefix 격리, 같은 NATS 라도 subject 공간이 갈림).
+- 같은 키여도 web(redis)·admin(memory)은 다른 manager 라 **서로 격리**됩니다.
+
+## cross-app 호출 (`getApp`, ADR-228)
+
+ctx 가 없거나 다른 앱의 자원이 필요하면 `getApp('<name>')` 로 잡습니다. 멀티앱이면 **이름 필수**(생략 시
+`app.ambiguous`, 없는 이름은 `app.not_found`, 부팅 전은 `app.not_initialized` — 전부 fail-fast).
+
+```js
+import { getApp } from 'mega-framework'
+// web 의 컨트롤러에서 admin 의 (글로벌) 버스로 직접 발행 → b.com/received 에 도착
+await getApp('admin').bus.emit('notice', { from: 'web' })
+```
+
+`getApp('admin').lock`/`bus`/`db(alias)`/`cache(alias)`/`log` 모두 **그 앱의** manager·자원을 가리킵니다.
+
+## 언제 멀티앱(vhost) vs process-per-app
+
+| 기준 | 멀티앱(vhost) | process-per-app |
+| --- | --- | --- |
+| 자원 공유 | 메모리/CPU/이벤트루프 공유 | 완전 분리 |
+| 배포·스케일 | 함께(한 프로세스) | 독립 스케일·독립 배포 |
+| 장애 격리 | 약함(한 프로세스 죽으면 전부) | 강함 |
+| 통신 | 같은 프로세스(`getApp`) | mega-bus(NATS) cross-process |
+| 적합 | admin+public 처럼 묶여 다니는 앱, 같은 도메인 그룹 | 독립 서비스, 다른 스케일/SLA |
+
+**강한 격리**(다른 스케일·장애 격리·다른 backend 전용)가 필요하면 process-per-app + mega-bus(NATS)로 프로세스 간
+통신하세요. 멀티앱은 "같은 프로세스 안에서 논리 분리(다른 host·다른 lock/bus backend·prefix)"까지가 적정선입니다.
+
+## 실행 — `sample/multi`
+
+`sample/multi/README.md` 참고. `/etc/hosts` 에 `a.com`/`b.com` 을 `127.0.0.1` 로 매핑하고 redis·nats 를 띄운 뒤
+`npm run dev`, `http://a.com:3200`(web)·`http://b.com:3200`(admin) 으로 접속합니다.

package/sample/crud/mega.config.js

@@ -111,6 +111,38 @@ export default {
     },
   },
 
+  // ── 분산 락 사용자 API(ADR-226) — `ctx.lock.with/.acquire/.tryAcquire` ─────────────────────────
+  // 위 services.locks(설정형 redlock, `ctx.lock('main')`)와 **별개 하위시스템**이다. 이쪽은 별명 선언 없이
+  // 코드에서 바로 임계구역을 잠근다: `await ctx.lock.with('user:42', { ttl: 5000 }, async () => { ... })`.
+  //
+  // 이 `lock` 블록이 **없어도** ctx.lock.with 는 동작한다 — driver 자동 폴백이 redis 가용 시 redis, 클러스터
+  // 워커면 cluster IPC, 그 외엔 **memory**(단일 프로세스, 부팅 경고)를 고른다. 멀티 프로세스/노드에서 진짜
+  // 분산 락을 쓰려면 아래처럼 **redis cache 별명을 cache 에 지정**한다(추가 .env 불필요 — 기존 caches.lock 재사용).
+  // 이 데모(crud)는 /demo/lock 시연을 위해 redis 분산 락을 켠다(클러스터 워커 간 실 상호배제·FIFO·fence).
+  lock: {
+    driver: 'auto', // 'auto'(기본) | 'redis' | 'cluster' | 'memory'. 명시 시 전제 부재면 부팅 fail-fast.
+    cache: 'lock', // services.caches 의 redis 별명(여기선 caches.lock = REDIS_LOCK_URL). driver redis/auto 시 사용.
+    ttl: 5000, // 락 보유 기본 시간(ms)
+    waitMs: 3000, // 획득 대기 기본 상한(ms, 0 = 즉시 실패). 데모 FIFO 대기가 보이도록 넉넉히.
+    fifo: false, // true = 대기자 도착 순서 보장(기아 방지). subject별 { fifo } 로 덮음.
+  },
+
+  // ── 메시지 버스 사용자 API(ADR-227) — `ctx.bus.emit/.on/.request/.with` ────────────────────────
+  // 위 services.buses(설정형 어댑터, `ctx.bus('jobs')`)와 **별개 하위시스템**이다. 별명 선언 없이 코드에서 바로
+  // 이벤트를 주고받는다: `ctx.bus.emit('order.created', { id })` / `ctx.bus.on('order.*', handler)`.
+  //
+  // 이 `bus` 블록이 **없어도** ctx.bus.emit 은 동작한다 — driver 자동 폴백이 NATS 가용 시 nats, 클러스터 워커면
+  // cluster IPC, 그 외엔 **memory**(단일 프로세스, 부팅 경고)를 고른다. 멀티 프로세스/노드에서 진짜 분산 버스를
+  // 쓰려면 아래처럼 **NATS 버스 별명을 nats 에 지정**한다(추가 .env 불필요 — 기존 buses.jobs 재사용).
+  // 이 데모(crud)는 /demo/bus 시연을 위해 NATS 버스를 켠다(워커 간 fan-out·persist(JetStream)·request/reply).
+  bus: {
+    driver: 'auto', // 'auto'(기본) | 'nats' | 'cluster' | 'memory'. 명시 시 전제 부재면 부팅 fail-fast.
+    nats: 'jobs', // services.buses 의 NATS 별명(여기선 buses.jobs = NATS_JOBS_URL). driver nats/auto 시 사용.
+    prefix: 'app.', // 모든 subject 에 붙는 네임스페이스(충돌 회피). 빈 값이면 그대로.
+    defaultPersist: false, // 기본 비영속. true 면 emit/on 이 기본 JetStream(영속) — subject별 { persist } 로 덮음.
+    requestTimeoutMs: 5000, // request 응답 대기 기본 상한(ms)
+  },
+
   // (예시·미사용) Embedded WS Hub(ADR-137) — `mega ws-hub` 별도 프로세스 대신 같은 프로세스에 허브를 띄움
   //   (single-node). 켜면 app.config.js bridgeHub.url 을 이 host:port 로 맞춘다. acceptedTokens 필수(빈 값=throw).
   // wsHub: {

package/sample/crud/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "dev": "NODE_ENV=development mega start --watch",
@@ -17,12 +17,13 @@
     "test": "mega test"
   },
   "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
     "highlight.js": "^11.11.1",
     "marked": "^18.0.5",
     "mega-framework": "file:../.."
   },
   "devDependencies": {
-    "concurrently": "^9.0.0",
+    "concurrently": "^10.0.3",
     "vitest": "^4.1.8"
   }
 }

package/sample/multi/.env

@@ -0,0 +1,16 @@
+# sample-multi 환경변수 (.env) — 로컬 전용(.gitignore). 실제 docker 인프라 값으로 채움.
+
+# HTTP 포트 — 한 포트로 두 앱(web=a.com, admin=b.com)을 vhost 라우팅한다.
+# 3200 사용(sample/crud 앱 3000·crud ws-hub 3100 과 충돌 회피). 점유된 포트면 boot 가 EADDRINUSE 로 실패.
+PORT=3200
+
+# ── 앱별 lock/bus 백엔드 (ADR-229) ───────────────────────────────────────────
+# web 앱 전용 분산 락 backend(redis) — services.caches.webLock. admin 은 글로벌 memory 락이라 불필요.
+# docker mega-redis 는 비밀번호 필요. db 5 사용(crud 가 0~4 점유: 0 세션·1 demo·2 rate·3 lock·4 cache).
+REDIS_WEBLOCK_URL=redis://:dkTkqkfl12@localhost:6379/5
+# 두 앱이 공유하는 NATS — services.buses.events. web 은 prefix 'web.', admin(글로벌)은 'glob.' 로 격리.
+NATS_EVENTS_URL=nats://localhost:4222
+
+# ── /etc/hosts (a.com / b.com 이미 설정됨) ──────────────────────────────────
+# 미설정이면 /etc/hosts 에 추가: 127.0.0.1 a.com / 127.0.0.1 b.com
+# 접속: http://a.com:3200 (web) / http://b.com:3200 (admin)

package/sample/multi/.env.example

@@ -0,0 +1,17 @@
+# sample-multi 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+
+# HTTP 포트 — 한 포트로 두 앱(web=a.com, admin=b.com)을 vhost 라우팅한다.
+# 3200 사용(sample/crud·sample/simple 이 3000 이라 충돌 회피). 이미 점유된 포트면 boot 가 EADDRINUSE 로 실패한다.
+PORT=3200
+
+# ── 앱별 lock/bus 백엔드 (ADR-229) ───────────────────────────────────────────
+# web 앱 전용 분산 락 backend(redis) — services.caches.webLock. admin 은 글로벌 memory 락이라 불필요.
+REDIS_WEBLOCK_URL=redis://localhost:6379/0
+# 두 앱이 공유하는 NATS — services.buses.events. web 은 prefix 'web.', admin(글로벌)은 'glob.' 로 격리.
+NATS_EVENTS_URL=nats://localhost:4222
+
+# ── /etc/hosts (이미 a.com / b.com 설정돼 있다고 가정) ────────────────────────
+# 미설정이면 아래를 /etc/hosts 에 추가:
+#   127.0.0.1 a.com
+#   127.0.0.1 b.com
+# 그 뒤 http://a.com:3200 (web) / http://b.com:3200 (admin) 으로 접속.